API overview - Orbitrage

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 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.

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.

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).

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.

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).

Errors

Errors use OpenAI-style JSON bodies.

Status	When
`401`	Missing, invalid, or revoked API key.
`402`	Organization credits exhausted (free tier). See Billing.
`403`	`byok_key_required` — a frontier model with no enabled key for its vendor (see 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.

// 401
{ "error": { "message": "Invalid or missing API key", "type": "invalid_request_error" } }

// 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, 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

Chat Completions

POST /v1/chat/completions — the main inference endpoint.

Responses

POST /v1/responses — the OpenAI Responses API (Agents SDK).

List models

GET /v1/models — the live catalog for your account.

Images & audio

POST /v1/images/* and /v1/audio/* proxy to the engine’s multimodal endpoints in OpenAI-compatible shapes.

​Base URL

​Authentication

​Request headers

​Response headers

​Errors

​Endpoints

Chat Completions

Responses

List models

Images & audio

Base URL

Authentication

Request headers

Response headers

Errors

Endpoints