Send a user message, cancel the current turn, or return a function call result to a session.
Endpoint
POST /agents/sessions/{session_id}/events
Returns 202 Accepted with an empty body. The response may include an x-request-id header.
A 202 means the input was durably accepted and delivery was scheduled. It does not mean the model has consumed the input or the turn has completed. Use SSE, the turn terminal status, and item history to determine the result.
Path parameterssession_idstring (required)Session ID, for example sess_xxxRequest bodyeventsarray<object> (required)Event array. An empty array [] is an empty batch and produces no inputChoose one of the following event structures based on type.
Event types
agent.session.input.message type string (required)Fixed to agent.session.input.message.input array<object> (required)Array of user messages. Must not be empty.
input item role string (required)Message role, fixed to user.content array (required)Content part array. Must not be empty.
content item type string (required)Content part type: input_text or input_image.text string (conditional)Text content.image_url string (conditional)Image URL.
agent.session.input.cancel type string (required)Fixed to agent.session.input.cancel. Only type is accepted; turn_id and other fields are rejected.
agent.session.input.tool_result type string (required)Fixed to agent.session.input.tool_result.turn_id string (required)Public turn ID from required_actions.call_id string (required)Function call ID.success boolean (required)Whether the call succeeded.output string or array / null (conditional)Function output; a string, or an array of input_text / input_image.error string / null (conditional)Failure message.input field for message is an array, not the string shorthand used when creating a session. cancel cancels only the current turn. Fields from other branches and unknown fields are rejected. | Request example |
Function calling
After the model initiates a function call, the session's required_actions contains a pending item:
arguments is already parsed into an object; do not parse it again as a JSON string. After a client restart, retrieve the session and read required_actions before continuing.
Idempotency
You can send an Idempotency-Key header:
- The key must be 1–256 characters. An empty or oversized key returns
400. - Retrying with the same session, key, and content reuses the acceptance result and does not deliver the input again.
- The same key with different content returns
409 conflict_error. - A batch containing only
cancelis the current-cancel exception: retrying with the same key still applies to the current turn at that time. - Without the header, the API does not provide request-level automatic deduplication.
- A batch containing only messages is merged into one user input in array order. A mixed batch is processed item by item; a semantic failure in a later item does not roll back items already accepted.
Response example
202 Accepted with no response body. Acceptance does not mean the model has consumed the tool result or the turn has completed.
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix the request structure and event content; use a non-empty Idempotency-Key of 1-256 characters |
404 | not_found_error / not_found_error | Use a session ID that exists and has not been deleted in the current workspace |
409 | conflict_error / conflict_error | Confirm the current resource state; reuse the same request content for the same Idempotency-Key |
503 | server_error / agents_api_upstream_unavailable | Retry later. If it keeps failing, submit a ticket with x-request-id |