Send Events

Call Create session first and replace the example session ID with its returned ID.

POST /agent/v1/sessions/{session_id}/events◐ Partial

Request parameters

session_idstring必填
path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.
eventsarray必填
Events to send to the session.

Returns

200

Each user.message accepts exactly one nonempty text block. Replace sesn_123 with your session id. Text user.message, user.interrupt and tool confirmation are supported. To guide a running turn, send a user.steer event with event_id referencing a queued user.message. Current tools continue; the message enters the next model request. The user.steer receipt has its own processed_at; repeated marking returns the same receipt. Processing or withdrawn inputs return 409; missing events return 404. Pending approvals defer injection. If the turn ends first, the input runs normally from the queue. Ordinary messages remain queued by default. This extension is unavailable on /anthropic. The response acknowledges inputs; read replies from event history or the stream. A user.message sent while the session waits for tool approval is queued: the returned event has processed_at null and runs in order once the approval is resolved. When allowing a tool call, copy its permission_suggestions into updated_permissions to remember similar operations for this conversation; dangerous operations offer no suggestions to remember. When searching or reading web pages, tool results use official search_result blocks on both API surfaces. Answer text blocks carry citations as an /agent/v1 extension; /anthropic renders answer references as [n] in the text.

Errors follow the Anthropic error format (type / message / request_id) — see error codes

Response

HTTP 200

Successful response

application/json

Name	Type	Description
data	array<object>	Sent events
data[].id	string	Unique identifier for this event. / Event id, unique within the session. Use it to refer to this event, for example in user.tool_confirmation or user.steer. / Event id, unique within the session.
data[].content	array<object>	Array of content blocks comprising the user message. / The result content returned by the tool. / The result content returned by the tool. / System content blocks. Text-only.
data[].type	string	Always `user.message`. A message from the user to the agent, with content blocks. / Always `user.interrupt`. The user interrupted the running turn. / Always `user.tool_confirmation`. The user's decision to allow or deny a tool call that waits for approval. / Always `user.custom_tool_result`. The user's result for a custom tool call. / Always `user.define_outcome`. The user defined the outcome the agent should reach. / Always `user.tool_result`. The user's result for a client-side tool call. / Always `system.message`. A message produced by the platform rather than the user or the agent. / Always `user.steer`. Receipt that a queued user.message was injected into the running turn. / Always `user.tool_confirmation`.
data[].processed_at	null \| string \| string \| null \| string \| null \| string \| string \| string	A timestamp in RFC 3339 format / RFC 3339 time at which the server processed the event; null while a queued input has not started running. / When the event was recorded, RFC 3339.
data[].session_thread_id	null \| string	If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. / Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread. / Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.
data[].result	string	UserToolConfirmationResult enum / Always `allow`.
data[].tool_use_id	string	The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` event's `stop_reason.event_ids` field. / The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` event's `stop_reason.event_ids` field. / The id of the AskUserQuestion `agent.tool_use` event this answers.
data[].deny_message	null \| string	Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
data[].custom_tool_use_id	string	The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` event's `stop_reason.event_ids` field.
data[].is_error	null \| boolean	Whether the tool execution resulted in an error.
data[].description	string	What the agent should produce. Copied from the input event.
data[].max_iterations	null \| number	Evaluate-then-revise cycles before giving up. Default 3, max 20.
data[].outcome_id	string	Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
data[].rubric	object	Rubric for grading the quality of an outcome.
data[].event_id	string	Id of the event this event refers to.
data[].answers	object	The user's answer to each question, keyed by the question text; empty when the questions were dismissed.
data[].annotations	object	Per-question notes, keyed by the question text.