Skip to main content
Start an agent run

Authorizations

Authorization
string
header
required

Authorization: Bearer stefan_sk_... (API key — bills the API wallet) or stefan_oat_... (OAuth member token — bills your plan pool).

Headers

Idempotency-Key
string

Safe blind retries: resubmitting the same key returns the ORIGINAL run's envelope (202 while it is running, the full status once it finished) — no second chat, no second billed run, and attachment staging is skipped. Dedupe window: the same UTC day, like the tools lane. 1-128 chars of A-Z a-z 0-9 _ . : -; invalid values are 400 invalid_idempotency_key.

Pattern: ^[A-Za-z0-9_.:-]{1,128}$

Body

message
string
required
chat
string

A chat_... id to continue. Omit it to start the run in a new chat, with or without project.

project
string

A proj_... id or project UUID. Without chat, the run starts in a new chat inside that project.

sync
boolean

Hold the connection until the run ends or the sync window closes: about 90 s, counted from when the request arrives (upload time included). A run that ends inside the window returns 200 with its final status; failed and cancelled runs also return 200, so check status. Otherwise the normal 202 envelope; finish by polling. Keyed replays answer at once. Set the HTTP client timeout to 120 s: a dropped connection or 504 does not stop the run.

on_busy
enum<string>

Busy-chat behavior. Only "reject" (default) is supported: an active run returns the 409 chat-busy error. Retry when the active run finishes or use a separate chat.

Available options:
reject
output_config
object

Structured output constraint: { format: { type: "json_schema", schema } }. The schema must satisfy strict mode (additionalProperties: false everywhere; every property listed in required).

Response

The run's final status: a sync-mode run ({ sync: true }) that ended inside the sync window (about 90 s from when the request arrived, upload time included), or a keyed replay of a run that already ended. Failed and cancelled runs also return 200; check status.

object
string
run_id
string
chat
string
status
string
output
string | null

The latest assistant text, or null before there is any. It is the final answer only once status is completed.

structured_output
object | null

Parsed JSON of the final answer for runs started with output_config; null when not requested or not completed.

turn_state
string | null
created_at
string<date-time> | null
started_at
string<date-time> | null
completed_at
string<date-time> | null
cancel_requested
boolean
last_error
string | null
project
string
user_message
string

Acceptance envelope only (msg_u_... id).

assistant_message
string

Acceptance envelope only (msg_a_... id).

status_url
string

Acceptance envelope only.

events_url
string

Acceptance envelope only.

cancel_url
string

Acceptance envelope only.