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

# API overview

> Base URL, authentication, headers, and errors for the Orbitrage gateway.

The Orbitrage gateway is **OpenAI-compatible**. If your code already talks to
the OpenAI API, point it at Orbitrage by changing one base URL — the request and
response bodies are byte-for-byte the OpenAI shapes.

## Base URL

```
https://api.orbitrage.ai/v1
```

The gateway speaks the OpenAI Chat Completions and Responses APIs, a model
catalog endpoint, and (through the engine) images and audio. To use Claude,
Gemini, Grok, or any other model, just name it in a chat-completions call —
Orbitrage routes and translates to that provider for you.

## Authentication

Send your [API key](/account/api-keys) as a bearer token:

```
Authorization: Bearer orb_<prefix>_<secret>
```

Keys are workflow-scoped; the gateway derives your organization, workflow, and
user from the key. Invalid or revoked keys return `401`.

<Tip>
  The SDKs set this header for you — `orbitrage.init(key)` is all you need. Use
  raw HTTP only when you can't use an SDK.
</Tip>

## Request headers

All optional — set them to enrich attribution. The SDK sets the run id and (when
configured) the end-user id automatically.

| Header                                              | Purpose                                                      |
| --------------------------------------------------- | ------------------------------------------------------------ |
| `x-orbitrage-end-user-id`                           | Attribute the call to one of your end-users.                 |
| `x-orbitrage-run-id`                                | Group calls into one session/run.                            |
| `x-orbitrage-session-id`                            | A session identifier within a run.                           |
| `x-orbitrage-workflow-id`                           | Override the key's workflow (advanced).                      |
| `x-orbitrage-customer-id` / `x-orbitrage-tenant-id` | Multi-tenant identifiers.                                    |
| `x-orbitrage-parent-request-id`                     | Parent span, to build call graphs.                           |
| `x-orbitrage-step-index`                            | Position of this call in a sequence.                         |
| `x-orbitrage-prompt-id`                             | Render a registered prompt by id (overrides messages/model). |

<Warning>
  Don't send `x-orbitrage-user-id`. It's the gateway's authoritative account
  identity and is signature-protected — sending your own value returns `403`.
  Use `x-orbitrage-end-user-id` instead.
</Warning>

A standard W3C `traceparent` header is also honored — its trace id seeds the run
id and its span id seeds the parent request id when you don't set them explicitly.

## Response headers

On top of the provider's headers, the gateway adds:

| Header                    | Meaning                                                    |
| ------------------------- | ---------------------------------------------------------- |
| `X-Orbitrage-Overhead-Ms` | Latency Orbitrage added on top of the provider call.       |
| `X-Orbitrage-BYOK`        | The BYOK provider used, or `pooled`.                       |
| `X-Orbitrage-BYOK-Reason` | Why BYOK did or didn't apply (see [BYOK](/concepts/byok)). |

## Errors

Errors use OpenAI-style JSON bodies.

| Status | When                                                                                                                                                                                                                         |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, or revoked API key.                                                                                                                                                                                        |
| `402`  | Organization credits exhausted (free tier). See [Billing](/account/billing).                                                                                                                                                 |
| `403`  | `byok_key_required` — a frontier model with no enabled key for its vendor (see [BYOK](/concepts/byok)); `pro_plan_required` — a Cerebras model on the free plan; or a spoofed `x-orbitrage-user-id` / failed edge signature. |
| `4xx`  | Passed through from the provider (e.g. bad request, content filter).                                                                                                                                                         |
| `5xx`  | Upstream/infrastructure error; the router may have already tried fallbacks.                                                                                                                                                  |

```json theme={null}
// 401
{ "error": { "message": "Invalid or missing API key", "type": "invalid_request_error" } }
```

```json theme={null}
// 403 — frontier model, no enabled provider key on this organization
{
  "error": {
    "message": "claude-sonnet-4-6 is a bring-your-own-key model. Add and enable an Anthropic key on the Models page to use it.",
    "type": "permission_error",
    "code": "byok_key_required",
    "requested_model": "claude-sonnet-4-6",
    "provider": "anthropic"
  }
}
```

To fix it, save **and enable** a key for `error.provider` on the
[Models page](https://app.orbitrage.ai/models), then retry unchanged. Orbitrage
never silently substitutes pooled inference for a frontier model, so this error is
always actionable rather than a surprise bill.

## Endpoints

<CardGroup cols={2}>
  <Card title="Chat Completions" icon="comments" href="/api-reference/chat-completions">
    `POST /v1/chat/completions` — the main inference endpoint.
  </Card>

  <Card title="Responses" icon="reply" href="/api-reference/responses">
    `POST /v1/responses` — the OpenAI Responses API (Agents SDK).
  </Card>

  <Card title="List models" icon="list" href="/api-reference/list-models">
    `GET /v1/models` — the live catalog for your account.
  </Card>

  <Card title="Images & audio" icon="image">
    `POST /v1/images/*` and `/v1/audio/*` proxy to the engine's multimodal
    endpoints in OpenAI-compatible shapes.
  </Card>
</CardGroup>