> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat lifecycle

> How a chat is created, how messages are grounded and streamed, and how conversations stay within context.

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

<Steps>
  <Step title="Create a chat">
    `POST /chats`, optionally with an initial message.
  </Step>

  <Step title="Send a message">
    `POST /chats/:id/messages` for a complete answer, or `/messages/stream` for a live SSE stream.
  </Step>

  <Step title="Grounded answer assembled">
    The assistant searches documents, queries connected data, calls tools, and recalls memory.
  </Step>

  <Step title="Persisted">
    The answer is stored with its **sources**, **usage**, and **credits**.
  </Step>
</Steps>

## 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:

<CardGroup cols={3}>
  <Card title="private" icon="lock">
    Visible only to its owner.
  </Card>

  <Card title="org" icon="building">
    Readable across the organization.
  </Card>

  <Card title="public" icon="globe">
    Shareable read-only via link.
  </Card>
</CardGroup>

See [Sharing chats](/chat/sharing) 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](/developers/guides/chat-and-stream).

### 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](/developers/lifecycles/rag); memory in [Memory system](/developers/lifecycles/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

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

<Tip>
  Treat a `final_response` with `isComplete: true` as canonical complete content. Accumulate partial `content` when received, finalize your UI on `done`, and always handle `error`. Use `ping` events as a liveness check rather than displaying them.
</Tip>

### 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.

<Note>
  Because partial answers are persisted, a reconnecting client can fetch the chat to recover the latest state rather than replaying the stream.
</Note>

## 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](/chat/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

<CardGroup cols={2}>
  <Card title="Chat overview" icon="comment" href="/chat/overview">
    How chats work across the dashboard and API.
  </Card>

  <Card title="Chat & streaming guide" icon="bolt" href="/developers/guides/chat-and-stream">
    Consume the SSE stream step by step.
  </Card>

  <Card title="Chats API" icon="code" href="/developers/api/chats">
    Full request and response schemas.
  </Card>

  <Card title="Retrieval & grounding" icon="magnifying-glass" href="/developers/lifecycles/rag">
    See how grounded answers are built.
  </Card>
</CardGroup>