Skip to main content
POST
Start an agent run

Authorizations

Authorization
string
header
required

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

Body

application/json

Send message for plain text. chat_id is optional - omit it and a new chat is created on the first send.

message
string
required

The user message to run. Required unless you send parts.

chat_id
string

Chat to run the turn on. A new chat is created when omitted.

workspace_id
string

Workspace the agent works in. Without it the agent has no files and no sandbox.

organization_id
string

Organization context. Defaults to the credential's organization.

model
string

Model id, for example anthropic/claude-haiku-4.5. Defaults per organization.

reasoning_effort
enum<string>

Reasoning depth. Clamped to what the selected model supports.

Available options:
none,
low,
medium,
high
max_tool_iterations
integer

Maximum tool-use rounds for this turn, from 1 to 100.

read_only
boolean

Run with read-only tools, so the turn cannot modify the workspace.

disabled_skills
string[]

Workspace skill names to withhold from this turn.

disabled_agents
string[]

Subagent names to withhold from this turn.

message_id
string

Client-supplied UUID for the user message. Generated when omitted.

Response

Successful response

The response is of type object.