Not Organic / Integration guides
API reference
A route and capability map for the gateway, with the implementation limits that matter to callers.
Account and access
| Endpoint | Required capability | Purpose |
|---|---|---|
GET /healthz | None | Store readiness; 200 or 503. |
POST /v1/auth/token/exchange | Product assertion | Exchange once for a 300-second token. |
POST /v1/public/token | Code + PKCE | Public-client token exchange. |
GET /v1/account | Authenticated | Account details for the token owner. |
GET /v1/models | Authenticated | Enabled aliases; not an upstream health check. |
GET /v1/wallet | wallet:read | Available credits and account balance. |
GET /v1/usage | usage:read | Usage records; optional limit. |
POST /v1/billing/checkout | billing:checkout | Hosted checkout URL. |
“Authenticated” means DPoP authorization is still required even when no additional capability is checked. Routes are account-scoped; a client cannot select another account by sending a DID in the body.
Model requests
| Endpoint | Capability | Response |
|---|---|---|
POST /v1/responses | infer:<alias> | Responses-shaped JSON or SSE when supported. |
POST /v1/chat/completions | infer:<alias> | Chat JSON or SSE. |
POST /v1/embeddings | infer:<alias> | Embedding result. |
POST /v1/images/generations | infer:<alias> | Image result. |
POST /v1/audio/speech | infer:<alias> | Audio response. |
POST /v1/audio/transcriptions | infer:<alias> | Multipart transcription request. |
POST /v1/audio/translations | infer:<alias> | Multipart translation request. |
GET /v1/realtime | realtime:connect | WebSocket upgrade; consent and adapter required. |
The body’s model alias selects the inference scope: a request for balanced needs infer:balanced. Aliases include fast, balanced, reasoning, vision, embedding, image, audio, and realtime. Enabled routes and provider capabilities determine which combinations work. Raw models require explicit authorization and allowlisting.
Metered requests need Idempotency-Key and x-notorganic-max-cost-microusd. Use JSON for JSON endpoints and multipart form data where the audio route requires it. OpenAI-shaped requests do not imply complete parity with every OpenAI endpoint or SDK feature.
The SDK’s chat helper supports an async iterable for streaming. Its responses.create helper parses JSON; consume a streaming Responses request with a streaming-capable HTTP client instead of assuming that helper returns an iterable.
Stored responses
| Endpoint | Capability | Notes |
|---|---|---|
GET /v1/responses/:responseId | responses:read | Read an unexpired response owned by the account. |
DELETE /v1/responses/:responseId | responses:delete | Delete the gateway record. |
GET /v1/responses/:responseId/input_items | responses:read | Accepts after and limit. |
Missing or inaccessible response records are not returned across account boundaries. The response store defaults to a 30-day expiry. See storage semantics.
Optional execution and evolution
| Endpoint group | Capabilities | Configuration |
|---|---|---|
/v1/projects and /v1/projects/:projectId/execution-config | projects:read, projects:configure | List/get project configuration; PUT validates the account and product. |
/v1/sandbox/runs, /:runId, /:runId/cancel | sandbox:run, sandbox:read, sandbox:cancel | POST creates (202); GET reads; POST cancels. Requires execution registry and runner. |
/v1/ci/runs and /:runId | ci:read | GET durable run status; requires CI registry. |
/v1/evolution/artifacts, /evidence, /jobs, /active-revision | evolution:read, evolution:write, evolution:execute | Account-scoped artifacts, evidence, job scheduling, and revision activation. |
POST /v1/sync/account-key | sync:key:read | Wraps account key material for the requesting public key. |
These are optional first-party integrations, not a public grant of execution access. Their full request schemas live in packages/contracts/src/{sandbox,project-execution,account-evolution,account-sync}.ts. Use those schemas rather than guessing a body from this route index.
Pagination and compatibility
List routes validate limit in the range 1–100. Use each route’s actual response shape; not every list exposes a cursor. In particular, the current Convex-backed usage adapter returns a limited list and does not implement the SDK’s after cursor. Do not build an infinite history view assuming that cursor advances.
The API is implemented under /v1. Treat new or optional routes as integration-specific until deployed and tested. Keep response parsing tolerant of additional fields while validating the fields your application relies on.