Skip to main content
POST
Start a chat turn for SSE streaming
Returns 202 with a Location of the SSE stream. Subscribe to Stream the turn. 409 if a turn is already running — the body names the stream to attach. The model usage of that turn is billed at 1.5×. Do not retry a 202 as a new POST.

Authorizations

Authorization
string
header
required

Organisation API key from Settings → API / /api/keys/. The secret is shown once. Send Authorization: Bearer sk-abacus-…. One active key per organisation. Ingest (/api/v2/ingest/*) refuses API keys — that surface is Auth0-only with ingest:read / ingest:write scopes.

Path Parameters

thread_id
string
required

Body

application/json

Body for POST /api/v2/chats/<thread_id>/messages/.

When CHAT_TURN_STREAMS_ENABLED is on (AD-404), the POST starts the durable turn immediately and message_id is the turn_id. When the flag is off, the legacy one-shot Redis buffer path is used.

Fields: message: The user's turn text. Plain UTF-8 (no base64 — that was a WebSocket-only transport detail). Non-empty. settings: Optional per-turn user settings (e.g. {"concise": true}), threaded into the graph as user_settings. Free-form to mirror the WebSocket user_settings payload; the graph ignores unknown keys. client_nonce: Optional opaque id for optimistic-paint dedup (AD-403/404).

message
string
required

The user's message text for this chat turn (plain UTF-8, non-empty).

Minimum string length: 1
settings
object

Optional per-turn user settings threaded into the graph as user_settings.

client_nonce
string | null

Optional client nonce for optimistic UI reconcile.

Maximum string length: 128

Response

202 response for POST /api/v2/chats/<thread_id>/messages/.

Mirrors the Location header. The client subscribes to stream_url (an EventSource / fetch-stream target) to receive the canonical StreamEvent sequence for this turn.

Fields: message_id: Durable turn_id when streams are enabled; otherwise the legacy one-shot buffer handle. stream_url: Relative path of the SSE stream endpoint for this turn.

message_id
string
required

Turn id / stream handle for this chat turn.

stream_url
string
required

Relative path of the SSE stream endpoint for this turn.