Skip to main content
POST
Run or resume a session

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

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.

Required string length: 1 - 255

Path Parameters

id
string
required

Client-provided session identifier. Use the same value across requests to continue the same agent session.

Required string length: 2 - 100
Pattern: ^[0-9a-zA-Z._:-]+$

Query Parameters

wait
boolean
default:false

When true, long-poll: block until the invocation's assistant response is available before returning.

wait_timeout
integer<int64>

Maximum time in seconds to block when wait=true. Omit to wait indefinitely. Ignored when wait is false.

Required range: x >= 1

Body

application/json
user_prompt
string
required

The user prompt driving this invocation.

model
object
required
tools
string[]

Names of the tools the model may call (e.g. "WEB_SEARCH").

system_prompt
string

System instructions for the model. Uses a default if omitted.

max_steps
integer

Max model steps before the run stops. Uses a default if omitted.

Required range: x >= 1
mcp_servers
object[]

MCP servers whose tools are offered to the model.

Response

Session run or resumed

session
object
required
messages
object[]
required