Request headers
Every header the gateway reads and every header it sends back — auth, client identity, caching, effort, thinking, sessions, tasks, cost.
All codai headers are optional and case-insensitive. Send them on POST /v1/chat/completions, POST /v1/messages and POST /v1/responses (the Responses route forwards every X-Codai-* header to the chat route it re-enters). Anything you send that the gateway does not understand is ignored.
Authentication
| Header | Value |
|---|---|
Authorization | Bearer codai_… — your API key, or an ephemeral codai_eph_v1.… token on the media surfaces. Required everywhere except the public /vscode/*, /copilot/*, /health and /status endpoints. |
x-api-key | Accepted on POST /v1/messages only, for Anthropic SDKs. Authorization wins if both are present. |
anthropic-version, anthropic-beta, openai-beta | Passed through where the upstream expects them. |
A missing or unknown key is 401 invalid_api_key. A key from an inactive subscription is 402 subscription_inactive.
Client identity
| Header | Effect |
|---|---|
X-Codai-Client | Who is calling, as <surface>/<version> — desktop/1.4.0, phone-android/0.9.2, codai-cli/0.3.0, hub/…. Drives task attribution: desktop and cli may self-report task outcomes; everything else (IDEs, raw SDKs, curl) is proxy and its tasks close only on explicit user confirmation in the hub. Falls back to the User-Agent when absent. |
X-Request-Id | Your own correlation id. Echoed back as x-codai-trace-id, forwarded to the upstream, and usable as client_request_id in POST /v1/feedback. |
X-Codai-Repo | Repository identifier for memory scoping. When absent the gateway infers scope from the transcript. |
X-Codai-Agent-Id | Attribution id recorded on tool calls in agent fleets. [A-Za-z0-9._:-], max 128 chars. |
Caching
| Header | Effect |
|---|---|
X-Codai-Cache | Prompt caching is on by default for every model. 0 or false turns it off — except on codai* aliases, where the opt-out is ignored. Cache reads cost roughly a tenth of fresh input, and an uncached 170 k-token agent loop once cost one user thousands of dollars a day, so the router alias does not let you disable it. |
Response side: x-codai-cache-read and x-codai-cache-write carry the cache token counts when known before the first byte; usage.prompt_tokens_details.cached_tokens carries the final read count in the body.
Effort and thinking
| Header | Effect |
|---|---|
X-Codai-Effort | minimal · low · medium (default) · high · max. Wins over the body's reasoning_effort. See models. |
X-Codai-Thinking | 1 or true enables extended thinking explicitly. |
X-Codai-Thinking-Budget | Thinking budget in tokens (positive integer, default 16 384). |
X-Codai-Thinking-Pin | 1 keeps the full thinking budget on tool-continuation turns. Without it the gateway clamps injected budgets to 4 096 tokens on turns whose last message is a tool result, so agent loops do not pay max on every step. |
Response side: x-codai-effort, x-codai-effort-applied, x-codai-effort-continuation-dampened.
Sessions and memory
| Header | Effect |
|---|---|
X-Codai-Session-Id | Stable id for a logical conversation. Enables sticky routing (keeps prompt caches warm), per-session cost roll-ups in GET /v1/receipt, and session memory. Header beats body.user. IDE clients usually omit it; the gateway then derives a key from the transcript. |
X-Codai-New-Session | 1 starts a brand-new persistent session with a fresh id, ignoring any X-Codai-Session-Id. |
X-Codai-No-Recall | 1 skips reading prior memory for this turn but still persists it. |
X-Codai-Incognito | 1 makes the turn fully stateless — nothing read, nothing written, no sticky routing. |
X-Codai-Compact | auto enables deterministic server-side context compaction (truncates stale tool results outside the protected tail, no model call). off disables it. Response: `x-codai-compacted: true |
Agent behaviour
| Header | Effect |
|---|---|
X-Codai-Mode | agent switches to plan-and-execute agent mode (raised depth cap, planning system message). Requires a tier with tools and sub-agents; otherwise 403 forbidden. Echoed as x-codai-mode: agent. |
X-Codai-Disable-Subagents | 1 skips the delegate_to_model tool injection. The VS Code config sets this — Copilot owns its own orchestration. |
X-Codai-Best-Of | 3 forces best-of-N sampling on this request; 0 disables the auto-gate. Response: x-codai-best-of-status. |
X-Codai-Cascade | verify forces draft-and-verify on this request. Response: x-codai-cascade-status. |
Tasks and billing
codai bills per verified successful task, not per token. These headers connect a request to its task.
| Header | Effect |
|---|---|
X-Codai-Task-Id | Your own task id ([A-Za-z0-9._:-], max 128). Correlates all turns of one task; without it the gateway derives a key from the transcript. |
X-Codai-Task-Outcome | pass or fail. Honoured only from desktop and cli surfaces and only with machine evidence — otherwise ignored and logged. |
X-Codai-Task-Evidence | exec_verdict or reexec — what proves the outcome. Required for X-Codai-Task-Outcome to take effect. |
X-Codai-No-Task | 1 opts a utility call out of task counting. Honoured only on utility aliases such as codai-fast; on a full codai request it is rejected with 400, so the task cap cannot be bypassed. |
X-Codai-Device, X-Codai-Device-Platform, X-Codai-Device-Name | Device registration for the shared-sessions protocol (desktop, phone). Not needed for plain API calls. |
Response side: x-codai-task-id (the task this turn attached to), x-codai-event-id (the usage row — pass it to POST /v1/feedback).
Response headers
| Header | Meaning |
|---|---|
x-codai-routed-to | Concrete upstream model that served. |
x-codai-provider | Provider adapter kind, e.g. vertex-anthropic. |
x-codai-upstream | Same as routed-to, set alongside the cost receipt. |
x-codai-trace-id | Your X-Request-Id or a minted UUID. |
x-codai-event-id | Id of the usage_events row for this request. |
x-codai-task-id | Task this request attached to. |
x-codai-cost-micro-usd | Integer micro-USD for this request, when known at header time. |
x-codai-cost-estimate | pending on native streams — see GET /v1/receipt. |
x-codai-cache-read, x-codai-cache-write | Cache token counts when known up front. |
x-codai-spend-day-usd, x-codai-spend-day-cap-usd, x-codai-spend-month-usd, x-codai-spend-month-cap-usd | Your running spend versus the cap, when spend caps are enabled for your account. |
x-codai-exec-verify | passed · refined · refine_failed · skipped · error on codai-labs execution-verified answers. |
x-codai-embed-fallback | <requested>-><served> when an embedding model was substituted. |
x-ratelimit-limit-minute, x-ratelimit-remaining-minute, x-ratelimit-reset-minute, x-ratelimit-limit-hour, x-ratelimit-remaining-hour, x-ratelimit-reset-hour | Sliding-window request limits. reset is a Unix timestamp in seconds. |
Retry-After | On 429: seconds until the oldest entry ages out of the window. Honour it — it is exact, not a flat 60. |
All of these are in the CORS Access-Control-Expose-Headers list, so browser code can read them.
Idempotency
The gateway has no Idempotency-Key header. Retrying a chat request creates a new request and a new usage row; prompt caching keeps the retry cheap. For a stable identity across retries, send the same X-Request-Id — it becomes client_request_id on the usage row and lets POST /v1/feedback target the turn.