codai docs
Referință APIGateway

Cercetare

Cercetare aprofundată asincronă: un raport cu citări, din mai multe căutări și citiri de pagini.

POST /v1/research pornește un job care planifică mai multe căutări, citește cele mai bune pagini și scrie un raport în care fiecare afirmație își citează sursa ca [S1]..[Sn] (sau, cu output_schema, un answer JSON). Cererea așteaptă cel mult wait_s secunde (implicit 0) și răspunde 200 cu jobul terminat sau 202 cât timp este queued / running; interoghezi GET /v1/research/{id} până când status devine done sau failed. Același Idempotency-Key trimis din nou întoarce jobul existent. Admiterea este aceeași ca la tool-uri — regulile tale îl văd ca web_search. Preț: 0,20 $ per job plus tokenii lui de model; joburile din alocarea gratuită lunară sau dintr-o tură de agent codai nu plătesc taxa de job.

SDK-urile se ocupă de interogare: codai.research.run({ question }) (TypeScript) și codai.research.run("…") (Python) pornesc jobul și îl așteaptă. Același motor este tool-ul deep_research din VS Code, desktop, telefon, headless și MCP-ul găzduit. Detalii: ghidul de tool-uri.

POST
/v1/research

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128
Idempotency-Key?string

Întoarce jobul creat anterior cu aceeași cheie în loc să pornească altul (se folosesc primele 200 de caractere).

Lungimelength <= 200

Corpul cererii

application/json
  1. body

Corpul lui POST /v1/research.

question*string

Întrebarea de cercetat, cu eventualele constrângeri (regiune, perioadă, ce se compară).

Lungime1 <= length <= 2000
time_budget_s?integer

Timpul maxim de cercetare, în secunde.

Interval20 <= value <= 300
Implicit90
max_sources?integer

Numărul maxim de pagini citite.

Interval3 <= value <= 30
Implicit12
include_domains?array<>

Folosește doar pagini de pe aceste host-uri.

Elementeitems <= 10
published_after?string

Folosește doar pagini publicate la sau după această dată (YYYY-MM-DD).

Potrivire^\d{4}-\d{2}(-\d{2})?$
output_schema?

JSON Schema opțională; rezultatul devine atunci un obiect JSON conform ei, în answer, în locul unui report în proză.

wait_s?number

Câte secunde se așteaptă terminarea jobului înainte de răspunsul 202.

Interval0 <= value <= 55
Implicit0

Corpul răspunsului

Jobul s-a terminat în wait_s (status este done sau failed).

application/json
  1. response

Un job de cercetare aprofundată. Câmpurile de rezultat apar doar când status este done, iar error doar când este failed.

id*string
Formatuuid
status*string
Valoare din"queued""running""done""failed"
created_at*string
Formatdate-time
finished_at?string
Formatdate-time
report?string

Raport Markdown care citează sursele ca [S1]..[Sn] (absent când s-a trimis output_schema).

answer?

Obiect JSON conform output_schema, când s-a trimis una.

sources?array<>
searches?integer

Numărul de căutări web rulate de job.

Interval0 <= value
pages_read?integer

Numărul de pagini citite de job.

Interval0 <= value
error?
Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/research' \  -H 'Content-Type: application/json' \  -d '{  "question": "Compare the e-Factura obligations for B2C sales in Romania in 2025 and 2026"}'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "queued",  "created_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z",  "report": "string",  "answer": {},  "sources": [    {      "id": "string",      "title": "string",      "url": "http://example.com"    }  ],  "searches": 0,  "pages_read": 0,  "error": {    "message": "string"  }}
GET
/v1/research/{id}

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul jobului de cercetare întors de POST /v1/research.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

Jobul.

application/json
  1. response

Un job de cercetare aprofundată. Câmpurile de rezultat apar doar când status este done, iar error doar când este failed.

id*string
Formatuuid
status*string
Valoare din"queued""running""done""failed"
created_at*string
Formatdate-time
finished_at?string
Formatdate-time
report?string

Raport Markdown care citează sursele ca [S1]..[Sn] (absent când s-a trimis output_schema).

answer?

Obiect JSON conform output_schema, când s-a trimis una.

sources?array<>
searches?integer

Numărul de căutări web rulate de job.

Interval0 <= value
pages_read?integer

Numărul de pagini citite de job.

Interval0 <= value
error?
Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/research/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "queued",  "created_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z",  "report": "string",  "answer": {},  "sources": [    {      "id": "string",      "title": "string",      "url": "http://example.com"    }  ],  "searches": 0,  "pages_read": 0,  "error": {    "message": "string"  }}

Tool-uri

Căutare web verificată și fetch sigur de pagini, aceleași tool-uri pe care le folosește fiecare agent codai.

Carduri

Date pentru carduri tipizate: vreme, locuri, geocodare, hărți statice, cursuri de schimb și previzualizări de linkuri, ca blocuri de card gata făcute.