Introduction - Carbon

The ingest API accepts batches of canonical events over HTTPS. The SDK uses it under the hood; use it directly from any language that can send JSON.

Base URL

https://ingest.oncarbon.site

Authentication

Authenticate every request with an API key as a bearer token:

Authorization: Bearer <api-key>

Create keys in the dashboard under Settings → API Keys — see API keys. The key determines the space your events land in. Requests with a missing, malformed, or revoked key return 401.

Request limits

Limit	Value
Maximum request body	4 MiB
Maximum events per request	500

Requests over either limit return 413. Split large workloads into multiple batches.

Errors

Every error response has the same shape:

{
  "error": {
    "id": "unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "details": "Missing or invalid API key."
  }
}

`error.id`	Status	Meaning
`invalid_request_body`	400	Body is missing or not valid JSON
`invalid_event_batch`	400	JSON does not match `{ events: [...] }` with valid events
`unauthorized`	401	Missing or invalid API key
`batch_too_large`	413	Request body exceeds 4 MiB
`too_many_events`	413	More than 500 events in one request
`internal_server_error`	500	Unexpected server error
`ingest_unavailable`	503	Ingest is temporarily unavailable

Retries

Retry on 5xx, 503, and network failures, with backoff.
Do not retry 400, 401, or 413 — fix the request instead.
Reuse the same event id values when retrying. Events are deduplicated by ID, so retries never create duplicates — see Delivery guarantees.

Success

A successful request returns 202 Accepted: events are validated and durably queued, and will appear in the dashboard within seconds. See POST /v1/ingest-events.

​Base URL

​Authentication

​Request limits

​Errors

​Retries

​Success