Chats

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

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.

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

string

required

Tenant whose chats to list.

string

Restrict results to one knowledge base. Required when the API key itself is knowledge-base-restricted.

string

Restrict an API-key request to one external end user’s chats.

boolean

Filter query chats from regular chats.

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.

string

required

Client-generated UUID for the chat.

string

required

Tenant that owns the chat.

string

required

Knowledge base that grounds the conversation.

string

required

Supported model identifier. Use /chats/models to discover choices.

string

Optional title. Long titles are truncated to 255 characters.

string

Optional initial user message.

string

quick or deep. Defaults to deep.

boolean

Enable web search for the initial turn.

string

External end-user identifier for API-key-authenticated ownership, memory, and connected apps.

string[]

Connected apps available to the turn.

string[]

Skills to load for this turn.

string[]

Agents available for delegation on this turn.

string[]

Up to 20 artifacts to add as context.

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"
  }'

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.

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.

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

string

External owner for API-key-authenticated chats.

string

New chat title.

Set access level

PATCH /chats/:id/access

string

Required for an API-key call when the chat has an external owner.

string

required

One of private, org, or public.

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.

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

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

number

Number of messages to return, from 1 to 200.

number

Zero-based pagination offset.

string

External owner for an API-key-authenticated chat.

Returns message records and chat metadata.

Send a message

POST /chats/:id/messages

string

required

User message, up to 32,000 characters.

string

required

Supported model identifier.

string

quick or deep. Defaults to deep.

boolean

Enable web search for this turn.

string

External owner for API-key authentication. It must resolve to the chat owner.

string[]

Skills to load for this turn.

string[]

Additional delegates for this turn.

string[]

Connected apps available in Deep mode.

string[]

Artifacts to attach as context.

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.

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.

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

Use the interactive explorer at /swagger for complete utility schemas and response examples.

Next steps

Chat lifecycle

Understand persistence, compaction, stopping, and recovery.

Chat & streaming

Implement an SSE client.

Shared chats

Read shared transcripts safely.

Chat modes

Choose between Quick and Deep mode.

Get started

Core concepts

Lifecycles

Guides

API reference

Endpoints

List chats

Create a chat

List supported models

Update a title

Set access level

Delete a chat

Get todo state

List messages

Send a message

Stream a message

SSE events

One active stream

Stop a stream

Delete one message

Configure MCP servers

Terminate a session

Prompt and follow-up utilities

Improve a prompt

Generate follow-up questions

Fast query utilities

Quick grounded answer

Raw retrieval chunks

Next steps

Chat lifecycle

Chat & streaming

Shared chats

Chat modes

​Endpoints

​List chats

​Create a chat

​List supported models

​Update a title

​Set access level

​Delete a chat

​Get todo state

​List messages

​Send a message

​Stream a message

​SSE events

​One active stream

​Stop a stream

​Delete one message

​Configure MCP servers

​Terminate a session

​Prompt and follow-up utilities

​Improve a prompt

​Generate follow-up questions

​Fast query utilities

​Quick grounded answer

​Raw retrieval chunks

​Next steps

Chat lifecycle

Chat & streaming

Shared chats

Chat modes

Endpoints

List chats

Create a chat

List supported models

Update a title

Set access level

Delete a chat

Get todo state

List messages

Send a message

Stream a message

SSE events

One active stream

Stop a stream

Delete one message

Configure MCP servers

Terminate a session

Prompt and follow-up utilities

Improve a prompt

Generate follow-up questions

Fast query utilities

Quick grounded answer

Raw retrieval chunks

Next steps