Messages API

Send messages and retrieve history on Direct API deployments. Widget embeds use the Widget messages endpoint instead.

Endpoints

Method	Path	Description
`POST`	`/api/v1/messages`	Send message (sync or stream)
`GET`	`/api/v1/messages/{id}`	Get single message
`GET`	`/api/v1/conversations/{id}/messages`	List messages in conversation

Requires API key auth with access to the deployment.

Send message (synchronous)

POST /api/v1/messages
Authorization: Bearer ch_live_xxx
Content-Type: application/json

{
  "deployment_id": "dep_api_xyz",
  "conversation_id": "conv_8mN4pQ1r",
  "role": "user",
  "content": "What is your refund policy?"
}

Response 200:

{
  "id": "msg_2kL7nP9q",
  "conversation_id": "conv_8mN4pQ1r",
  "role": "assistant",
  "content": "Our refund policy allows returns within 30 days…",
  "citations": [
    { "document_id": "doc_1aB3c", "title": "Refund Policy", "snippet": "…" }
  ],
  "created_at": "2026-07-16T10:05:00Z"
}

Omit conversation_id on the first message to start a new thread; the response includes the new conversation_id.

Streaming

Set stream: true to receive Server-Sent Events. Event types match the widget stream:

Event	Purpose
`step_message`	Progress text
`tool_call`	Tool started
`tool_result`	Tool finished
`done`	Final assistant message
`error`	Failure

See Widget SSE events for payload shapes.

{
  "deployment_id": "dep_api_xyz",
  "conversation_id": "conv_8mN4pQ1r",
  "content": "Show me available rooms for July 20",
  "stream": true
}

Response Content-Type: text/event-stream.

Message fields

Field	Type	Description
`content`	string	Plain-text message body
`rich_content`	object	Optional cards/carousels from tool results
`citations`	array	Knowledge base sources cited in the reply
`tool_calls`	array	Tools invoked during this turn

Rate limits

Direct API messages count against the Chat rate limit (60/min per deployment by default).