Skip to navigation

Send conversation message

Alpha

Send input to a conversation, and wait until the agent finishes or waits on client tool results. With background set to true, the endpoint returns 202 when the server admits the turn. Then stream the turn’s events with Last-Event-ID set to the stream_cursor. This endpoint is in alpha and may change.

Path parameters

conversation_idstringRequired
The Conversation ID

Headers

xi-api-keystringOptional

Request

This endpoint expects an object.
inputlist of objectsRequired

Either one user_message, which starts a new turn, or client_tool_result items, which answer the required_actions of the waiting turn and continue it. Calls that they leave out stay pending. Client tools wait with no timeout. While calls are pending, a user_message is rejected. A user_message can come with contextual_update items, at most one per context_id. client_tool_result items that answer every pending call can come with end updates.

backgroundbooleanOptionalDefaults to false
If true, return a 202 handle after the turn is admitted instead of waiting for generation to finish.

Response

Successful Response
turn_idstring
statusenum
Allowed values:
outputlist of objectsOptional
errorobject or nullOptional
required_actionslist of objectsOptional

The actions the agent waits on. Answer each client_tool_call with a client_tool_result item in input to continue.

stream_cursorstring or nullOptional

Resume token for this turn’s event stream. Present while the turn is in progress; pass it as Last-Event-ID to stream the turn’s events.

Errors

422
Unprocessable Entity Error