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
The session UUID.
Request body
The text content of the message.
Message role. One of
"system", "user", "assistant", or "tool".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.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}
The session UUID.
Always
"running" immediately after a message is accepted.Errors
| Code | Condition |
|---|---|
404 | Session not found. |
409 | The session is already processing a message. |
GET /sessions/{session_id}/messages
Retrieve the full conversation history managed by the agent for this session.Path parameters
The session UUID.
Response
200 OK — returns a list of ChatMessage objects in chronological order.
Message role:
"user", "assistant", "system", or "tool".Text content of the message.
Errors
| Code | Condition |
|---|---|
404 | Session not found. |