API Reference

The Astralog Ingestion API is a RESTful service that accepts JSON-formatted event batches. All requests must be authenticated using a secret token.

Base URL

The default base URL for the ingestion engine is:

http://localhost:8080 (Local)
https://ingest.astralog.cloud (Production)

POST /v1/drain

Ingests a batch of event messages into the pipeline.

Authentication

All requests must include the following header: Authorization: <YOUR_AUTH_TOKEN>

Request Body

The request must be a JSON object containing an array of events.

Field	Type	Description
`events`	Array	An array of event objects to be ingested.

Event Object Structure

Field	Type	Required	Description
`project_id`	String	Yes	Unique identifier for the organization or project.
`timestamp`	String	Yes	Event time (Supports RFC3339, ISO8601, and SQL formats).
`level`	String	Yes	Severity level (e.g., info, error, debug).
`service`	String	Yes	The name of the microservice or process.
`message`	String	Yes	The primary event message content.
`metadata`	Object	No	Any key-value pairs of additional context.

Example Request (cURL)

curl -X POST https://ingest.astralog.cloud/v1/drain \
  -H "Authorization: my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "project_id": "org-xyz",
        "timestamp": "2024-05-31T15:30:45Z",
        "level": "info",
        "service": "api-gateway",
        "message": "User logged in",
        "metadata": { "user_id": 123, "ip": "1.1.1.1" }
      }
    ]
  }'

Responses

202 Accepted

The batch has been successfully received and queued for asynchronous processing.

{
  "status": "accepted"
}

401 Unauthorized

The provided Authorization header is missing or incorrect.

400 Bad Request

The request body is not valid JSON or contains malformed/missing required data.

429 Too Many Requests

The server is temporarily saturated (Backpressure). It is recommended to retry with exponential backoff.

{
  "error": "server saturated",
  "code": "backpressure_triggered"
}

Health Checks

GET /health (Internal)

Used by load balancers and orchestrators (like Kubernetes) to verify the service is alive.

Response: 200 OK

Best Practices

Use Official SDKs: We strongly recommend using the official Astralog SDKs whenever possible. They automatically handle batching, retries with exponential backoff, and local buffering to ensure no events are lost during network instability.
Batch Size: If implementing a custom client, we recommend sending batches of 100 to 500 events per request for optimal performance.
Concurrency: Use multiple concurrent HTTP connections if you are ingesting more than 100k events per second from a single source.
Timeouts: Configure your clients with a 10-second timeout to ensure the pipeline remains non-blocking during network congestion.
Exponential Backoff: If you receive a 429 Too Many Requests response, implement a retry strategy to avoid overwhelming the ingestion engine.