> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oncarbon.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Base URL, authentication, limits, and error format for the Carbon ingest API.

The ingest API accepts batches of canonical events over HTTPS. The [SDK](/documentation/sdk/configuration) uses it under the hood; use it directly from any language that can send JSON.

## Base URL

```text theme={null}
https://ingest.oncarbon.site
```

## Authentication

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

```text theme={null}
Authorization: Bearer <api-key>
```

Create keys in the dashboard under **Settings → API Keys** — see [API keys](/documentation/dashboard/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:

```json theme={null}
{
  "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](/documentation/concepts/delivery).

## 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](/api-reference/endpoints/ingest-events).