Tasks

Outcome billing: list the tasks your requests opened and confirm or reject their result.

A task is opened by the first request of a piece of work and settled by its outcome. Confirmation needs the owner's own key — there is no act-as path. Money fields are micro-EUR integers. How tasks and spend interact: tasks & spend.

Agents read tasks through the MCP server tools tasks_list (status, limit), tasks_get (id) and tasks_stats (since). There is no confirm tool: settling a task is billing and stays with a human.

GET

/v1/tasks

Authorization

bearerAuth

headerAuthorizationBearer <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).

Query Parameters

outcome?string

Only tasks with this outcome.

Value in"pass""fail""error""unconfirmed""confirmed""cancelled""open"

limit?integer

Page size.

Range1 <= value <= 200

Default50

cursor?string

ISO 8601 timestamp with offset — the next_cursor of the previous page.

Formatdate-time

Header Parameters

Response Body

One page of tasks.

application/json

response

tasks*array<>

next_cursor*|

Pass as cursor to fetch the next page; null when there is none.

Formatdate-time

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks'

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks'

Example ResponseSchema

{
  "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"
}

{  "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

Authorization

bearerAuth

headerAuthorizationBearer <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).

Header Parameters

Response Body

Tasks pending confirmation.

application/json

response

tasks*array<>

Itemsitems <= 100

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks/pending'

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks/pending'

Example ResponseSchema

{
  "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"
    }
  ]
}

{  "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

Authorization

bearerAuth

headerAuthorizationBearer <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).

Query Parameters

since?string

Lower bound on opened_at (inclusive). Defaults to now minus 30 days.

Formatdate-time

Header Parameters

Response Body

Counts for the window.

application/json

response

Counts over tasks opened at or after since.

since*string

The effective lower bound, normalised to ISO 8601 UTC.

Formatdate-time

opened*integer

Range0 <= value

confirmed*integer

Range0 <= value

pass*integer

Range0 <= value

unconfirmed*integer

Range0 <= value

billed*integer

Tasks with billed_success set.

Range0 <= value

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks/stats'

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks/stats'

Example ResponseSchema

{
  "since": "2019-08-24T14:15:22Z",
  "opened": 0,
  "confirmed": 0,
  "pass": 0,
  "unconfirmed": 0,
  "billed": 0
}

{  "since": "2019-08-24T14:15:22Z",  "opened": 0,  "confirmed": 0,  "pass": 0,  "unconfirmed": 0,  "billed": 0}

GET

/v1/tasks/{id}

Authorization

bearerAuth

headerAuthorizationBearer <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).

Path Parameters

id*string

Task UUID.

Formatuuid

Header Parameters

Response Body

The task.

application/json

response

Wire view of a task. Money is integer micros (USD for cost, EUR for charges); dates are ISO 8601.

id*string

Formatuuid

surface*TaskSurface

Client surface that opened the task.

Value in"proxy""desktop""cli""resolve""sandbox""mobile""hub"

session_key*|

Derived session key or the client x-codai-task-id that groups the task's requests.

client_task_id*|

Your x-codai-task-id, verbatim, when one was sent.

title*|

First user message, ≤ 200 chars.

outcome*TaskOutcome

Task outcome. open while running; pass/fail/error from an exec verdict; unconfirmed after the idle close; confirmed after your confirmation; cancelled when withdrawn.

Value in"pass""fail""error""unconfirmed""confirmed""cancelled""open"

evidence_kind*TaskEvidenceKind

What closed the task — a machine verdict, a re-execution, your confirmation, or nothing yet.

Value in"exec_verdict""reexec""user_confirmed""none"

evidence_ref*|

Verdict request id, resolve job id, usage event id, or the x-request-id of the confirm call.

requests*integer

Number of requests attributed to the task.

Range0 <= value

cost_micro_usd*integer

Real upstream cost in USD micros.

Range0 <= value

charged_micro_eur*integer

Token cost debited from the prepaid wallet so far, in EUR micros.

Range0 <= value

billed_success*boolean

True once the task was billed as one success (task_succeeded meter event).

billable_at*|

When outcome and evidence first agreed on a billable success.

Formatdate-time

confirm_deadline_at*|

Until when POST /v1/tasks/{id}/confirm still converts an unconfirmed task.

Formatdate-time

opened_at*string

Formatdate-time

last_activity_at*string

Formatdate-time

closed_at*|

Formatdate-time

note*|

Your note from the confirm call, when given.

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example Request

curl -X GET 'https://ai.codai.ro/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Example ResponseSchema

{
  "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"
}

{  "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

Authorization

bearerAuth

headerAuthorizationBearer <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).

Path Parameters

id*string

Task UUID.

Formatuuid

Header Parameters

Request Body

application/json

body

Body of POST /v1/tasks/{id}/confirm.

outcome*string

confirmed = codai solved it (billable); fail = it did not (never billed).

Value in"confirmed""fail"

note?string

Optional free-text note (trimmed), stored on the task.

Lengthlength <= 500

Response Body

The task is closed with the chosen outcome.

application/json

response

Outcome of the confirmation. Keys are camelCase, unlike the Task object.

taskId*string

Formatuuid

outcome*string

The outcome you sent.

Value in"confirmed""fail"

billed*boolean

True when this confirmation emitted a task_succeeded meter event.

refundedMicroEur*integer

Token cost returned to the prepaid wallet on conversion to a flat success charge, in EUR micros.

Range0 <= value

Example Request

curl -X POST 'https://ai.codai.ro/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08/confirm' \
  -H 'Content-Type: application/json' \
  -d '{
  "outcome": "confirmed"
}'

Example Request

curl -X POST 'https://ai.codai.ro/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08/confirm' \  -H 'Content-Type: application/json' \  -d '{  "outcome": "confirmed"}'

Example ResponseSchema

{
  "taskId": "e6e9d88a-9b63-468a-aec3-b7a11de27af8",
  "outcome": "confirmed",
  "billed": true,
  "refundedMicroEur": 0
}

{  "taskId": "e6e9d88a-9b63-468a-aec3-b7a11de27af8",  "outcome": "confirmed",  "billed": true,  "refundedMicroEur": 0}

Tasks

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Query Parameters

Header Parameters

Response Body

Authorization

Header Parameters

Response Body

Authorization

Query Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Request Body

Response Body