Skip to content
Dot
DocsSign inGet started

Chat API

Send a message to a chatbot and stream the reply.

POST/api/v1/public/chatBearer API key

Send a turn to a chatbot and stream the reply as Server-Sent Events.

This is the same pipeline the widget and the playground use: knowledge is retrieved, the model streams a reply, and the conversation and its token usage are recorded against your workspace on the api channel.

Request

FieldTypeRequiredNotes
chatbotIdstring (uuid)YesA chatbot in the key's workspace. It must be Active.
messagesarrayYes1–60 turns of { role, content }, where role is user or assistant. Content is 1–8000 characters.
conversationIdstring (uuid)NoContinues an existing conversation. Omit it to start a new one.
Request body
{
  "chatbotId": "b3f1c0de-0000-4000-8000-000000000000",
  "messages": [
    { "role": "user", "content": "Do you ship to the EU?" }
  ]
}

Send the whole visible transcript on each turn, not just the newest message: the platform stores what it receives and passes the history to the model. Only the latest user message is recorded as a new message.

Response

200 OK with Content-Type: text/event-stream. Each line is a data: frame holding one JSON event. The stream always ends with a done event.

Stream
data: {"type":"tool-result","id":"conversation","result":{"conversationId":"…"}}

data: {"type":"start","id":"gen_…","model":"…"}

data: {"type":"sources","sources":[{"id":"…","title":"Shipping policy","snippet":"…"}]}

data: {"type":"text-delta","delta":"Yes — EU orders "}

data: {"type":"text-delta","delta":"ship in 2–4 days."}

data: {"type":"usage","usage":{"inputTokens":412,"outputTokens":38}}

data: {"type":"done","finishReason":"stop"}

Event types

EventPayloadMeaning
tool-result (id conversation){ conversationId }Sent first. Keep it to continue the conversation on the next call.
start{ id, model }Generation began.
sources{ sources[] }Knowledge passages the answer may cite as [n].
text-delta{ delta }A fragment of the reply. Concatenate in order.
tool-call / tool-result{ id, name, arguments } / { id, result }Tool activity, on agent-backed runs.
usage{ inputTokens, outputTokens }Token counts for the turn.
done{ finishReason }stop, length, tool_calls, cancelled or error.
error{ message, code }Generation failed. A done with error always follows.

Cancelling

Abort the HTTP request to stop generation. The server notices the disconnect, stops the model, and records the conversation up to that point.

Failure modes

StatusCodeWhen
401unauthorizedMissing, malformed or revoked API key.
403forbiddenThe chatbot exists but is not Active.
404not_foundNo chatbot with that id in this workspace. Another tenant's id is indistinguishable from a missing one.
422validation_errorThe body failed validation; details names the fields.
429rate_limitedA ceiling was hit. See rate limits.

See errors for the envelope, and examples for working clients.