codai docs
Referință APIGateway

Sarcini

Facturare pe rezultat: listezi sarcinile deschise de cererile tale și confirmi sau respingi rezultatul lor.

O sarcină e deschisă de prima cerere a unei bucăți de lucru și e decontată după rezultat. Confirmarea cere cheia proprie a deținătorului — nu există o cale act-as. Câmpurile de bani sunt întregi în micro-EUR. Cum se leagă sarcinile de cheltuieli: sarcini și cheltuieli.

Agenții citesc sarcinile prin uneltele serverului MCP tasks_list (status, limit), tasks_get (id) și tasks_stats (since). Nu există unealtă de confirmare: decontarea unei sarcini înseamnă facturare și rămâne la om.

GET
/v1/tasks

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 query

outcome?string

Doar task-urile cu acest rezultat.

Valoare din"pass""fail""error""unconfirmed""confirmed""cancelled""open"
limit?integer

Dimensiunea paginii.

Interval1 <= value <= 200
Implicit50
cursor?string

Marcaj de timp ISO 8601 cu offset — next_cursor din pagina anterioară.

Formatdate-time

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

O pagină de task-uri.

application/json
  1. response
tasks*array<>
next_cursor*|

Îl trimiți ca cursor pentru pagina următoare; null când nu mai există.

Formatdate-time
Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/tasks'
Exemplu de răspuns
{  "tasks": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "surface": "proxy",      "session_key": "string",      "client_task_id": "string",      "title": "string",      "outcome": "pass",      "evidence_kind": "exec_verdict",      "evidence_ref": "string",      "requests": 0,      "cost_micro_usd": 0,      "charged_micro_eur": 0,      "billed_success": true,      "billable_at": "2019-08-24T14:15:22Z",      "confirm_deadline_at": "2019-08-24T14:15:22Z",      "opened_at": "2019-08-24T14:15:22Z",      "last_activity_at": "2019-08-24T14:15:22Z",      "closed_at": "2019-08-24T14:15:22Z",      "note": "string"    }  ],  "next_cursor": "2019-08-24T14:15:22Z"}
GET
/v1/tasks/pending

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

Corpul răspunsului

Task-uri în așteptarea confirmării.

application/json
  1. response
tasks*array<>
Elementeitems <= 100
Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/tasks/pending'
Exemplu de răspuns
{  "tasks": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "surface": "proxy",      "session_key": "string",      "client_task_id": "string",      "title": "string",      "outcome": "pass",      "evidence_kind": "exec_verdict",      "evidence_ref": "string",      "requests": 0,      "cost_micro_usd": 0,      "charged_micro_eur": 0,      "billed_success": true,      "billable_at": "2019-08-24T14:15:22Z",      "confirm_deadline_at": "2019-08-24T14:15:22Z",      "opened_at": "2019-08-24T14:15:22Z",      "last_activity_at": "2019-08-24T14:15:22Z",      "closed_at": "2019-08-24T14:15:22Z",      "note": "string"    }  ]}
GET
/v1/tasks/stats

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 query

since?string

Limita inferioară pentru opened_at (inclusiv). Implicit acum minus 30 de zile.

Formatdate-time

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

Numărătorile pentru fereastră.

application/json
  1. response

Numărători peste task-urile deschise la sau după since.

since*string

Limita inferioară efectivă, normalizată la ISO 8601 UTC.

Formatdate-time
opened*integer
Interval0 <= value
confirmed*integer
Interval0 <= value
pass*integer
Interval0 <= value
unconfirmed*integer
Interval0 <= value
billed*integer

Task-uri cu billed_success setat.

Interval0 <= value
Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/tasks/stats'
Exemplu de răspuns
{  "since": "2019-08-24T14:15:22Z",  "opened": 0,  "confirmed": 0,  "pass": 0,  "unconfirmed": 0,  "billed": 0}
GET
/v1/tasks/{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 task-ului.

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

Task-ul.

application/json
  1. response

Vederea pe fir a unui task. Banii sunt micro-unități întregi (USD pentru cost, EUR pentru taxe); datele sunt ISO 8601.

id*string
Formatuuid
surface*TaskSurface

Suprafața de client care a deschis task-ul.

Valoare din"proxy""desktop""cli""resolve""sandbox""mobile""hub"
session_key*|

Cheia de sesiune derivată sau x-codai-task-id-ul de client care grupează cererile task-ului.

client_task_id*|

x-codai-task-id-ul tău, neschimbat, când a fost trimis.

title*|

Primul mesaj al utilizatorului, ≤ 200 de caractere.

outcome*TaskOutcome

Rezultatul task-ului. open cât timp rulează; pass/fail/error dintr-un verdict de execuție; unconfirmed după închiderea pentru inactivitate; confirmed după confirmarea ta; cancelled când este retras.

Valoare din"pass""fail""error""unconfirmed""confirmed""cancelled""open"
evidence_kind*TaskEvidenceKind

Ce a închis task-ul — un verdict automat, o re-execuție, confirmarea ta sau nimic încă.

Valoare din"exec_verdict""reexec""user_confirmed""none"
evidence_ref*|

Id-ul cererii de verdict, id-ul job-ului resolve, id-ul evenimentului de usage sau x-request-id-ul apelului de confirmare.

requests*integer

Numărul de cereri atribuite task-ului.

Interval0 <= value
cost_micro_usd*integer

Costul upstream real, în micro-USD.

Interval0 <= value
charged_micro_eur*integer

Costul de tokeni debitat până acum din portofelul preplătit, în micro-EUR.

Interval0 <= value
billed_success*boolean

True odată ce task-ul a fost facturat ca un succes (eveniment de meter task_succeeded).

billable_at*|

Când rezultatul și dovada au concordat prima dată pe un succes facturabil.

Formatdate-time
confirm_deadline_at*|

Până când POST /v1/tasks/{id}/confirm mai convertește un task unconfirmed.

Formatdate-time
opened_at*string
Formatdate-time
last_activity_at*string
Formatdate-time
closed_at*|
Formatdate-time
note*|

Nota ta din apelul de confirmare, când ai dat una.

Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "surface": "proxy",  "session_key": "string",  "client_task_id": "string",  "title": "string",  "outcome": "pass",  "evidence_kind": "exec_verdict",  "evidence_ref": "string",  "requests": 0,  "cost_micro_usd": 0,  "charged_micro_eur": 0,  "billed_success": true,  "billable_at": "2019-08-24T14:15:22Z",  "confirm_deadline_at": "2019-08-24T14:15:22Z",  "opened_at": "2019-08-24T14:15:22Z",  "last_activity_at": "2019-08-24T14:15:22Z",  "closed_at": "2019-08-24T14:15:22Z",  "note": "string"}
POST
/v1/tasks/{id}/confirm

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 task-ului.

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 cererii

application/json
  1. body

Corpul lui POST /v1/tasks/{id}/confirm.

outcome*string

confirmed = codai a rezolvat (facturabil); fail = nu a rezolvat (nu se facturează niciodată).

Valoare din"confirmed""fail"
note?string

Notă opțională în text liber (cu spațiile de la capete eliminate), stocată pe task.

Lungimelength <= 500

Corpul răspunsului

Task-ul este închis cu rezultatul ales.

application/json
  1. response

Rezultatul confirmării. Cheile sunt camelCase, spre deosebire de obiectul Task.

taskId*string
Formatuuid
outcome*string

Rezultatul pe care l-ai trimis.

Valoare din"confirmed""fail"
billed*boolean

True când această confirmare a emis un eveniment de meter task_succeeded.

refundedMicroEur*integer

Costul de tokeni întors în portofelul preplătit la conversia într-o taxă fixă de succes, în micro-EUR.

Interval0 <= value
Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08/confirm' \  -H 'Content-Type: application/json' \  -d '{  "outcome": "confirmed"}'
Exemplu de răspuns
{  "taskId": "e6e9d88a-9b63-468a-aec3-b7a11de27af8",  "outcome": "confirmed",  "billed": true,  "refundedMicroEur": 0}

Ultima actualizare:

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.

Declanșatoare

Webhook-uri care transformă evenimentele din GitHub, Sentry, monitorizare sau surse proprii în sesiuni de agent, plus inbox-ul de notificări.