Lifecycle at a glance
Send a message
POST /chats/:id/messages for a complete answer, or /messages/stream for a live SSE stream.Grounded answer assembled
The assistant searches documents, queries connected data, calls tools, and recalls memory.
Create a chat
POST /chats creates a conversation on a knowledge base. You can include an initial message to create the chat and get its first grounded answer in a single call, or create an empty chat and send messages afterward.
Every chat has an access_level that governs who can read it:
private
Visible only to its owner.
org
Readable across the organization.
public
Shareable read-only via link.
Send a message
Send a turn withPOST /chats/:id/messages for a single complete response, or POST /chats/:id/messages/stream for live SSE progress and final content. Both produce the same grounded answer — the difference is delivery. For a hands-on walkthrough, see Chat & streaming.
How the answer is grounded
The assistant assembles each answer from the sources available to the knowledge base — retrieved document passages, read-only queries against connected databases, tools and connected apps, and durable memory when enabled. Retrieval details are covered in Retrieval & grounding; memory in Memory system.Streaming with SSE
The streaming endpoint returnstext/event-stream. Read events as they arrive to show progress, tool activity, sources, and final content. Answer text is delivered through final_response events with an isComplete flag.
Event types
| Event | Purpose |
|---|---|
ping | Keep-alive heartbeat to hold the connection open. |
user_message | Confirms the user turn was accepted and persisted. |
agent_thought | Optional progress from a multi-step run. |
data_preview | A preview of grounded data available to the run. |
todo_update | Updated task state from the agent. |
mcp_tool_call / mcp_tool_result | MCP tool activity. |
final_response | Answer content; isComplete: true marks the canonical complete answer. Partial events may also occur. |
sources | The source passages cited by the answer. |
chart | A chart produced from connected data, when applicable. |
tokens | Token usage for the turn. |
done | The stream has finished; the answer is fully persisted. |
error | An error occurred; the stream ends. |
One active stream per chat
A chat has one active stream at a time. Sending a new streamed message while another stream is in progress replaces the in-progress one — the newer request takes over. Design clients to keep a single open stream per chat and start a new turn only after the previous stream reachesdone.
Disconnects and stopping
If a client disconnects mid-stream, the partial answer is saved to the chat, so the conversation stays consistent and you can read what was produced when you reconnect. To end a response deliberately, callPOST /chats/:id/stop; the partial answer up to that point is preserved.
Because partial answers are persisted, a reconnecting client can fetch the chat to recover the latest state rather than replaying the stream.
Long conversations
As a conversation grows, AutoSage automatically summarizes earlier turns to keep the chat within the model’s context window while preserving the most recent turns verbatim. This happens transparently — you keep sending messages to the same chat and recent context stays intact. See Long conversations for details.Endpoint summary
| Action | Method & path |
|---|---|
| Create a chat | POST /chats |
| Send a message | POST /chats/:id/messages |
| Stream a message | POST /chats/:id/messages/stream |
| Stop a response | POST /chats/:id/stop |
Next steps
Chat overview
How chats work across the dashboard and API.
Chat & streaming guide
Consume the SSE stream step by step.
Chats API
Full request and response schemas.
Retrieval & grounding
See how grounded answers are built.