EventLoomer API Reference

This document provides detailed information about the EventLoomer API endpoints for log ingestion.

Authentication

All log ingestion API requests require authentication using a Team API key. Include your API key in the X-API-Key request header:

X-API-Key: your-team-api-key

The API validates this key against the Team associated with the target Event, Step, or Project specified in the request body.

Endpoint Base URL

All API routes are relative to your EventLoomer instance's base URL (e.g., https://api.eventloomer.com).

Response Format

These specific log ingestion endpoints (/api/ExternalLogs and /api/ApplicationLogs) are designed to always return an HTTP 200 OK status, even in cases of client-side errors (like missing fields, invalid keys, or entity not found).

The actual success or failure of the log ingestion is indicated within the JSON response body. Client applications must check the success field in the response body.

Success Response Example (ExternalLogs & Single ApplicationLogs):

{
    "success": true,
    "data": {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef" // ID of the created log entry
    }
}

Success Response Example (Batch ApplicationLogs):

{
    "success": true,
    "data": {
        "message": "Successfully processed 9 log entries",
        "count": 9
    }
}

Error Response Example:

{
    "success": false,
    "error": {
        "code": "missing_api_key", // Machine-readable error code
        "message": "API key is required.", // Human-readable message
        "details": null // Optional additional details
    }
}

External Logs API (/api/ExternalLogs)

Use this endpoint to send logs associated with specific Events or Steps that you have defined within EventLoomer using their unique identifiers. Logs sent here appear in the Event Logs view and contribute to the Event Flow visualization when a correlationKey is provided.

Send Single External Log

Sends a log entry tied to a predefined Event or Step uniqueIdentifier.

POST /api/ExternalLogs

Headers:

• X-API-Key: Your Team's API Key.
• Content-Type: application/json

Request Body (ExternalLogDto):

{
    "uniqueIdentifier": "order-processed", // REQUIRED: The UniqueIdentifier of the Event or Step
    "payload": "{\"orderId\": 123, \"status\": \"Shipped\"}", // REQUIRED: The log message or serialized data (e.g., JSON string)
    "level": "Information", // REQUIRED: Log severity level (see Log Levels below)
    "correlationKey": "corr-xyz-789", // OPTIONAL: Key to group related logs across steps/events
    "environment": "Production" // OPTIONAL: Environment name (e.g., "Production", "Staging"). Defaults to "Development" if not provided.
}

• uniqueIdentifier (string, required): The predefined unique string identifier for the Event or Step this log belongs to.
• payload (string, required): The main content of the log message. This can be plain text or a JSON string.
• level (string, required): The severity level of the log. Must match one of the defined Log Levels (case-insensitive).
• correlationKey (string, optional): An identifier used to link this log with others in the same process flow or transaction.
• environment (string, optional): The environment where the log originated (e.g., "Production", "Staging", "QA"). Defaults to "Development" if omitted.

Possible error.code values in the 200 OK JSON response:

• missing_api_key: X-API-Key header was not provided.
• missing_identifier: uniqueIdentifier field was missing or empty.
• missing_payload: payload field was missing or empty.
• invalid_log_level: level field contained an unrecognized value.
• entity_not_found: No Event or Step found matching the provided uniqueIdentifier.
• team_not_found: Internal error indicating the team associated with the event/step could not be found.
• invalid_api_key: The provided X-API-Key does not match the key for the Team associated with the Event/Step.
• server_error: An unexpected internal error occurred during processing.

Application Logs API (/api/ApplicationLogs)

Use this endpoint to send general application logs associated with a Project. This endpoint is primarily used by the EventLoomer .NET SDK's ILogger provider but can be called directly. Logs sent here appear in the Application Logs view.

Send Single Application Log

Sends a single log entry associated with a Project ID.

POST /api/ApplicationLogs

Headers:

• X-API-Key: Your Team's API Key (The API uses the uniqueIdentifier in the body to find the Project and then validates the key against that Project's Team).
• Content-Type: application/json

Request Body (LogEntryDto):

{
    "uniqueIdentifier": "f47ac10b-58cc-4372-a567-0e02b2c3d479", // REQUIRED: The Project ID (as a GUID string)
    "categoryName": "MyApp.Services.EmailService", // REQUIRED: Source category (e.g., logger category name)
    "eventId": 1001, // OPTIONAL: Numeric Event ID from ILogger (defaults to 0)
    "eventName": "EmailSent", // OPTIONAL: String Event Name from ILogger (defaults to empty)
    "message": "Email sent successfully to user@example.com", // REQUIRED: The primary log message
    "level": "Information", // REQUIRED: Log severity level (see Log Levels below)
    "exception": "System.Exception: Details...", // OPTIONAL: String representation of an exception (including stack trace)
    "scopeData": { "UserId": "user-123", "TenantId": "tenant-abc" }, // OPTIONAL: JSON object/document representing ILogger scope data
    "correlationKey": "req-abc-123", // OPTIONAL: Key to group related logs
    "environment": "Staging" // OPTIONAL: Environment name. Defaults to "Development".
}

• uniqueIdentifier (string, required): The Project ID (as a GUID string) this log belongs to.
• categoryName (string, required): Typically the source of the log, often the fully qualified class name when using ILogger.
• eventId (integer, optional): The numeric ID associated with the log event (from Microsoft.Extensions.Logging.EventId).
• eventName (string, optional): The name associated with the log event (from Microsoft.Extensions.Logging.EventId).
• message (string, required): The primary log message content.
• level (string, required): The severity level (see Log Levels below).
• exception (string, optional): A string representation of any associated exception, including the stack trace.
• scopeData (JSON object/document, optional): Structured data representing the logging scope information.
• correlationKey (string, optional): An identifier to link related log entries.
• environment (string, optional): The environment where the log originated. Defaults to "Development".

Send Batch Application Logs

Sends multiple application log entries associated with the same Project ID in a single request.

POST /api/ApplicationLogs/batch

Headers:

• X-API-Key: Your Team's API Key.
• Content-Type: application/json

Request Body (BatchLogEntryDto):

{
    "uniqueIdentifier": "f47ac10b-58cc-4372-a567-0e02b2c3d479", // REQUIRED: The Project ID for ALL logs in this batch
    "logEntries": [
        {
            "categoryName": "MyApp.Services.AuthService",
            "eventId": 200,
            "eventName": "LoginAttempt",
            "message": "User login attempt failed for user@example.com",
            "level": "Warning",
            "exception": null,
            "scopeData": { "IPAddress": "192.168.1.100" },
            "correlationKey": "req-def-456",
            "environment": "Production",
            "timestamp": "2023-10-27T11:00:00Z" // Optional: ISO 8601 timestamp
        },
        {
            "categoryName": "MyApp.Data.UserRepository",
            "eventId": 201,
            "eventName": null,
            "message": "User record updated.",
            "level": "Information",
            "exception": null,
            "scopeData": { "UserId": "user-456" },
            "correlationKey": "req-ghi-789",
            "environment": "Production",
            "timestamp": null // Defaults to server receive time
        }
        // ... more log entries up to batch limit (e.g., 100)
    ]
}

• uniqueIdentifier (string, required): The Project ID (as a GUID string) that applies to all log entries within this batch.
• logEntries (array, required): An array of log entry objects. Each object has the same structure as the single ApplicationLogs request body (LogEntryDto), with the addition of an optional timestamp field.
  • timestamp (string, optional): An ISO 8601 formatted timestamp (e.g., "2023-10-27T10:30:00Z"). If omitted or null, the server's receive time will be used.

Possible error.code values in the 200 OK JSON response (for both single and batch):

• missing_project_id: uniqueIdentifier (Project ID) was missing or empty.
• invalid_project_id: uniqueIdentifier was not a valid GUID format.
• missing_api_key: X-API-Key header was missing.
• project_not_found: No Project found matching the provided uniqueIdentifier.
• invalid_team_config: Internal error - the Team associated with the Project has no API key configured.
• invalid_api_key: The provided X-API-Key does not match the key for the Team associated with the Project.
• invalid_log_level: level field in one or more log entries contained an unrecognized value (batch processing may continue for valid entries).
• server_error: An unexpected internal error occurred during processing.

Log Levels

The level field in the request bodies accepts the following string values (case-insensitive):

• Trace
• Debug
• Information (Default if invalid level provided)
• Warning
• Error
• Critical

---