Run or resume a session
Runs the session with the given ID, creating it if it does not exist and resuming it otherwise. Each call is a single invocation, optionally identified by the Idempotency-Key header. Supplying a key makes the call safe to retry: retrying with the same key and an identical body re-attaches to the in-flight invocation and returns its current state; a differing body for the same key returns 409; a new key while another invocation is still running returns 423. Omitting the header starts a fresh, non-idempotent invocation each time; the server generates a key and returns it in the Idempotency-Key response header.
With wait=true the request long-polls: it blocks until the invocation’s assistant response is available and returns it in messages. wait_timeout bounds the wait in seconds; when omitted the request waits indefinitely (until the response arrives or the client disconnects). If the timeout elapses first, the request fails with 504 and a JSON body, letting the client distinguish an expected server-side timeout from a transport error; the client may retry.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Optional but strongly encouraged. Uniquely identifies this invocation of the session; reuse the same value to safely retry a request, and a new value starts a new invocation. When omitted, the server generates a key for the invocation and returns it in the Idempotency-Key response header, but the request is not retry-safe.
1 - 255Path Parameters
Client-provided session identifier. Use the same value across requests to continue the same agent session.
2 - 100^[0-9a-zA-Z._:-]+$Query Parameters
When true, long-poll: block until the invocation's assistant response is available before returning.
Maximum time in seconds to block when wait=true. Omit to wait indefinitely. Ignored when wait is false.
x >= 1Body
The user prompt driving this invocation.
Names of the tools the model may call (e.g. "WEB_SEARCH").
System instructions for the model. Uses a default if omitted.
Max model steps before the run stops. Uses a default if omitted.
x >= 1MCP servers whose tools are offered to the model.