Sending a message is asynchronous.
POST /sessions/\{id}/messages returns 202 Accepted immediately — the agent runs in the background. To get the result, either poll GET /sessions/\{id} (with optional long-polling via wait=true) or include a webhook field in your request to receive a callback when the turn completes. See Webhooks for details.POST /sessions/{session_id}/messages
Send a message to a session. The agent processes it in the background and the endpoint returns immediately.Path parameters
string
required
The session UUID.
Request body
string | null
default:"null"
The text content of the message.
string
default:"user"
Message role. One of
"system", "user", "assistant", or "tool".object | null
default:"null"
Arbitrary key-value parameters passed through to the agent on the
ChatMessage object. Useful for per-request context such as user identity or feature flags.WebhookSpec | null
default:"null"
Webhook configuration to receive the turn result via HTTP callback instead of polling. See Webhooks for the full spec.
MessageRequest inherits from ChatMessage, so additional fields are also accepted: tool_calls, tool_call_id, name, and base64_image.Response
202 Accepted — returns a MessageResponse and a Location header pointing to the session.
Headers: Location: /sessions/\{session_id}
string
required
The session UUID.
string
required
Always
"running" immediately after a message is accepted.Errors
GET /sessions/{session_id}/messages
Retrieve the full conversation history managed by the agent for this session.Path parameters
string
required
The session UUID.
Response
200 OK — returns a list of ChatMessage objects in chronological order.
string
required
Message role:
"user", "assistant", "system", or "tool".string | null
required
Text content of the message.