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

# Chats

> Create grounded conversations, send messages, stream responses, and manage chat access.

Chats are tenant- and knowledge-base-scoped conversations. The same endpoints support complete JSON responses and live Server-Sent Events (SSE).

<Note>
  Endpoints on this page are **\[User+Key]**. API-key chat operations require `query:rag`. Use `external_subject_id` to isolate API-served end users; signed-in user requests do not accept that field.
</Note>

## Endpoints

| Method   | Path                             | Description                                   | Auth        |
| -------- | -------------------------------- | --------------------------------------------- | ----------- |
| `GET`    | `/chats`                         | List chats                                    | \[User+Key] |
| `POST`   | `/chats`                         | Create a chat, optionally with its first turn | \[User+Key] |
| `GET`    | `/chats/models`                  | List supported models                         | \[User+Key] |
| `PATCH`  | `/chats/:id`                     | Update the title                              | \[User+Key] |
| `PATCH`  | `/chats/:id/access`              | Set `private`, `org`, or `public` access      | \[User+Key] |
| `DELETE` | `/chats/:id`                     | Delete a chat                                 | \[User+Key] |
| `GET`    | `/chats/:id/todo`                | Get persistent todo state                     | \[User+Key] |
| `GET`    | `/chats/:id/messages`            | List messages                                 | \[User+Key] |
| `POST`   | `/chats/:id/messages`            | Send a message and wait for the response      | \[User+Key] |
| `POST`   | `/chats/:id/messages/stream`     | Send a message over SSE                       | \[User+Key] |
| `POST`   | `/chats/:id/stop`                | Stop the active stream                        | \[User+Key] |
| `DELETE` | `/chats/:id/messages/:messageId` | Delete one message                            | \[User+Key] |
| `GET`    | `/chats/:id/mcp-servers`         | List available and enabled MCP servers        | \[User+Key] |
| `PATCH`  | `/chats/:id/mcp-servers`         | Set enabled MCP servers                       | \[User+Key] |
| `POST`   | `/chats/:id/terminate`           | Terminate an agent session                    | \[User+Key] |
| `POST`   | `/chats/improve-prompt`          | Improve a prompt                              | \[User+Key] |
| `POST`   | `/chats/follow-up-questions`     | Generate follow-up questions                  | \[User+Key] |
| `POST`   | `/chats/fast-query`              | Run a quick grounded query                    | \[User+Key] |
| `POST`   | `/chats/fast-raw-query`          | Return raw retrieval chunks                   | \[User+Key] |
| `POST`   | `/chats/raw-query`               | Compatibility alias for `fast-raw-query`      | \[User+Key] |

## List chats

`GET /chats`

<ParamField query="tenant_id" type="string" required>
  Tenant whose chats to list.
</ParamField>

<ParamField query="knowledge_base_id" type="string">
  Restrict results to one knowledge base. Required when the API key itself is knowledge-base-restricted.
</ParamField>

<ParamField query="external_subject_id" type="string">
  Restrict an API-key request to one external end user's chats.
</ParamField>

<ParamField query="is_query" type="boolean">
  Filter query chats from regular chats.
</ParamField>

```bash theme={null}
curl "$AUTOSAGE_URL/chats?tenant_id=TENANT_ID&external_subject_id=CUSTOMER_123" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

## Create a chat

`POST /chats`

Creates an empty chat or, when `message` is present, creates the chat and processes its first turn.

<ParamField body="id" type="string" required>
  Client-generated UUID for the chat.
</ParamField>

<ParamField body="tenant_id" type="string" required>
  Tenant that owns the chat.
</ParamField>

<ParamField body="knowledge_base_id" type="string" required>
  Knowledge base that grounds the conversation.
</ParamField>

<ParamField body="model" type="string" required>
  Supported model identifier. Use `/chats/models` to discover choices.
</ParamField>

<ParamField body="title" type="string">
  Optional title. Long titles are truncated to 255 characters.
</ParamField>

<ParamField body="message" type="string">
  Optional initial user message.
</ParamField>

<ParamField body="agent_mode" type="string">
  `quick` or `deep`. Defaults to `deep`.
</ParamField>

<ParamField body="websearch_enable" type="boolean">
  Enable web search for the initial turn.
</ParamField>

<ParamField body="external_subject_id" type="string">
  External end-user identifier for API-key-authenticated ownership, memory, and connected apps.
</ParamField>

<ParamField body="connector_slugs" type="string[]">
  Connected apps available to the turn.
</ParamField>

<ParamField body="skill_ids" type="string[]">
  Skills to load for this turn.
</ParamField>

<ParamField body="delegate_agent_ids" type="string[]">
  Agents available for delegation on this turn.
</ParamField>

<ParamField body="attached_artifact_ids" type="string[]">
  Up to 20 artifacts to add as context.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/chats" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CHAT_UUID",
    "tenant_id": "TENANT_ID",
    "knowledge_base_id": "KB_ID",
    "model": "MODEL_ID",
    "message": "What is our refund window?",
    "agent_mode": "quick",
    "external_subject_id": "CUSTOMER_123"
  }'
```

<Tip>
  Keep the same `external_subject_id` on every operation for an API-served end user. AutoSage uses it as part of chat ownership and durable-memory isolation.
</Tip>

<Note>
  For an externally owned chat, API-key calls to owner-checked routes must pass `external_subject_id` in the query string unless the endpoint schema places it in the request body. This includes title or access changes, deletion, todo reads, message listing, stop, message deletion, MCP configuration, and session termination.
</Note>

The schema also supports up to two base64 image data URLs and an optional shared-chat seed. Use `/swagger` for their exact shapes.

## List supported models

`GET /chats/models`

Returns supported model IDs and display metadata.

## Update a title

`PATCH /chats/:id`

<ParamField query="external_subject_id" type="string">
  External owner for API-key-authenticated chats.
</ParamField>

<ParamField body="title" type="string">
  New chat title.
</ParamField>

## Set access level

`PATCH /chats/:id/access`

<ParamField query="external_subject_id" type="string">
  Required for an API-key call when the chat has an external owner.
</ParamField>

<ParamField body="access_level" type="string" required>
  One of `private`, `org`, or `public`.
</ParamField>

Returns the updated access level and a share URL when the chat can be shared.

| Level     | Read access                            |
| --------- | -------------------------------------- |
| `private` | The owner only.                        |
| `org`     | Signed-in members of the organization. |
| `public`  | Anyone with the link.                  |

<Warning>
  Anyone with a public link can read the shared transcript. Share only content you are comfortable making public.
</Warning>

## Delete a chat

`DELETE /chats/:id`

Deletes the chat and its conversation data. API-key calls for external subjects should include `external_subject_id` in the query string.

## Get todo state

`GET /chats/:id/todo`

Pass `external_subject_id` in the query for an API-key call to an externally owned chat.

Returns the current persistent todo list for the chat, or `null` when no todo state exists.

## List messages

`GET /chats/:id/messages`

<ParamField query="limit" type="number">
  Number of messages to return, from 1 to 200.
</ParamField>

<ParamField query="offset" type="number">
  Zero-based pagination offset.
</ParamField>

<ParamField query="external_subject_id" type="string">
  External owner for an API-key-authenticated chat.
</ParamField>

Returns message records and chat metadata.

## Send a message

`POST /chats/:id/messages`

<ParamField body="content" type="string" required>
  User message, up to 32,000 characters.
</ParamField>

<ParamField body="model" type="string" required>
  Supported model identifier.
</ParamField>

<ParamField body="agent_mode" type="string">
  `quick` or `deep`. Defaults to `deep`.
</ParamField>

<ParamField body="websearch_enable" type="boolean">
  Enable web search for this turn.
</ParamField>

<ParamField body="external_subject_id" type="string">
  External owner for API-key authentication. It must resolve to the chat owner.
</ParamField>

<ParamField body="skill_ids" type="string[]">
  Skills to load for this turn.
</ParamField>

<ParamField body="delegate_agent_ids" type="string[]">
  Additional delegates for this turn.
</ParamField>

<ParamField body="connector_slugs" type="string[]">
  Connected apps available in Deep mode.
</ParamField>

<ParamField body="attached_artifact_ids" type="string[]">
  Artifacts to attach as context.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/chats/CHAT_ID/messages" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I start a return?",
    "model": "MODEL_ID",
    "agent_mode": "deep",
    "external_subject_id": "CUSTOMER_123"
  }'
```

The response contains `user_message`, `assistant_message`, and `usage` with token and credit information.

## Stream a message

`POST /chats/:id/messages/stream`

Accepts the same body as the non-streaming endpoint and returns `text/event-stream`.

```bash theme={null}
curl -N -X POST "$AUTOSAGE_URL/chats/CHAT_ID/messages/stream" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Compare the return rules by product category.",
    "model": "MODEL_ID",
    "agent_mode": "deep"
  }'
```

### SSE events

SSE data contains JSON. Heartbeats can also use the SSE event name `ping`.

| `type`            | Purpose                                            |
| ----------------- | -------------------------------------------------- |
| `ping`            | Transport keep-alive.                              |
| `user_message`    | Confirms that the user message was persisted.      |
| `agent_thought`   | User-facing progress from the agent.               |
| `data_preview`    | A preview of document or data content.             |
| `todo_update`     | Updated persistent todo tasks.                     |
| `mcp_tool_call`   | An MCP tool invocation started.                    |
| `mcp_tool_result` | An MCP tool invocation finished.                   |
| `final_response`  | Answer content and `isComplete`.                   |
| `chart`           | Structured chart configuration.                    |
| `sources`         | Knowledge-base citations.                          |
| `tokens`          | Token usage.                                       |
| `done`            | Terminal summary; the response has been persisted. |
| `error`           | An error message and recovery metadata.            |

Treat a `final_response` with `isComplete: true` as canonical complete answer content. If your client receives partial events, accumulate their `content` until completion. Finalize the UI on `done` and always handle `error`.

### One active stream

Each chat supports one active stream. Starting another stream on the same chat replaces the current one. A client disconnect or explicit stop preserves partial output that has already been generated.

## Stop a stream

`POST /chats/:id/stop`

Pass `external_subject_id` in the query for an API-key call to an externally owned chat.

Returns `{ "stopped": true }` when an active stream was aborted, or `false` when no stream was active.

## Delete one message

`DELETE /chats/:id/messages/:messageId`

Pass `external_subject_id` in the query for an API-key call to an externally owned chat.

Deletes a message only when it belongs to the chat in the path.

## Configure MCP servers

`GET /chats/:id/mcp-servers` lists organization servers and annotates which are enabled for the chat.

`PATCH /chats/:id/mcp-servers` replaces the enabled list:

For either route, pass `external_subject_id` in the query for an API-key call to an externally owned chat.

```json theme={null}
{ "enabled_mcp_server_ids": ["MCP_SERVER_UUID"] }
```

AutoSage validates that every ID belongs to the chat's organization. Up to 25 servers can be enabled.

## Terminate a session

`POST /chats/:id/terminate`

Ends an agent session while preserving its messages for audit. Later standalone agent-runtime calls using that chat return a conflict. The optional body accepts `termination_reason` up to 500 characters.

## Prompt and follow-up utilities

### Improve a prompt

`POST /chats/improve-prompt` accepts `knowledge_base_id`, `query`, and an optional supported `category`. It returns an improved prompt, analysis, and techniques applied. This operation uses credits.

### Generate follow-up questions

`POST /chats/follow-up-questions` accepts `knowledge_base_id` and `chat_id` and returns suggestions based on the conversation. The chat must belong to that knowledge base.

## Fast query utilities

### Quick grounded answer

`POST /chats/fast-query` performs one knowledge-base retrieval pass and produces an answer. Its main fields are `knowledge_base_id`, `content`, `model`, optional `chat_id`, `chunk_count` (1–50), `external_subject_id`, `websearch_enable`, and `connector_slugs`.

### Raw retrieval chunks

`POST /chats/fast-raw-query` returns grouped retrieval chunks without answer generation. `POST /chats/raw-query` is a compatibility alias. Prefer `fast-raw-query` for new integrations.

<Tip>
  Use the interactive explorer at `/swagger` for complete utility schemas and response examples.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Chat lifecycle" icon="comments" href="/developers/lifecycles/chat-lifecycle">
    Understand persistence, compaction, stopping, and recovery.
  </Card>

  <Card title="Chat & streaming" icon="bolt" href="/developers/guides/chat-and-stream">
    Implement an SSE client.
  </Card>

  <Card title="Shared chats" icon="share-nodes" href="/developers/api/shared-chats">
    Read shared transcripts safely.
  </Card>

  <Card title="Chat modes" icon="gauge-high" href="/chat/modes">
    Choose between Quick and Deep mode.
  </Card>
</CardGroup>