Send Event
Writes events to a session: user messages, interrupts, tool approvals, and function result backfills. The request body contains only the top-level input field, which is an array of events (length 1-50).
Prerequisites
A session must already be created. For details, see Create Session.
Endpoint
POST /sessions/{session_id}/events
The request body contains only one top-level field input, which is an array of events (length 1-50). Each event must contain at least role and type.
Request body structure
{
"input": [
{ "role": "user", "type": "message", "content": [...] }
]
}
Client event types
type | role | Purpose and key fields |
|---|---|---|
message | user | Sends a user message, triggering the agent to enter running. Required: content (array) |
interrupt | user | Interrupts the current turn; the session returns to idle. Optional top-level session_thread_id (in multi-agent scenarios, targets the interrupt at a specific sub-thread) |
tool_approval_response | user | Responds to a tool approval. content is a single data block; data must contain batch_id, call_id, and result (allow / deny); optional deny_message (only for deny, passed back to the model as tool output). Multiple tool_approval_response in the same request must belong to the same batch_id |
function_call_output | tool | Backfills the execution result of a self-hosted function. content is a single data block; data must contain call_id and output (string); optional top-level is_error, session_thread_id |
tool_call_output | tool | Backfills the execution result of a self-hosted platform built-in tool, with the same structure as function_call_output (content contains call_id + output; optional top-level is_error, session_thread_id) |
interrupt and a plain message may be sent together in the same request; the semantics are: finish the current approval batch first, then start chatting.
NoteThe
batch_id and call_id of tool_approval_response together identify an approval (a composite identity, both non-empty); do not match on call_id alone, and do not deduplicate by call_id at the session level. Tool approval is only supported on the main agent, not in sub-agents.ContentBlock: message content
content is an array of ContentBlocks. Each block is distinguished by type and must use exactly one carrier.
type | Mutually exclusive fields | Description |
|---|---|---|
text | text | Plain text |
image | image_url / file_id (choose one) | Image, enters the model's vision channel: public URL or uploaded file ID (dereferenced to a temporary URL, rendered for this turn only, not persisted) |
video | video_url / file_id (choose one) | Video, enters the model's vision channel: public URL or uploaded file ID |
audio | data + format / file_id (choose one) | Audio: only appears in server-side pushes/responses (as a tool output attachment); cannot be sent as client input |
file | file_id + filename | File: uploaded file ID, requires filename (used for the sandbox path and file manifest). Base64 input is not supported. The file is materialized to the session sandbox by the platform, and the model reads it on demand. file_id is the persistent source of truth |
data | data (object) | Structured data (JSON). Server-side status events also use this carrier |
refusal | refusal | Model refusal message; only appears in server-side pushes |
Example: send a text message
curl -X POST "$AGENTSTUDIO_URL/sessions/sesn_01K8ZQX3/events" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": [
{
"role": "user",
"type": "message",
"content": [
{"type": "text", "text": "Analyze Q3 sales trends in /mnt/session/uploads/sales.csv"}
]
}
]
}'
client.sessions.events.send(
"sesn_01K8ZQX3",
events=[user_message("Analyze Q3 sales trends in /mnt/session/uploads/sales.csv")],
)
client.sessions().events().send("sesn_01K8ZQX3",
Collections.singletonList(
ClientEvents.userMessage("Analyze Q3 sales trends in /mnt/session/uploads/sales.csv")));
Response
200 OK returns the echo of the successfully written events and the request ID:
{
"data": [
{
"object": "message",
"id": "msg_8f2a1c...",
"created_at": "2025-10-24T08:15:30.123Z",
"role": "user",
"type": "message",
"status": "completed",
"content": [{"type": "text", "text": "..."}]
}
],
"request_id": "req_01K8ZQX..."
}
NoteA 200 only means the events were enqueued successfully; it does
not mean the agent has started processing or that a ruling has taken effect — especially fortool_approval_response, acceptance of the event does not mean the approval has been ruled and applied. Observe actual processing results via the SSE event stream or a subsequent GET /events.Response fields
| Field | Type | Description |
|---|---|---|
data | array<object> | Array of echoed accepted events, aligned with the request input order; the echo only means the event was enqueued, not that it has been processed or that a ruling has taken effect |
data[].object | string | Object type, always message |
data[].id | string | Server-assigned message ID, format msg_<ULID> |
data[].created_at | string | Server write time, ISO 8601 |
data[].role | string | Event role, echoes the user from the request |
data[].type | string | Event type, echoes the type of the sent event (e.g., sending message echoes message; sending tool_approval_response echoes tool_approval_response), not always message |
data[].status | string | Write status, always completed |
data[].content | array<object> | ContentBlock array, same structure as the request |
request_id | string | Unique identifier of this request |