Skip to main content
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.
HeaderPurpose
x-orbitrage-end-user-idAttribute the call to one of your end-users.
x-orbitrage-run-idGroup calls into one session/run.
x-orbitrage-session-idA session identifier within a run.
x-orbitrage-workflow-idOverride the key’s workflow (advanced).
x-orbitrage-customer-id / x-orbitrage-tenant-idMulti-tenant identifiers.
x-orbitrage-parent-request-idParent span, to build call graphs.
x-orbitrage-step-indexPosition of this call in a sequence.
x-orbitrage-prompt-idRender 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:
HeaderMeaning
X-Orbitrage-Overhead-MsLatency Orbitrage added on top of the provider call.
X-Orbitrage-BYOKThe BYOK provider used, or pooled.
X-Orbitrage-BYOK-ReasonWhy BYOK did or didn’t apply (see BYOK).

​
Errors

Errors use OpenAI-style JSON bodies.
StatusWhen
401Missing, invalid, or revoked API key.
402Organization credits exhausted (free tier). See Billing.
403Spoofed x-orbitrage-user-id / failed edge signature.
4xxPassed through from the provider (e.g. bad request, content filter).
5xxUpstream/infrastructure error; the router may have already tried fallbacks.
// 401
{ "error": { "message": "Invalid or missing API key", "type": "invalid_request_error" } }

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