cURL
Write events to a session to trigger agent processing.
Images and videos enter the model's multimodal visual channel; files are materialized by the platform into the session sandbox filesystem, and the model reads them on demand via tools.
For matching, dedup, and mixed-input rules, see the Tool approval section below.
Responds to a tool approval request.
Matching and dedup
Neither is a synchronous 4xx of this POST; observe via the SSE event stream or
Valid example:
input is an array of events (length 1–50); each event takes one of the following by type:
| type | role | Description |
|---|---|---|
message | user | Send a user message and trigger the agent into running; content supports four content block types — text, image, video, and file. See Content blocks |
interrupt | user | Interrupt the current turn; the session returns to idle; optionally specify session_thread_id to interrupt a sub-thread |
tool_approval_response | user | Respond to tool approval; see the Tool approval section below for the rules |
function_call_output | tool | Return the execution result of a self-hosted function |
tool_call_output | tool | Return the execution result of a self-hosted platform built-in tool |
interrupt and a plain message may be mixed in the same request (semantics: end the current approval batch first, then start chatting).
Content blocks
Images and videos enter the model's multimodal visual channel; files are materialized by the platform into the session sandbox filesystem, and the model reads them on demand via tools.
| type | Carrier field | Description |
|---|---|---|
text | text | Plain text |
image | image_url, file_id | Image; enters the model's visual channel; file_id is dereferenced by the platform into a temporary URL, rendered only for this turn and not persisted |
video | video_url or file_id | Video; enters the model's visual channel; same for file_id |
file | file_id + filename | File/document; materialized into the sandbox and read on demand by the model; filename is the file name, used for the sandbox path and manifest display |
Fields per event type
message
| Field | Type | Required | Description |
|---|---|---|---|
role | string | Yes | user |
type | string | Yes | message |
content | array | Yes | Content block array; supports text/image/video/file. See Content blocks |
interrupt
| Field | Type | Required | Description |
|---|---|---|---|
role | string | Yes | user |
type | string | Yes | interrupt |
session_thread_id | string | No | Target a sub-thread for interruption when multiple agents are involved |
tool_approval_response
| Field | Type | Required | Description |
|---|---|---|---|
role | string | Yes | user |
type | string | Yes | tool_approval_response |
content | array | Yes | Exactly one data block, containing batch_id, call_id, and result (allow/deny); optionally deny_message |
function_call_output / tool_call_output
| Field | Type | Required | Description |
|---|---|---|---|
role | string | Yes | tool |
type | string | Yes | function_call_output or tool_call_output |
content | array | Yes | A single data block containing call_id and output (string) |
is_error | boolean | No | true when execution failed or was interrupted |
session_thread_id | string | No | Route to a sub-agent thread |
Tool approval tool_approval_response
Responds to a tool approval request. content is a single data block with the following data fields:
| Field | Required | Description |
|---|---|---|
batch_id | Yes | Batch ID of the corresponding tool_approval_request |
call_id | Yes | ID of the tool call awaiting a decision |
result | Yes | allow or deny |
deny_message | No | Returned to the model as tool output only when deny |
batch_id+call_idjointly identify one approval (composite identity); both must be non-empty- Matching by
call_idalone is not allowed, nor is session-level dedup bycall_id— different batches may legitimately reuse the samecall_id - Multiple
tool_approval_responseentries in the same request must belong to the samebatch_id
pending_call_ids is unchanged):
| Input combination | Result | Error code |
|---|---|---|
tool_approval_response + plain message | Fed back later via a pending_tool_approval_unresolved event / terminal state | — |
tool_approval_response + interrupt | Rejected due to control-message conflict | invalid_tool_approval |
GET /events. interrupt and a plain message may be mixed in the same request (semantics: end the current approval batch first, then start chatting).
Scope: Tool approval is supported only for the main agent, not for sub-agents.
content validation
content must be exactly one data block. Counter-examples (all should be rejected):
| Example | Reason |
|---|---|
content: [] | Empty array |
content: [{}] | Missing type and data |
content: [{"type":"data"}] | Missing data |
data: {"batch_id":"","call_id":"call_xxx","result":"allow"} | Empty batch_id |
data: {"batch_id":"b","call_id":"","result":"allow"} | Empty call_id |
content: [{"type":"data","data":{"batch_id":"...","call_id":"...","result":"allow"}}], or result set to deny with deny_message.