Skip to main content
POST
Submit one user turn to an existing chat session.

Idempotency

Network retries (especially over SMS) can re-submit the same logical turn twice. Always send an idempotency_key (any client-chosen unique value, e.g. UUID or sessionId+turnNumber) so the server can dedupe. The retry returns the prior assistant response — including when the original turn finalised the session.

Path Parameters

id
string<uuid>
required

Body

Request body for POST /api/v1/chats/{id}/messages — submits a single user turn to the named session. The response contains only the assistant turn(s) produced this round, not the full transcript (the transcript lives on the server and is retrievable via GET /api/v1/chats/{id}).

content
string | null

User-supplied message content for this turn.

idempotency_key
string | null

Optional idempotency key. When supplied, a retried submit with the same key returns the previous assistant response without re-running the LLM. Bound to the session, not global. Capped at 128 characters.

additional_data
object | null

Turn-level additional_data overrides merged on top of the session's persisted bag. Reserved keys (DashaAI.BlackBox.AgentAPI.TextChat.ChatReservedKeys) are dropped before merge.

Response

Submit succeeded. Inspect is_final to decide whether to keep submitting.

Response to POST /api/v1/chats/{id}/messages. Returns only the new assistant turn(s) produced this round (per the plan's "returns only the new assistant turn(s)" requirement), plus the post-turn session status so clients don't need a follow-up GET to learn whether the agent finished the conversation.

messages
object[] | null

New messages produced this turn. Ordered: assistant tool-turns first (each bundling its tool calls with their executed responses), final plain-text assistant reply last.

is_final
boolean

True when the agent signalled end-of-conversation this turn (e.g. invoked the finishTheConversation built-in tool) and the session has been finalised. After this point, further submits return 409 Conflict.

status
string | null

Post-turn session status: active while accepting new turns, final after finalisation (matches the state filter on the list endpoint).

sources
object[] | null

Knowledge base documents this turn's answer drew on, deduplicated by document and in rank order. Present when the agent has a knowledge base enabled (features.rag); empty when the search found nothing or failed. Omitted when the agent has no knowledge base enabled, and on an idempotent replay of an earlier turn. With features.rag.mode "tool", the documents of every search the agent ran this turn, each with its best score, most relevant first; empty when the agent did not search.

grounding
object | null

How this turn used the agent's knowledge bases: the mode and the number of searches. Omitted on an idempotent replay of an earlier turn.