ReferenceBeta
API reference
The OpenAI-compatible surface plus the Omnious extensions: analytics, market data, integrity, points, orders.
The customer-facing API is OpenAI-compatible. Use the guided section below to build an integration, then use this page as the canonical endpoint index when you need to find a specific route.
Guided API section
Start hereBase URL, first request, payment rails, and the overall request lifecycle.Authentication & x402402 negotiation, exact versus upto payments, credits, keys, and wallet safety.Chat & inferenceCompletions, streaming, routing controls, and response headers.Computer useLocal CUA execution with API-routed reasoning, intent checks, approvals, and screenshots.Market data & analyticsPublic market reads, chart feeds, receipts, economics, and SSE snapshots.Sessions & operationsBudget sessions, API keys, patient orders, retries, and resumable streams.
How the core request works
POST /v1/chat/completions works as a drop-in base_url swap for existing apps and agent frameworks, on the mainnet launch surface. Direct x402 is the default payment path: an unpaid request answers 402 Payment Requiredwith an accepts array, then the client signs and retries with PAYMENT-SIGNATURE. Invited funded keys may usex-credit-key. Payload details are in Wire formats.
Auth in the table below: pay means prepaid credit or direct x402 payment, none needs no existing credential,pub is a public read, key reads your own data via x-api-key, sig is a wallet typed-data signature, and provider is a quote signed by a registered provider key. context means the passport's bearer x-context-token, and device is the short-lived agent setup code. task means the one-time x-task-token capability (or the owning governed key). credit requires a spend-capable key and returns only requests attributed to that key. Admin surfaces (/v1/admin/*) exist but are operator-token gated and not listed here.
Canonical endpoint index
| Endpoint | Auth | Purpose |
|---|---|---|
POST /v1/chat/completions | pay | OpenAI-compatible completions; the core paid surface |
POST /v1/responses | pay | OpenAI Responses items and events for Codex and agent harnesses |
POST /v1/messages | pay | Anthropic Messages compatibility for Claude Code and native clients |
POST /v1/messages/count_tokens | pub | local prompt-token estimate; does not start an auction |
GET /v1/context/passports/:id | off | Not enabled in the V1 mainnet launch |
DELETE /v1/context/passports/:id | off | Not enabled in the V1 mainnet launch |
POST /v1/tasks | none | Create a retained durable task and receive its capability once |
GET /v1/tasks/:id | task | Read task state, latest checkpoint, approvals, and unresolved effects |
GET /v1/tasks/:id/events | task | Cursor-based ordered events with bounded long polling |
POST /v1/tasks/:id/claim | task | Claim or recover the task with a renewable worker lease |
POST /v1/tasks/:id/checkpoints | task | Persist resumable execution and context state |
POST /v1/tasks/:id/effects/:effectId/begin | task | Write-ahead receipt for exactly-once side effects |
DELETE /v1/tasks/:id | task | Immediately erase a task and all dependent records |
POST /v1/images/generations | pay | Paid GPT Image generation; one image is billed per request |
POST /v1/embeddings | off | Not enabled in the V1 mainnet launch |
POST /v1/orders | off | Not enabled in the V1 mainnet launch |
GET /health | pub | router status, chain network, auction version |
GET /v1/models | pub | model classes with live depth and prices |
POST /v1/routing/preview | pub | router-owned six-profile winners, score breakdowns, candidate counts, and data maturity |
GET /v1/market/book | pub | anonymized ask ladder per class |
GET /v1/market/stats | pub | rolling clearing summary (24h window) |
GET /v1/market/snapshot | pub | full point-in-time market snapshot |
GET /v1/market/candles | pub | cleared-price OHLC and VWAP candles |
GET /v1/market/index | pub | composite price index and component weights |
GET /v1/receipts/:id | pub | the signed usage record for a request |
GET /v1/analytics/requests/:id | pub | reconstructed auction: rivals, counterfactuals, fee split |
GET /v1/auctions/latest | credit | key-scoped RFQ tape, replay, run tree, and versioned JSON |
GET /v1/analytics/sessions/:id | pub | per-turn session tape and cache discount captured |
GET /v1/analytics/market | pub | per-class cleared prices, HHI, latency |
GET /v1/analytics/providers/:id | pub | a provider's served volume and reliability |
GET /v1/analytics/task-fit | pub | aggregate model/task quality evidence used by automatic routing |
GET /v1/analytics/dashboard | pub | bucketed chart feed |
GET /v1/analytics/leaderboard | pub | providers ranked by cleared volume |
GET /v1/model-integrity/claims/:id | pub | Shadow: a provider's declared model claim; bond_amount is metadata, not escrow |
GET /v1/model-integrity/challengers/:wallet | pub | Shadow: approved-reviewer status for a wallet |
GET /v1/model-integrity/challenges/quote | off | Shadow only; not enabled in the V1 mainnet launch |
POST /v1/model-integrity/challenges | off | Shadow only; not enabled in the V1 mainnet launch |
GET /v1/points/:wallet | pub | mainnet Season One wallet score, tier, rank, and settled/pending earn |
GET /v1/points/leaderboard | pub | mainnet Season One customer leaderboard |
GET /v1/points/provider/:id | pub | mainnet Season One provider score and earn |
POST /v1/points/follow | sig | one-time 100-GPU @Omniousai follow-intent reward |
POST /v1/points/demo-share | sig | one-time 250-GPU Omnious demo-share intent reward |
GET /v1/orders/:id | pub | order state: funding, resting, filled, expired |
POST /v1/orders/:id/cancel | sig | cancel a resting order; escrow refunds at epoch close |
GET /v1/sessions/:id | pub | session state and remaining budget |
POST /v1/sessions/:id/close | sig | close a session; unspent budget refunds |
POST /v1/agent-setup/sessions | none | Start a short-lived, wallet-bounded harness setup |
GET /v1/agent-setup/sessions/:code | device | Read the exact setup terms awaiting wallet approval |
POST /v1/agent-setup/sessions/:code/approve | sig | Approve the displayed harness, network, budget, and expiry |
POST /v1/agent-setup/token | device | Exchange an approved device code once for its governed spend key |
POST /v1/keys | sig | mint an API key bound to your wallet |
GET /v1/keys/usage | key | per-key request and spend attribution |
POST /v1/credits/deposits | pay | fund prepaid credits with an exact on-chain USDC payment |
GET /v1/credits/balance | key | read the unified API balance accessible to a spend-capable key |
POST /v1/credits/withdrawals | sig | withdraw prepaid credits as HyperEVM USDC to an EVM wallet |
POST /v1/routing/feedback/:id | stream | record explicit response quality using the request's stream capability |
POST /provider/quotes | provider | signed standing-quote ingest (the maker side) |
noteProviders do not have to speak OpenAI upstream. The router translates to Anthropic-dialect backends (
/v1/messages) and back before the metering tap, so metering, billing, analytics, and the customer never know which dialect the winning backend spoke. Customers always see the OpenAI surface.Core customer endpoints have typed methods in the SDK.
where this lives in code
- router/src/http/server.ts every route, in one file
- router/src/api/protocol.ts OpenAI to Anthropic translation