Skip to main content
Create an empty chat and return its id and agent_id. Every other chat surface — the WebSocket and Upload Files — requires an existing chat_id. Call this endpoint first.
A WebSocket send_message frame or POST /v1/chats/uploads without a chat_id is rejected with MISSING_CHAT_ID; there is no lazy creation.
string
required
Bearer token obtained from the authenticate endpoint.
string
Custom title for the chat. If omitted, null, or empty, the server generates Chat YYYY-MM-DD HH:MM using container-local time (UTC in current deployments). The first WebSocket turn can replace this placeholder automatically; REST turns do not. Socketless clients should set a title here or with Update Chat.
string
ID of the database integration this chat will query. When supplied, it is validated against the caller’s organization and stored on the chat’s metadata so subsequent messages don’t need to resend it.

Response

string
required
The newly created chat’s ID. Pass this as chat_id on subsequent calls.
string
required
Organization the chat belongs to.
string
required
Member the chat belongs to.
string
required
The agent this chat is bound to. The chat WebSocket is per-agent — pass this as {agent_id} in wss://api.trellis.sh/v1/agents/{agent_id}/chats/ws.
string
required
The chat’s title at creation time. If it is the generated placeholder, reload the chat after the first WebSocket turn to receive any automatic title update.
string
required
ISO 8601 timestamp when the chat was created.

Rate limits and caps

The open-chat cap counts every chat that hasn’t been deleted; reach it and you must delete a chat (see Delete Chat or Delete Chats) before creating another.