Start an agent run
Authorizations
Authorization: Bearer stefan_sk_... (API key — bills the API wallet) or stefan_oat_... (OAuth member token — bills your plan pool).
Headers
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.
^[A-Za-z0-9_.:-]{1,128}$Body
A chat_... id to continue. Omit it to start the run in a new chat, with or without project.
A proj_... id or project UUID. Without chat, the run starts in a new chat inside that project.
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.
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.
reject 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.
The latest assistant text, or null before there is any. It is the final answer only once status is completed.
Parsed JSON of the final answer for runs started with output_config; null when not requested or not completed.
Acceptance envelope only (msg_u_... id).
Acceptance envelope only (msg_a_... id).
Acceptance envelope only.
Acceptance envelope only.
Acceptance envelope only.

