Skip to main content
Send a natural language message and receive a streamed response via Server-Sent Events (SSE).
For a complete guide on handling responses, see the Chat Overview.Prefer real-time bidirectional communication? Use the WebSocket endpoint instead.
​
Authorization
string
required
Bearer token obtained from the authenticate endpoint.
​
Accept
string
Set to text/event-stream to receive SSE responses.
​
message
string
required
The natural language message to send.
​
chat_id
string
ID of an existing chat to continue the conversation. Omit to create a new chat.
​
integration_id
string
ID of the database integration to query. Required for database queries.
​
title
string
Custom title for new chats. If omitted, a title is generated automatically.
​
model
string
AI model to use for this message. If omitted, the default model is used. See List Models for available values.

​
Response

The response is a stream of Server-Sent Events. See Chat Overview for details on handling the stream.

​
Event types

EventDataDescription
chat_metadata{"id": "chat_...", "user_message_id": "msg_..."}Chat ID and persisted user message ID. Emitted at the start of every response.
processing{"status": "thinking"}AI is processing the request
visualizationFull chart or table payloadA chart or table was generated. See Visualizations.
message{"content": "...", "id": "msg_..."}The final response
error{"error": "..."}An error occurred
curl -X POST https://api.trellis.sh/v1/chats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Show me the top 5 projects by budget as a bar chart",
    "integration_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

event: chat_metadata
data: {"id": "chat_abc123", "user_message_id": "msg_001"}

event: processing
data: {"status": "thinking"}

event: processing
data: {"status": "analyzing"}

event: message
data: {"content": "There were 1,523 orders placed last month (December 2024).", "id": "msg_xyz789"}