Header-e de cerere
Fiecare header pe care gateway-ul îl citește și fiecare header pe care îl trimite înapoi — autentificare, identitate de client, caching, effort, thinking, sesiuni, task-uri, cost.
Toate header-ele codai sunt opționale și insensibile la majuscule. Le trimiți pe POST /v1/chat/completions, POST /v1/messages și POST /v1/responses (ruta Responses trimite mai departe fiecare header X-Codai-* către ruta de chat în care reintră). Tot ce trimiți și gateway-ul nu înțelege este ignorat.
Autentificare
| Header | Valoare |
|---|---|
Authorization | Bearer codai_… — cheia ta API, sau un token efemer codai_eph_v1.… pe suprafețele media. Obligatoriu peste tot, cu excepția endpoint-urilor publice /vscode/*, /copilot/*, /health și /status. |
x-api-key | Acceptat doar pe POST /v1/messages, pentru SDK-urile Anthropic. Authorization câștigă dacă sunt prezente ambele. |
anthropic-version, anthropic-beta, openai-beta | Trimise mai departe unde upstream-ul le așteaptă. |
O cheie lipsă sau necunoscută dă 401 invalid_api_key. O cheie dintr-un abonament inactiv dă 402 subscription_inactive.
Identitatea clientului
| Header | Efect |
|---|---|
X-Codai-Client | Cine apelează, ca <suprafață>/<versiune> — desktop/1.4.0, phone-android/0.9.2, codai-cli/0.3.0, hub/…. Determină atribuirea task-urilor: desktop și cli pot raporta singure rezultatul task-ului; tot restul (IDE-uri, SDK-uri brute, curl) este proxy și task-urile lui se închid doar prin confirmare explicită a utilizatorului în hub. Cade pe User-Agent când lipsește. |
X-Request-Id | Id-ul tău de corelare. Reflectat înapoi ca x-codai-trace-id, trimis către upstream și utilizabil ca client_request_id în POST /v1/feedback. |
X-Codai-Repo | Identificator de repository pentru scoparea memoriei. Când lipsește, gateway-ul deduce scopul din transcript. |
X-Codai-Agent-Id | Id de atribuire înregistrat pe apelurile de tool în flote de agenți. [A-Za-z0-9._:-], maximum 128 caractere. |
Caching
| Header | Efect |
|---|---|
X-Codai-Cache | Prompt caching este pornit implicit pentru fiecare model. 0 sau false îl oprește — cu excepția alias-urilor codai*, unde opt-out-ul este ignorat. Citirile din cache costă aproximativ a zecea parte din input-ul proaspăt, iar o buclă de agent necache-uită cu 170 k tokeni a costat odată un utilizator mii de dolari pe zi, așa că alias-ul router nu te lasă să-l dezactivezi. |
Pe răspuns: x-codai-cache-read și x-codai-cache-write poartă numărul de tokeni din cache când e cunoscut înaintea primului byte; usage.prompt_tokens_details.cached_tokens poartă numărul final de citiri în body.
Effort și thinking
| Header | Efect |
|---|---|
X-Codai-Effort | minimal · low · medium (implicit) · high · max. Câștigă peste reasoning_effort din body. Vezi modele. |
X-Codai-Thinking | 1 sau true activează explicit extended thinking. |
X-Codai-Thinking-Budget | Buget de thinking în tokeni (întreg pozitiv, implicit 16 384). |
X-Codai-Thinking-Pin | 1 păstrează bugetul complet de thinking pe turele de continuare cu tool. Fără el, gateway-ul limitează bugetele injectate la 4 096 tokeni pe turele al căror ultim mesaj e un rezultat de tool, ca buclele de agent să nu plătească max la fiecare pas. |
Pe răspuns: x-codai-effort, x-codai-effort-applied, x-codai-effort-continuation-dampened.
Sesiuni și memorie
| Header | Efect |
|---|---|
X-Codai-Session-Id | Id stabil pentru o conversație logică. Activează sticky routing (ține prompt cache-urile calde), totaluri de cost per sesiune în GET /v1/receipt și memorie de sesiune. Header-ul bate body.user. Clienții IDE îl omit de obicei; gateway-ul derivă atunci o cheie din transcript. |
X-Codai-New-Session | 1 pornește o sesiune persistentă nouă cu id proaspăt, ignorând orice X-Codai-Session-Id. |
X-Codai-No-Recall | 1 sare citirea memoriei anterioare pentru această tură, dar o persistă totuși. |
X-Codai-Incognito | 1 face tura complet stateless — nimic citit, nimic scris, fără sticky routing. |
X-Codai-Compact | auto activează compactarea deterministă server-side a contextului (trunchiază rezultatele vechi de tool din afara cozii protejate, fără apel de model). off o dezactivează. Răspuns: `x-codai-compacted: true |
Comportament de agent
| Header | Efect |
|---|---|
X-Codai-Mode | agent comută pe modul agent plan-and-execute (limită de adâncime ridicată, mesaj de sistem de planificare). Necesită un tier cu tool-uri și sub-agenți; altfel 403 forbidden. Reflectat ca x-codai-mode: agent. |
X-Codai-Disable-Subagents | 1 sare injectarea tool-ului delegate_to_model. Configurația VS Code îl setează — Copilot își deține propria orchestrare. |
X-Codai-Best-Of | 3 forțează best-of-N pe această cerere; 0 dezactivează auto-gate-ul. Răspuns: x-codai-best-of-status. |
X-Codai-Cascade | verify forțează draft-and-verify pe această cerere. Răspuns: x-codai-cascade-status. |
Task-uri și facturare
codai facturează per task reușit verificat, nu per token. Aceste header-e leagă o cerere de task-ul ei.
| Header | Efect |
|---|---|
X-Codai-Task-Id | Id-ul tău de task ([A-Za-z0-9._:-], maximum 128). Corelează toate turele unui task; fără el gateway-ul derivă o cheie din transcript. |
X-Codai-Task-Outcome | pass sau fail. Respectat doar de pe suprafețele desktop și cli și doar cu dovadă automată — altfel ignorat și logat. |
X-Codai-Task-Evidence | exec_verdict sau reexec — ce dovedește rezultatul. Obligatoriu ca X-Codai-Task-Outcome să aibă efect. |
X-Codai-No-Task | 1 scoate un apel utilitar din numărătoarea de task-uri. Respectat doar pe alias-uri utilitare precum codai-fast; pe o cerere codai completă este respins cu 400, ca plafonul de task-uri să nu poată fi ocolit. |
X-Codai-Device, X-Codai-Device-Platform, X-Codai-Device-Name | Înregistrarea dispozitivului pentru protocolul de sesiuni partajate (desktop, telefon). Nu e nevoie pentru apeluri API simple. |
Pe răspuns: x-codai-task-id (task-ul la care s-a atașat tura), x-codai-event-id (rândul de usage — îl trimiți la POST /v1/feedback).
Header-e de răspuns
| Header | Semnificație |
|---|---|
x-codai-routed-to | Modelul upstream concret care a servit. |
x-codai-provider | Tipul adaptorului de provider, de ex. vertex-anthropic. |
x-codai-upstream | La fel ca routed-to, setat împreună cu chitanța de cost. |
x-codai-trace-id | X-Request-Id al tău sau un UUID generat. |
x-codai-event-id | Id-ul rândului usage_events pentru această cerere. |
x-codai-task-id | Task-ul la care s-a atașat cererea. |
x-codai-cost-micro-usd | Micro-USD întregi pentru această cerere, când e cunoscut la momentul header-elor. |
x-codai-cost-estimate | pending pe stream-urile native — vezi GET /v1/receipt. |
x-codai-cache-read, x-codai-cache-write | Numărul de tokeni de cache când e cunoscut dinainte. |
x-codai-spend-day-usd, x-codai-spend-day-cap-usd, x-codai-spend-month-usd, x-codai-spend-month-cap-usd | Cheltuiala ta curentă față de plafon, când plafoanele de cheltuieli sunt active pe contul tău. |
x-codai-exec-verify | passed · refined · refine_failed · skipped · error pe răspunsurile codai-labs verificate prin execuție. |
x-codai-embed-fallback | <cerut>-><servit> când un model de embedding a fost înlocuit. |
x-ratelimit-limit-minute, x-ratelimit-remaining-minute, x-ratelimit-reset-minute, x-ratelimit-limit-hour, x-ratelimit-remaining-hour, x-ratelimit-reset-hour | Limite de cereri cu fereastră glisantă. reset este un timestamp Unix în secunde. |
Retry-After | Pe 429: secunde până când cea mai veche intrare iese din fereastră. Respectă-l — este exact, nu un 60 fix. |
Toate acestea sunt în lista CORS Access-Control-Expose-Headers, așa că codul din browser le poate citi.
Idempotență
Gateway-ul nu are un header Idempotency-Key. Reîncercarea unei cereri de chat creează o cerere nouă și un rând de usage nou; prompt caching face reîncercarea ieftină. Pentru o identitate stabilă peste reîncercări, trimiți același X-Request-Id — devine client_request_id pe rândul de usage și lasă POST /v1/feedback să țintească tura.