Send a chat message

post

https://api.getkronos.ai/api/chat

Sends a message to an agent and returns its reply. This is the core endpoint of the API distribution channel.

Response mode

Streaming (default when messages is provided, or stream: true) — a text/event-stream of Server-Sent Events (Vercel AI UI message stream; x-vercel-ai-ui-message-stream: v1).
JSON (stream: false) — a single JSON object with the agent reply.

Set agent_id to target a specific agent. When omitted, the agent configured on the API distribution that owns the key is used. Pass conversation_id to continue an existing thread.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

messages

array of objects

Conversation history in useChat format. The last user message is the prompt. Provide either messages or message.

messages

message

string

Legacy single-message field. Use messages for new integrations.

agent_id

uuid

The agent to send the message to. On API-key-authenticated requests this is ignored — the reply always comes from the agent configured on the API distribution that owns the key. (Honored only on internal session-authenticated calls.)

agent_version_id

uuid

Pin the response to a specific published agent version.

conversation_id

string

Stable, caller-supplied conversation key — a string (e.g. ULID, UUID, or a stringified integer). Maps to an internal session so a stateless caller can continue a thread without round-tripping session_id; ignored when session_id is also sent. Supplying it also enables per-conversation concurrency on the JSON (stream: false) path: a newer request for the same conversation supersedes an in-flight one, and the superseded request returns 409 (not retryable — the newer request carries the answer). Omit to start a new conversation.

channel

string

Channel label recorded on the conversation (for analytics and routing).

source

string

Free-form source label recorded on the conversation.

show_citations

boolean

Defaults to false

Include source citations in the response.

show_reasoning

boolean

Defaults to false

Include the agent reasoning trace in the response.

show_tool_calls

boolean

Defaults to false

Include tool-call events in the response.

contact_email

string

Visitor's email. Attaches the conversation to a contact.

contact_name

string

Visitor's name. Attaches the conversation to a contact.

prechat

object

Widget only. The pre-chat form's answers, sent with the first message of a new conversation and ignored on any other request.

mock_visitor_attributes

array of objects

Playground only. Simulated visitor attributes used to build the "Current visitor" context for a test run, so an author can verify instructions that reference a contact property without a real visitor. Ignored unless source is playground; never persisted.

mock_visitor_attributes

mock_verified_user

object

Playground only. Simulate a verified (identity-verified) visitor without signing a JWT — sets the trusted {{user.*}} namespace directly so an author can test tools/prompt behaviour for an identified visitor. Ignored unless source is playground; never persisted. Optional token fills {TOKEN}, for testing a tool that forwards the visitor's ID token upstream — on a real turn that value is the JWT the server just verified.

visitor_token

string

Stable visitor token that ties messages to one contact across requests. Reuse the value returned on the first response.

user_jwt

string

Customer-signed HS256 JWT proving the visitor identity (identity verification). Sign it on your backend with the workspace secret from Settings → Identity verification; carry user_id (required) and optionally email + custom claims. When the workspace is in log/enforce mode, a valid token writes the identity as verified; an invalid token only downgrades the identity and never blocks the message. The API-distribution equivalent of the widget's kronos('boot', { user_jwt }).

auth_tokens

object

Per-user auth tokens for custom tools (a map of named opaque bearer tokens). Forwarded verbatim to a custom tool as the {{auth_tokens.NAME}} template variable (e.g. Authorization: Bearer {{auth_tokens.my_api}}), letting the tool call your backend as this visitor. Never parsed, persisted, or logged. The API-distribution equivalent of the widget's kronos('setAuthTokens', { my_api: '<token>' }).

attachments

array of objects

File attachment references (e.g. the result of POST /chat/upload).

attachments

stream

boolean

Stream the response as Server-Sent Events. Defaults to true when messages is provided, false otherwise. When false, a single JSON object is returned.

Responses

200

Agent reply. An SSE stream when streaming, or a single JSON object when stream is false.

400

Message content is required.

409

JSON mode only. The run was superseded by a newer request on the same conversation_id. Body: { session_id, superseded: true, message: null }. Not retryable — the newer request carries the answer.