Chat & Completions
The three wire formats that reach `codai`: OpenAI Chat Completions, Anthropic Messages, OpenAI Responses.
All three endpoints route to the same model chain and share auth, rate limits, prompt caching and usage recording. Pick the one your SDK already speaks — the wire formats guide explains the differences and the headers guide covers every x-codai-* extension you see below.
bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128x-codai-session-id?stringGroups requests of one conversation for receipts, stickiness and prompt caching.
length <= 128x-codai-effort?stringTest-time-compute effort tier. Wins over the reasoning_effort body field. max is a codai extension above OpenAI's high; none is accepted as an alias of minimal.
"minimal""low""medium""high""max"x-codai-thinking?string1/true enables extended thinking on models that support it (budget from x-codai-thinking-budget, default 16384 tokens).
x-codai-thinking-budget?stringPositive integer thinking-token budget used when x-codai-thinking is on. Also marks the request as caller-tuned so the effort planner does not override it.
x-codai-thinking-pin?string1 keeps the full thinking budget on tool-continuation turns instead of the dampened budget the gateway applies by default.
x-codai-cache?string0/false disables prompt caching for a DIRECT model id. Ignored (caching forced ON) for the codai / codai-* router aliases.
x-codai-no-task?string1/true opts this request out of task counting. Only valid on utility aliases; on codai the request is rejected with 400.
x-codai-task-id?stringClient-chosen task correlation id. Requests sharing it are attributed to one task; echoed back as the x-codai-task-id response header when known within 150 ms.
x-codai-task-outcome?stringpass or fail — self-reported outcome that closes the attached task. Honoured only for desktop/CLI surfaces (x-codai-client) and only together with a machine x-codai-task-evidence.
"pass""fail"x-codai-task-evidence?stringEvidence kind backing x-codai-task-outcome; only exec_verdict and reexec close a task.
"exec_verdict""reexec"x-codai-client?stringExplicit client surface tag used for task attribution (desktop/<ver>, phone-android/<ver>, codai-cli/<ver>, hub/<ver>). Anything else is classified as proxy.
x-codai-incognito?string1 makes the turn fully stateless: no memory read, nothing persisted, no sticky routing.
x-codai-no-recall?string1 skips reading prior memory but still persists this turn.
x-codai-proven-only?string1 restricts memory recall to entries promoted to proven.
x-codai-new-session?string1 rotates to a fresh server-minted session namespace for this request, ignoring x-codai-session-id.
x-codai-repo?stringRepository scope hint (e.g. owner/name) used to select the session playbook; most IDE proxies cannot send it, so the gateway also infers scope from the transcript.
x-codai-agent-id?stringCaller-supplied agent identifier persisted with the usage event for per-agent analytics.
x-codai-disable-subagents?string1 forbids delegate_to_model sub-agent fan-out and forces the native streaming path.
x-codai-mode?"agent"agent requests agent mode (server-side agent prompt + server tools). 403 when the key/plan is not entitled.
"agent"x-codai-server-tools?string1/true enables gateway-side tools without full agent mode (agent mode implies it).
x-codai-orchestrate?string1/true opts into multi-model orchestration (fan-out to sub-tasks). Requires at least two models in the key allowlist.
x-codai-cascade?stringverify opts into the FrugalGPT cascade (cheap draft, frontier verify). Result reported in x-codai-cascade-status.
x-codai-best-of?stringBest-of-N sampling count (e.g. 3); 0/off explicitly disables the automatic best-of. Result in x-codai-best-of-status.
x-codai-best-of-depth?stringJudge depth for best-of-N.
x-codai-reflect?stringOpt-in/out of the self-verification reflect pass (1/0). Result in x-codai-reflect-status.
x-codai-step-verify?stringOpt-in/out of step-level process verification (1/0). Result in x-codai-step-verify-status.
x-codai-plan?stringOpt-in/out of the long-horizon plan check (1/0). Result in x-codai-plan-status.
x-codai-consensus?string1 runs iterative consensus across all tiers (non-stream, router alias only). Result in x-codai-consensus-status.
x-codai-compact?stringOpt-in server-side transcript compaction (1). Savings reported in x-codai-compacted / x-codai-compact-saved-chars.
x-codai-retrieval?string1/on enables relevance retrieval over the transcript before dispatch (x-codai-retrieval-reduced).
x-codai-heuristics?stringOpt-in/out of the learned-heuristics prompt injection (1/0).
x-codai-identity?stringIdentity-preamble mode override (on / off / shadow).
x-codai-playbook?stringPer-request playbook mode override; x-codai-no-playbook: 1 is the hard kill-switch.
x-codai-no-playbook?string1 disables session playbook injection for this request.
x-codai-debug?string1 adds the full router decision trace as extra x-codai-router-* response headers.
application/json- body
OpenAI Chat Completions body. Unknown fields are accepted (passthrough) and forwarded to OpenAI-compatible upstreams; Anthropic upstreams ignore them.
model?stringLogical model. codai is the smart router and the only publicly addressable model; any unrecognised name is coerced to codai.
"codai"messages*array<>Conversation so far. Above 2 000 messages the gateway trims the middle (system head + recent tail kept); above 20 000 the request is rejected with 400.
1 <= items <= 20000stream?booleantrue returns text/event-stream chunks. The final usage chunk is always emitted.
falsestream_options?Accepted for OpenAI compatibility; include_usage is effectively always on.
max_tokens?integerMaximum completion tokens (legacy name).
1 <= valuemax_completion_tokens?integerMaximum completion tokens (current OpenAI name). Either name is honoured.
1 <= valuetemperature?numbertop_p?numbertop_k?integercodai extension forwarded to Anthropic upstreams.
stop?|array<string>One stop string or an array of stop strings.
tools?array<|>Function tools. Presence switches the request to the multi-turn loop path (streams are buffered and replayed). A codai_sandbox item lets the gateway run bash and Python server-side in an isolated sandbox (see the Sandboxes tag).
tool_choice?|auto | none | required | {type: function, function: {name}}. required and named choices are downgraded to auto on models that reject forced tool use (Fable 5.x); none suppresses tools entirely.
response_format?Structured-output control. json_object / json_schema inject a system instruction and validate the output at serve time; json_schema also carries the schema.
reasoning_effort?stringTest-time-compute effort tier (OpenAI vocabulary plus codai max; none accepted as minimal). The x-codai-effort header wins when both are present.
"minimal""low""medium""high""max"n?integerAccepted for compatibility and forwarded only to OpenAI-compatible upstreams; codai always returns a single choice.
user?stringEnd-user identifier. When no x-codai-session-id header is present a non-empty user under 256 chars is used as the session id.
length <= 255metadata?Accepted for compatibility (passthrough); not interpreted by the gateway.
[key: string]?anyCompletion. JSON (chat.completion) when stream is false or
absent; text/event-stream of chat.completion.chunk objects
when stream: true, always ending with a usage chunk and
data: [DONE]. Response headers below are set on both forms;
cost headers are x-codai-cost-micro-usd when the cost is known
at response time and x-codai-cost-estimate: pending on native
streams (the usage row is written after the stream closes).
- response
id*stringobject*"chat.completion""chat.completion"created*integerUnix seconds.
model*stringUpstream model that served the request.
choices*array<>Always exactly one choice.
usage*curl -X POST 'https://ai.codai.ro/v1/chat/completions' \ -H 'Content-Type: application/json' \ -d '{ "messages": [ { "role": "system" } ]}'{ "id": "chatcmpl_9f1c2b7e4d", "object": "chat.completion", "created": 1790108310, "model": "claude-sonnet-5", "choices": [ { "index": 0, "message": { "role": "system", "content": "string", "name": "string", "tool_call_id": "string", "tool_calls": [ { "id": "toolu_01Xy9k3mQ", "type": "function", "function": { "name": "string", "arguments": "{\"path\":\"src/index.ts\"}" } } ] }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "prompt_tokens_details": { "cached_tokens": 0 }, "cache_creation_input_tokens": 0 }}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128x-codai-session-id?stringGroups requests of one conversation for receipts, stickiness and prompt caching.
length <= 128x-api-key?stringAnthropic-style API key header. Alternative to Authorization: Bearer; ignored when a Bearer header
is present.
x-codai-effort?stringTest-time-compute effort tier. Wins over the body reasoning_effort. none is normalised to
minimal; unknown values are ignored.
"minimal""low""medium""high""max"x-codai-thinking?stringEnable extended thinking upstream (1 or true). Default budget 16384 tokens.
"1""true""0""false"x-codai-thinking-budget?stringThinking budget in tokens (positive integer). On adaptive-thinking models it is mapped to an effort level. Setting it also tells the compute allocator not to inject its own budget.
x-codai-cache?stringPrompt-caching opt-out (0 / false). Only honoured on direct model calls — caching is forced ON
for the codai router alias.
"0""false""1""true"x-codai-compact?stringForce (1) or suppress (0) server-side conversation compaction for this request.
"0""1"x-codai-disable-subagents?"1"1 disables sub-agent delegation for this request. Combined with stream: true and no tools this
unlocks the native pass-through streaming path on sub-agent-capable tiers.
"1"x-codai-no-task?"1"1 opts out of task counting. Only honoured for eligible utility aliases; on a full model the request
is rejected with 400.
"1"x-codai-best-of?stringBest-of-N sampling on the buffered path (tier-gated; ignored when not entitled).
x-codai-best-of-depth?stringSub-agent depth at which best-of applies on the buffered path.
x-codai-client?stringFree-form client identifier recorded on the task opened for this turn.
application/json- body
Public Anthropic Messages request. Unknown top-level fields pass validation and are ignored unless listed here as a codai extension.
model*stringModel or alias. Use codai for the smart router. Names that are not codai aliases are coerced to
codai.
messages*array<>Conversation turns, alternating user / assistant. Content is a string or an array of blocks.
Over-long transcripts are trimmed from the middle rather than rejected.
1 <= itemsmax_tokens*integerMaximum output tokens. Required.
1 <= valuesystem?|array<>System prompt as a plain string or an array of text blocks (joined with blank lines).
temperature?numberSampling temperature. Dropped on upstream models that reject sampling parameters.
top_p?numberNucleus sampling. Dropped on upstream models that reject sampling parameters.
top_k?numberTop-k sampling. Dropped on upstream models that reject sampling parameters.
stop_sequences?array<string>Custom stop sequences.
stream?booleantrue returns text/event-stream (see the operation description for the event list).
falsetools?array<>Tool definitions the model may call. Any non-empty list forces the buffered execution path.
tool_choice?|auto lets the model decide, any forces some tool call, tool forces a named tool. On Fable 5 / 5.1
upstreams any and tool are downgraded to auto because those models reject forced tool use.
metadata?Only user_id is used; it is forwarded as the upstream user field.
thinking?|Anthropic extended-thinking config. Accepted for SDK compatibility but NOT forwarded — the gateway decides
the thinking shape per upstream model (enabled + budget_tokens on legacy models, adaptive on newer
ones). Use the x-codai-thinking / x-codai-thinking-budget headers instead.
reasoning_effort?stringcodai extension (OpenAI-standard body param). Effort tier for the compute allocator; the
x-codai-effort header takes precedence.
"minimal""low""medium""high""max"The assistant message. JSON when stream is false or absent; an SSE event sequence (see the
operation description) when stream is true.
- response
Non-streaming response. model echoes the requested model or alias, not the upstream that answered (see x-codai-routed-to).
id*stringtype*"message""message"role*"assistant""assistant"model*stringcontent*array<|>Always at least one block; an empty reply is a single text block with text: ''.
stop_reason*stringMapped from the upstream finish reason (content_filter becomes end_turn).
"end_turn""max_tokens""stop_sequence""tool_use"stop_sequence*stringAlways null on the buffered path.
usage*curl -X POST 'https://ai.codai.ro/v1/messages' \ -H 'Content-Type: application/json' \ -d '{ "model": "codai", "messages": [ { "role": "user", "content": "string" } ], "max_tokens": 4096}'{ "id": "msg_1f0d5b7a-4c2e-4a9b-9c1d-2e3f4a5b6c7d", "type": "message", "role": "assistant", "model": "codai", "content": [ { "type": "text", "text": "string" } ], "stop_reason": "end_turn", "stop_sequence": "string", "usage": { "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0 }}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128x-codai-session-id?stringGroups requests of one conversation for receipts, stickiness and prompt caching.
length <= 128x-codai-effort?stringEffort tier; when present it wins and reasoning.effort from the body is not mapped.
"minimal""low""medium""high""max"x-codai-cache?string0/false disables prompt caching for a direct model id (ignored for the codai alias). Forwarded to the inner chat-completions call.
x-codai-no-task?stringForwarded to the inner call; only valid on utility aliases (400 on codai).
x-codai-incognito?stringForwarded to the inner call — stateless turn, nothing persisted.
x-codai-client?stringForwarded to the inner call — client surface tag for task attribution.
application/json- body
model?string"codai"input?|array<>Prompt as a single user string or as an array of input items.
instructions?stringBecomes the leading system message.
stream?booleanfalsemax_output_tokens?integerMapped to max_tokens.
1 <= valuetemperature?numbertop_p?numbertools?array<>tool_choice?|Passed through to chat completions unchanged.
reasoning?Only effort is mapped (xhigh → max, none → minimal, unknown values dropped). Ignored when x-codai-effort is sent.
previous_response_id?stringNOT supported — any value is rejected with 400. Send the full input context instead.
background?booleanNOT supported — true is rejected with 400.
[key: string]?anyA response object when stream is false; otherwise a
text/event-stream of response.* events (see description).
Non-stream responses carry the same x-codai-* headers as
/v1/chat/completions (routing, trace, cost, task).
- response
id*stringobject*"response""response"created_at*integerUnix seconds.
status*"completed""completed"model*stringUpstream model that served the inner call.
output*array<|>Function-call items first, then at most one assistant message.
output_text*stringConvenience copy of the assistant text (empty string when none).
usage*curl -X POST 'https://ai.codai.ro/v1/responses' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "resp_chatcmpl_9f1c2b7e4d", "object": "response", "created_at": 0, "status": "completed", "model": "string", "output": [ { "type": "function_call", "id": "fc_toolu_01Xy9k3mQ", "call_id": "string", "name": "string", "arguments": "string", "status": "completed" } ], "output_text": "string", "usage": { "input_tokens": 0, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 0, "total_tokens": 0 }}Last updated: