API Reference

The AstraLog Ingestion API is a RESTful service that accepts JSON-formatted log batches. All requests must be authenticated using a Bearer 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 log 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 logs.

Field	Type	Description
`logs`	Array	An array of log objects to be ingested.

Log 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 log 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 '{
    "logs": [
      {
        "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

200 Accepted

{
  "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 data.

Health Checks

GET `/health` (Internal)

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

Response: 200 OK

Best Practices

Batch Size: For optimal performance, we recommend sending batches of 100 to 500 logs per request.
Concurrency: Use multiple concurrent HTTP connections if you are ingesting more than 100k logs 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.