codai docs
API referenceGateway

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.

GET
/v1/tasks

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

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

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/tasks"
{  "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
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/tasks/pending"
{  "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
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Query Parameters

since?string

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

Formatdate-time

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/tasks/stats"
{  "since": "2019-08-24T14:15:22Z",  "opened": 0,  "confirmed": 0,  "pass": 0,  "unconfirmed": 0,  "billed": 0}
GET
/v1/tasks/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Task UUID.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "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
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Task UUID.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/tasks/497f6eca-6276-4993-bfeb-53cbbbba6f08/confirm" \  -H "Content-Type: application/json" \  -d '{    "outcome": "confirmed"  }'
{  "taskId": "e6e9d88a-9b63-468a-aec3-b7a11de27af8",  "outcome": "confirmed",  "billed": true,  "refundedMicroEur": 0}

Tools

Verified web search and safe page fetching, the same tools the agent loop uses.

Sessions

Shared-sessions protocol v2: event log, controls, executor lease, dispatch and the live SSE stream.