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.

POST

/v1/agents/run

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

Request Body

application/json

body

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

The completed run.

application/json

response

Response of POST /v1/agents/run.

result*string

The final assistant answer (empty string when the model produced no content).

status*"completed"

Value in"completed"

usage*

Aggregate token counts for the whole run.

model*string

Concrete upstream model that served the final turn.

event_id*|

Usage event id for feedback correlation; null when none was written.

Formatuuid

Example Request

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

Example Request

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

Example ResponseSchema

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

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

POST

/v1/agents/runs

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

Request Body

application/json

body

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

Run accepted and queued.

application/json

response

Response of POST /v1/agents/runs (HTTP 202).

id*string

Formatuuid

status*"queued"

Always queued at submit time, even when an idempotent repeat hits a run that has since progressed.

Value in"queued"

poll*string

Relative URL of the poll endpoint for this run.

Example Request

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

Example Request

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

Example ResponseSchema

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

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

GET

/v1/agents/runs/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

days?integer

Window length in days, clamped to 1–90.

Range1 <= value <= 90

Default7

Header Parameters

Response Body

Aggregates for the window.

application/json

response

Aggregates over your runs in the window. Only window_days and total are guaranteed; the remaining fields are absent for legacy compatibility keys that cannot own persisted runs.

window_days*integer

Range1 <= value <= 90

total*integer

Range0 <= value

completed?integer

Range0 <= value

failed?integer

Range0 <= value

cancelled?integer

Range0 <= value

in_flight?integer

Runs currently queued or running.

Range0 <= value

prompt_tokens?integer

Range0 <= value

completion_tokens?integer

Range0 <= value

avg_steps?integer

Rounded average of step_count.

Range0 <= value

avg_latency_ms?integer

Rounded average of finished_at - started_at over finished runs.

Range0 <= value

Example Request

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

Example Request

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

Example ResponseSchema

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

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

GET

/v1/agents/runs/{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

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

Formatuuid

Header Parameters

Response Body

The run.

application/json

response

Poll view of a persisted run (GET /v1/agents/runs/{id}).

id*string

Formatuuid

status*AgentRunStatus

Run lifecycle — queued → running → one of completed, failed, cancelled.

Value in"queued""running""completed""failed""cancelled"

task*string

The submitted goal, verbatim.

model*|

Requested model alias (codai when omitted at submit).

result*|

Final answer; set only once status is completed.

error*|

Failure message (≤ 2000 chars); set only when status is failed.

step_count*integer

Loop steps executed so far. Not incremented by the current executor.

Range0 <= value

usage*

Aggregate token counts for the whole run.

created_at*string

Formatdate-time

started_at*|

When execution was claimed; null while queued.

Formatdate-time

finished_at*|

Set on completed, failed and cancelled.

Formatdate-time

Example Request

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

Example Request

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

Example ResponseSchema

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

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

GET

/v1/agents/runs/{id}/steps

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

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

Formatuuid

Header Parameters

Response Body

The step trace.

application/json

response

id*string

The run id.

Formatuuid

steps*array<>

Example Request

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

Example Request

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

Example ResponseSchema

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

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

GET

/v1/agents/runs/{id}/stream

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

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

Formatuuid

Header Parameters

Response Body

SSE stream; see the description for event names and payloads.

response?stringtext/event-stream

Example Request

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

Example Request

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

Example ResponseSchema

"string"

"string"

POST

/v1/agents/runs/{id}/cancel

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

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

Formatuuid

Header Parameters

Response Body

The run is now cancelled.

application/json

response

id*string

Formatuuid

status*"cancelled"

Value in"cancelled"

Example Request

curl -X POST 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel'

Example Request

curl -X POST 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel'

Example ResponseSchema

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

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

Agents

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy 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

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

Response BodyCopy Anchor Link

Authorization

Header Parameters

Request Body

Response Body

Authorization

Header Parameters

Request Body

Response Body

Authorization

Query Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body

Authorization

Path Parameters

Header Parameters

Response Body