Agents

Run a server-side agent synchronously or as an async run you poll, stream or cancel.

The agents API wraps the gateway's own tool-using loop. Synchronous runs return the answer inline; async runs return 202 with an id you poll, stream over SSE (full replay on reconnect — no Last-Event-ID) or cancel. Concepts and limits: agents guide.

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body of POST /v1/agents/run.

task*string

The goal, in natural language. Becomes the user turn.

Length1 <= length <= 64000

context?string

Optional supporting material, appended to the task under a ## Context heading.

Lengthlength <= 256000

system?string

Optional system-prompt override, sent as the first message before the agent scaffold.

Lengthlength <= 32000

model?string

Model alias to route through.

Lengthlength <= 128

Default"codai"

max_steps?integer

Requested agent-loop depth cap. Validated but not enforced — the tier's agent-mode depth applies.

Range1 <= value <= 16

Response Body

`application/json`

curl -X POST "https://example.com/v1/agents/run" \  -H "Content-Type: application/json" \  -d '{    "task": "Find the three most recent BNR EUR/RON rates and summarise the trend."  }'

{  "result": "string",  "status": "completed",  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0  },  "model": "string",  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"}

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body of POST /v1/agents/runs; extends the synchronous request.

task*string

The goal, in natural language. Becomes the user turn.

Length1 <= length <= 64000

context?string

Optional supporting material, appended to the task under a ## Context heading.

Lengthlength <= 256000

system?string

Optional system-prompt override, sent as the first message before the agent scaffold.

Lengthlength <= 32000

model?string

Model alias to route through.

Lengthlength <= 128

Default"codai"

max_steps?integer

Requested agent-loop depth cap. Validated but not enforced — the tier's agent-mode depth applies.

Range1 <= value <= 16

budget_seconds?integer

Requested wall-clock budget. Stored (default 300) but not enforced.

Range10 <= value <= 1800

client_request_id?string

Idempotency key scoped to your user — a repeat returns the existing run id.

Lengthlength <= 200

Response Body

`application/json`

curl -X POST "https://example.com/v1/agents/runs" \  -H "Content-Type: application/json" \  -d '{    "task": "Find the three most recent BNR EUR/RON rates and summarise the trend."  }'

{  "id": "3f9d2c1e-7b4a-4e0f-9a1d-2c5b6e7f8a90",  "status": "queued",  "poll": "/v1/agents/runs/3f9d2c1e-7b4a-4e0f-9a1d-2c5b6e7f8a90"}

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

days?integer

Window length in days, clamped to 1–90.

Range1 <= value <= 90

Default7

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`

curl -X GET "https://example.com/v1/agents/runs/stats"

{  "window_days": 1,  "total": 0,  "completed": 0,  "failed": 0,  "cancelled": 0,  "in_flight": 0,  "prompt_tokens": 0,  "completion_tokens": 0,  "avg_steps": 0,  "avg_latency_ms": 0}

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

Agent run UUID returned by POST /v1/agents/runs.

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`

curl -X GET "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "queued",  "task": "string",  "model": "string",  "result": "string",  "error": "string",  "step_count": 0,  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0  },  "created_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z"}

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

Agent run UUID returned by POST /v1/agents/runs.

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`

curl -X GET "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/steps"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "steps": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "runId": "78c33d18-170c-44d3-a227-b3194f134f73",      "seq": 0,      "kind": "plan",      "summary": "string",      "detail": null,      "latencyMs": 0,      "createdAt": "2019-08-24T14:15:22Z"    }  ]}

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

Agent run UUID returned by POST /v1/agents/runs.

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

`text/event-stream`

`application/json`

curl -X GET "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/stream"

"string"

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

Agent run UUID returned by POST /v1/agents/runs.

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`

curl -X POST "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "cancelled"}

200application/json

400application/json

401application/json

402application/json

403application/json

429application/json

502application/json

202application/json

400application/json

401application/json

402application/json

403application/json

200application/json

401application/json

402application/json

200application/json

401application/json

402application/json

404application/json

200application/json

401application/json

402application/json

404application/json

200text/event-stream

401application/json

402application/json

404application/json

200application/json

401application/json

402application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`