Start a chat turn
Start a chat turn and receive the SSE Location.
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
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
Body
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).
The user's message text for this chat turn (plain UTF-8, non-empty).
1Optional per-turn user settings threaded into the graph as user_settings.
Optional client nonce for optimistic UI reconcile.
128Response
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.

