ORBDocumentation

Orbit API reference.

A REST API under /v1. Chat completions follow the OpenAI protocol; everything else is Orbit-specific and documented here and in the OpenAPI document.

Quickstart openapi.json

Authentication

Send your key as a bearer token: Authorization: Bearer orb_live_…. Keys are created in the app or with POST /v1/keys, shown once, and stored only as an HMAC-SHA256 hash with a server-side pepper. Each key has scopes (inference, balance:read, usage:read, agents:read, agents:write, keys:write, tools, payments) and may be bound to an agent, capped in spend, restricted to models, or given an expiry.

Chat completions

POST /v1/chat/completions accepts the OpenAI request body. Use model: "orbit/auto" for routing or any catalog id. stream: true returns server-sent events. Responses add an orbit object:

cURL

curl https://<your-orbit-host>/v1/chat/completions \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "orbit/auto",
    "messages": [{ "role": "user", "content": "Summarise this incident report." }],
    "max_tokens": 800
  }'

Response with orbit metadata

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "anthropic/claude-sonnet-5.5",
  "choices": [ … ],
  "usage": { "prompt_tokens": 412, "completion_tokens": 288, "total_tokens": 700 },
  "orbit": {
    "request_id": "req_…",
    "model": "anthropic/claude-sonnet-5.5",
    "routing": { "mode": "coding", "tier": 3, "explanation": "auto → coding · …", "fallback_used": false },
    "cost": { "estimated_usd": "…", "charged_usd": "…", "provider_cost_usd": "…", "fee_usd": "…" }
  }
}

orbit.request_id, orbit.model
orbit.routing — mode, tier, explanation, fallback_used
orbit.cost — estimated_usd, charged_usd, provider_cost_usd, fee_usd

Endpoint reference

Inference

Endpoint	Description	Scope
POST`/v1/chat/completions`	OpenAI-compatible chat completion. Supports stream: true. Returns an orbit metadata object.	inference
GET`/v1/models`	Model catalog with prices, capabilities and availability.	public
POST`/v1/route/preview`	Preview Orbit Auto's choice and cost for a prompt. Never calls a model.	public, rate-limited
GET`/v1/requests/:id`	A past request: model, tokens, routing decision and cost.	usage:read

Balance & usage

Endpoint	Description	Scope
GET`/v1/balance`	Available and reserved credits by funding source.	balance:read
GET`/v1/usage`	Recent usage and spend.	usage:read

Keys

Endpoint	Description	Scope
POST`/v1/keys`	Create a key (optionally agent-bound, spend-capped, model-restricted). The secret is returned once.	keys:write
GET`/v1/keys`	List keys (prefix and metadata only).	any key
DELETE`/v1/keys/:id`	Revoke a key.	keys:write

Agents

Endpoint	Description	Scope
GET`/v1/agents`	Agents visible to the caller.	agents:read
POST`/v1/agents`	Create an agent with a policy template or custom limits and an initial allocation.	agents:write
GET`/v1/agents/:id`	One agent with its policy and balances.	agents:read
PATCH`/v1/agents/:id`	Update name, status or (owners only) policy.	agents:write

Payments

Endpoint	Description	Scope
POST`/v1/payments/authorize`	Authorize (and optionally capture) a payment. Requires an Idempotency-Key header.	payments
GET`/v1/payments`	List payments.	payments

Tools

Endpoint	Description	Scope
GET`/v1/tools`	Built-in and approved marketplace tools with availability.	public
POST`/v1/tools/:id/execute`	Execute a tool; paid tools are charged via Orbit Pay.	tools

Create an agent

curl https://<your-orbit-host>/v1/agents \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-agent",
    "initial_allocation_usd": "10",
    "policy": { "template": "research" }
  }'

Authorize a payment

curl https://<your-orbit-host>/v1/payments/authorize \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Idempotency-Key: 8f1c2d4e-run-42-step-3" \
  -H "Content-Type: application/json" \
  -d '{ "payee": { "type": "tool", "id": "<tool-id>" }, "amount_usd": "0.02", "memo": "search call" }'

Errors

Errors share one shape. Include the request_id when contacting support.

Error body

{
  "error": {
    "type": "billing_error",
    "code": "daily_limit",
    "message": "agent daily spending limit reached",
    "request_id": "req_…"
  }
}

Code	HTTP	Meaning
validation_error	400	The request body or parameters are invalid.
invalid_api_key	401	Missing, malformed or unknown API key.
key_revoked	401	The key was revoked or has expired.
insufficient_balance	402	Available balance cannot cover the worst-case reservation.
daily_limit	402	The agent (or an ancestor) would exceed its daily cap.
monthly_limit	402	The agent (or an ancestor) would exceed its monthly cap.
per_request_limit	402	The request's worst-case cost exceeds the per-request maximum.
key_spend_cap	402	The API key's spend cap is reached.
forbidden	403	The key lacks the required scope or ownership.
model_not_allowed	403	The model is outside the key's or agent's allowlist.
agent_paused	403	The agent or one of its ancestors is paused.
no_eligible_model	422	Orbit Auto found no model satisfying every hard constraint.
rate_limited	429	Too many requests (or the loop breaker is throttling).
loop_detected	429	The loop breaker paused the agent.
provider_error	502	The upstream provider failed and no cheaper-or-equal fallback succeeded.

Billing behaviour

Reserve the worst case. Before calling a provider, Orbit reserves the prompt-token estimate plus max_tokens at the model's prices, plus the platform fee. If max_tokens is omitted, a default of 4,096 (capped by the model's output limit) is used.
Settle on reported usage. The charge is computed from the provider-reported token counts, not Orbit's estimate.
Release the remainder. The unused part of the reservation returns to your available balance immediately. Stale reservations expire.
Streaming disconnects. If the client disconnects mid-stream, only the tokens actually generated are billed.
Failures. If a request fails before any output, the reservation is released and nothing is charged.

All amounts are integers in nano-USD internally and rounded up to the nearest nano-dollar. See pricing for fees.

Rate limits

POST /v1/route/preview without a key: about 20 requests per minute per IP (operator-configurable).
Authenticated endpoints are limited per key; agents are additionally protected by the loop breaker (120 requests, 10 identical requests or 20 errors per minute by default).
Exceeding a limit returns 429 with code rate_limited (or loop_detected when an agent is paused).

OpenAPI

The machine-readable description is served by the API at /api/openapi.json (or https://<your-orbit-host>/openapi.json on the API host). It is the source of truth for request and response schemas.

Looking for MCP or SDK setup? See the developer hub.