Chat lifecycle

A chat is a single conversation against a knowledge base. Every message produces a grounded, cited answer that is persisted with its sources, usage, and credit cost. This page covers the full lifecycle — creating a chat, sending messages, streaming responses over Server-Sent Events (SSE), and how long conversations are kept within context.

​

Lifecycle at a glance

​

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: See Sharing chats for how public links work.

​

Send a message

Send a turn with POST /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 returns text/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

​

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 reaches done.

​

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, call POST /chats/:id/stop; the partial answer up to that point is preserved.

​

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

​

Next steps