API Documentation

POST /api/ingest

Stream log data to the ingestion endpoint.

Example Request

curl -X POST https://guardian.azimuthpro.com/api/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -H "Content-Encoding: gzip" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Session-ID: my-session-123" \
  --data-binary @logs.jsonl.gz

Request Headers

*Either Authorization or X-API-Key must be provided

Successful Response (202 Accepted)

{
  "status": "accepted",
  "message": "Ingest pipeline running",
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "sessionId": "my-session-123"
}

Response Headers

• X-Request-ID: Unique request identifier
• X-Trace-ID: Trace ID for observability
• X-RateLimit-Limit: Maximum requests per minute
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when rate limit resets

Error Responses

{
  "error": "Missing authentication. Provide Authorization: Bearer <token> or x-api-key header",
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

{
  "error": "Invalid API key",
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

{
  "error": "Payload too large: 60000000 bytes (max: 52428800)",
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

{
  "error": "Too many requests",
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "retryAfter": 45
}

Data Formats

JSONL (Newline-Delimited JSON)

Each line is a valid JSON object:

{"timestamp": "2025-10-08T12:00:00Z", "level": "info", "message": "User logged in", "userId": 123}
{"timestamp": "2025-10-08T12:00:01Z", "level": "warn", "message": "High memory usage", "memoryMB": 1024}
{"timestamp": "2025-10-08T12:00:02Z", "level": "error", "message": "API timeout", "endpoint": "/api/users"}

Plain Text

Any UTF-8 text stream:

2025-10-08 12:00:00 INFO User logged in
2025-10-08 12:00:01 WARN High memory usage: 1024MB
2025-10-08 12:00:02 ERROR API timeout on /api/users

Compression

The API supports automatic decompression of the following formats:

• gzip: Content-Encoding: gzip
• brotli: Content-Encoding: br
• deflate: Content-Encoding: deflate

Example with gzip compression:

# Compress logs
gzip -c logs.jsonl > logs.jsonl.gz

# Send compressed logs
curl -X POST https://guardian.azimuthpro.com/api/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -H "Content-Encoding: gzip" \
  --data-binary @logs.jsonl.gz

Rate Limits & Idempotency

Rate Limits

• Default: 120 requests per minute per API key
• Uses token bucket algorithm with Upstash Redis
• Rate limit headers included in all responses
• 429 responses include Retry-After header

Idempotency

Use the Idempotency-Key header to prevent duplicate processing:

curl -X POST https://guardian.azimuthpro.com/api/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  --data '{"message": "test log"}'

• Idempotency keys must be UUID v4 format
• Duplicate requests (same key + API key) within 24 hours return cached response
• Cached responses include X-Idempotent-Replay: true header

System Limits