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. The key naming this invocation of the session, unique within your organization: reuse the same value to safely retry a request, read the invocation back with GET /traces/{invocation_key}, and use a new value to start 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_timeout_seconds
integer<int64>
default:1800

Wait up to this many seconds for the assistant response. Omit to wait up to 30 minutes; use 0 to return after the invocation is accepted.

Required range: 0 <= x <= 1800

Body

application/json
user_prompt
string
required

The user prompt driving this invocation.

agent_name
string
required

Human-readable name identifying the agent (e.g. "support-triage"). Invocations sharing a name are grouped as one agent; each distinct configuration under it becomes a revision.

agent
object
required

The agent configuration for an invocation: the model, tools, instructions, and MCP servers that define its behavior. Invocations with the same configuration share a revision.

Response

Session run or resumed

session
object
required
message
object

The assistant message this invocation produced. Absent when the invocation has not answered yet — a call with wait_timeout_seconds=0, or a wait that returned before the response existed. Use GET /sessions/{id} to read it later.