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.

attached_workspaces
object[]

Other workspaces the agent may reach in this chat, each at workspaces/<alias>/ - the alias is assigned by the server the first time a workspace is added and never reused for another workspace in the same chat. Replaces the chat's current set when the turn starts; omit it to keep that set. Up to 5. A workspace you cannot read is dropped, and edit falls back to read without write access. Every write into one waits for the user's approval, so on an API call with no one to approve it the write is refused. Ignored on a chat a service account owns.

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.

notify_on_complete
boolean

Send a completion push to the acting user's registered devices after a successful answer. Defaults to false. No email or inbox row is created; service accounts do not receive this alert.

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.