Appearance

Chat ​

List chats visible to the caller​

GET
/v1/chats

List the chats the caller may read, with each chat's agent, round count and
average alignment score. Chats that were deleted, or whose agent was deleted,
are never listed.

Without sort, chats are ordered by last activity (updated_at), newest first.
sort=title orders case-insensitively by display_title;
avg_alignment_score and agent put chats without a value last in both
directions. Every sort breaks ties on the chat id in the same direction.

next_cursor carries the sort it was issued under; a cursor from another sort
starts again from the first page. total counts every chat matching the
filters and is only computed with include_total=true.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Query Parameters

cursor

Opaque cursor for keyset pagination.

limit

Max chats per page.

Type
integer
Default
50
Maximum
100
Minimum
1
sort

Sort key; omit to order by last activity.

order

Sort direction; defaults to desc. Ignored without sort.

include_total

When true, also count every matching chat into total.

Type
boolean
Default
false
agent_id

Only chats bound to this agent.

mine

When true, only chats created by the caller.

Type
boolean
Default
false
echo_state

Only chats whose latest scored round is in this alignment state.

date_from

Start of the window, inclusive. Either an ISO-8601 instant (2026-09-15T00:00:00+08:00) or a bare YYYY-MM-DD, which means that whole calendar day in UTC. Send an instant with an offset to use another timezone. Compared with the chat's start time.

date_to

End of the window, inclusive. A bare YYYY-MM-DD closes at the last instant of that day in UTC; an ISO-8601 instant is used exactly as given. Compared with the chat's start time.

search

Case-insensitive substring of the chat title, the agent name, or any user message or assistant reply in the chat.

Responses​

Successful Response

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"agent_id": "string",
  
  
  
"agent_model": "string",
  
  
  
"agent_name": "string",
  
  
  
"alignment_score": 0,
  
  
  
"avg_alignment_score": 0,
  
  
  
"completion_tokens": 0,
  
  
  
"context_compacted": false,
  
  
  
"context_limit": 0,
  
  
  
"created_at": "string",
  
  
  
"display_title": "string",
  
  
  
"echo_scoring_pending": false,
  
  
  
"echo_state": "string",
  
  
  
"id": "string",
  
  
  
"input_tokens": 0,
  
  
  
"latency_ms": 0,
  
  
  
"rag_enabled": true,
  
  
  
"rag_exclude_document_ids": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"rag_include_document_ids": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"rag_reranking": true,
  
  
  
"rag_reranking_type": "string",
  
  
  
"round": 0,
  
  
  
"started_at": "string",
  
  
  
"title": "string",
  
  
  
"total_rounds": 0,
  
  
  
"updated_at": "string"
  
  
}
  
],
  
"next_cursor": "string",
  
"total": 0
}

Samples​

Create a chat​

POST
/v1/chats

Create an empty chat bound to an agent. Chats default to personal; send visibility and team_ids to scope it otherwise. include_document_ids or exclude_document_ids set the chat's Knowledge Base scope. Upload attachments with POST /chats/{chat_id}/attachments and send turns with POST /chats/{chat_id}/messages.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Request Body​

application/json
Format"uuid"

When set, these document IDs are excluded from RAG retrieval.

Any of
Format"uuid"

When set, RAG retrieval is restricted to only these document IDs.

Any of
Format"uuid"

Team scope of the new chat. Omit to keep the default behavior, or use [] for creator-only personal/org_level.

Any of
Format"uuid"

Visibility of the new chat. Defaults to personal. Reserved visibilities may still be rejected by authorization.

Any of
Valid values"personal""team_level""org_level""community""universal"

Responses​

Successful Response

application/json
JSON
{
  
"agent_id": "string",
  
"chat_id": "string",
  
"echo_scoring_pending": false,
  
"messages": [
  
  
{
  
  
  
"citations": [
  
  
  
  
{
  
  
  
  
  
"attachment_id": "string",
  
  
  
  
  
"chunk_id": "string",
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
"excerpt": "string",
  
  
  
  
  
"filename": "string",
  
  
  
  
  
"images": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
  
  
"image_id": "string",
  
  
  
  
  
  
  
"kind": "string",
  
  
  
  
  
  
  
"label": "string",
  
  
  
  
  
  
  
"marker": 0,
  
  
  
  
  
  
  
"page": 0,
  
  
  
  
  
  
  
"x0": 0,
  
  
  
  
  
  
  
"x1": 0,
  
  
  
  
  
  
  
"y0": 0,
  
  
  
  
  
  
  
"y1": 0
  
  
  
  
  
  
}
  
  
  
  
  
],
  
  
  
  
  
"source_type": "rag",
  
  
  
  
  
"source_url": "string",
  
  
  
  
  
"spans": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"chunk_id": "string",
  
  
  
  
  
  
  
"doc_end": 0,
  
  
  
  
  
  
  
"doc_start": 0,
  
  
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
  
  
"mark_index": 0,
  
  
  
  
  
  
  
"n": 0,
  
  
  
  
  
  
  
"page": 0,
  
  
  
  
  
  
  
"quote": "string"
  
  
  
  
  
  
}
  
  
  
  
  
]
  
  
  
  
}
  
  
  
],
  
  
  
"content": "string",
  
  
  
"pruned": false,
  
  
  
"reasoning": "string",
  
  
  
"role": "string"
  
  
}
  
],
  
"team_ids": [
  
  
"string"
  
],
  
"title": "string",
  
"visibility": "personal"
}

Samples​

Summarize the chats matching a filter​

GET
/v1/chats/summary

Totals over every chat that GET /chats would list for the same filters, not
just one page: chat and round counts, the average alignment score, and rounds
per alignment state. drift_rate is drift rounds over drift, stable and
refusal rounds, and 0 when there are none.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Query Parameters

agent_id

Only chats bound to this agent.

mine

When true, only chats created by the caller.

Type
boolean
Default
false
echo_state

Only chats whose latest scored round is in this alignment state.

date_from

Start of the window, inclusive. Either an ISO-8601 instant (2026-09-15T00:00:00+08:00) or a bare YYYY-MM-DD, which means that whole calendar day in UTC. Send an instant with an offset to use another timezone. Compared with the chat's start time.

date_to

End of the window, inclusive. A bare YYYY-MM-DD closes at the last instant of that day in UTC; an ISO-8601 instant is used exactly as given. Compared with the chat's start time.

search

Case-insensitive substring of the chat title, the agent name, or any user message or assistant reply in the chat.

Responses​

Successful Response

application/json
JSON
{
  
"avg_alignment_score": 0,
  
"drift_rate": 0,
  
"drift_rounds": 0,
  
"mild_drift_rounds": 0,
  
"moderate_drift_rounds": 0,
  
"refusal_rounds": 0,
  
"severe_drift_rounds": 0,
  
"stable_rounds": 0,
  
"total_chats": 0,
  
"total_rounds": 0
}

Samples​

Delete a chat​

DELETE
/v1/chats/{chat_id}

Delete a chat. It stops appearing in every chat read; its history is kept.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Responses​

Successful Response

Samples​

Get a chat and its message history​

GET
/v1/chats/{chat_id}

Get a chat with its full message history.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Responses​

Successful Response

application/json
JSON
{
  
"agent_id": "string",
  
"chat_id": "string",
  
"echo_scoring_pending": false,
  
"messages": [
  
  
{
  
  
  
"citations": [
  
  
  
  
{
  
  
  
  
  
"attachment_id": "string",
  
  
  
  
  
"chunk_id": "string",
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
"excerpt": "string",
  
  
  
  
  
"filename": "string",
  
  
  
  
  
"images": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
  
  
"image_id": "string",
  
  
  
  
  
  
  
"kind": "string",
  
  
  
  
  
  
  
"label": "string",
  
  
  
  
  
  
  
"marker": 0,
  
  
  
  
  
  
  
"page": 0,
  
  
  
  
  
  
  
"x0": 0,
  
  
  
  
  
  
  
"x1": 0,
  
  
  
  
  
  
  
"y0": 0,
  
  
  
  
  
  
  
"y1": 0
  
  
  
  
  
  
}
  
  
  
  
  
],
  
  
  
  
  
"source_type": "rag",
  
  
  
  
  
"source_url": "string",
  
  
  
  
  
"spans": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"chunk_id": "string",
  
  
  
  
  
  
  
"doc_end": 0,
  
  
  
  
  
  
  
"doc_start": 0,
  
  
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
  
  
"mark_index": 0,
  
  
  
  
  
  
  
"n": 0,
  
  
  
  
  
  
  
"page": 0,
  
  
  
  
  
  
  
"quote": "string"
  
  
  
  
  
  
}
  
  
  
  
  
]
  
  
  
  
}
  
  
  
],
  
  
  
"content": "string",
  
  
  
"pruned": false,
  
  
  
"reasoning": "string",
  
  
  
"role": "string"
  
  
}
  
],
  
"team_ids": [
  
  
"string"
  
],
  
"title": "string",
  
"visibility": "personal"
}

Samples​

Update a chat​

PATCH
/v1/chats/{chat_id}

Rename a chat, change its visibility and team scope, and/or change its Knowledge Base scope. Chats are created personal; send visibility to share one afterwards. org_level clears team_ids. Sending include_document_ids or exclude_document_ids replaces the Knowledge Base scope; send null to clear it.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Request Body​

application/json

When set, these document IDs are excluded from RAG retrieval.

Any of
Format"uuid"

When set, RAG retrieval is restricted to only these document IDs.

Any of
Format"uuid"

Team scope; only with visibility. Optional for personal.

Any of
Format"uuid"
Any of
Max Length200
Min Length1

New visibility. org_level clears team_ids.

Any of
Valid values"personal""team_level""org_level""community""universal"

Responses​

Successful Response

application/json
JSON
{
  
"exclude_document_ids": [
  
  
"string"
  
],
  
"include_document_ids": [
  
  
"string"
  
],
  
"team_ids": [
  
  
"string"
  
],
  
"title": "string",
  
"visibility": "string"
}

Samples​

List attachments for a chat​

GET
/v1/chats/{chat_id}/attachments

List the active attachments on a chat.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Responses​

Successful Response

application/json
JSON
[
  
{
  
  
"char_count": 0,
  
  
"chat_id": "string",
  
  
"created_at": "string",
  
  
"created_by": "string",
  
  
"document_id": "string",
  
  
"filename": "string",
  
  
"id": "string",
  
  
"page_count": 0,
  
  
"source_format": "string"
  
}
]

Samples​

Upload file attachments to a chat​

POST
/v1/chats/{chat_id}/attachments

Upload one or more files to a chat as multipart/form-data. Extracted text is
injected into the model's context as numbered sources, which the model cites
with [N] markers.

Accepted types: .txt, .md, .pdf, .doc, .docx, .xlsx, .xls,
.csv. At most 5 files per upload, 10 MB each. Extraction is synchronous and
does not go through document ingestion, so attachments are not searchable
outside the chat they belong to.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Request Body​

multipart/form-data

Responses​

Successful Response

application/json
JSON
[
  
{
  
  
"char_count": 0,
  
  
"chat_id": "string",
  
  
"created_at": "string",
  
  
"created_by": "string",
  
  
"document_id": "string",
  
  
"filename": "string",
  
  
"id": "string",
  
  
"page_count": 0,
  
  
"source_format": "string"
  
}
]

Samples​

Delete a chat attachment​

DELETE
/v1/chats/{chat_id}/attachments/{attachment_id}

Delete an attachment. The attachment stops being sent to the model and stops
appearing in listings; the stored file itself is retained.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

attachment_id*
Type
string
Required
Format
"uuid"
chat_id*
Type
string
Required
Format
"uuid"

Responses​

Successful Response

Samples​

Stream attachment bytes for inline preview or download​

GET
/v1/chats/{chat_id}/attachments/{attachment_id}/file

Stream the original attachment bytes for inline preview or download.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"
attachment_id*
Type
string
Required
Format
"uuid"

Responses​

Successful Response

JSON
[
]

Samples​

List the size of every page of a PDF attachment​

GET
/v1/chats/{chat_id}/attachments/{attachment_id}/pages

Page sizes for laying out the attachment's page images before they load.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"
attachment_id*
Type
string
Required
Format
"uuid"

Responses​

Successful Response

application/json
JSON
{
  
"pages": [
  
  
{
  
  
  
"height": 0,
  
  
  
"width": 0
  
  
}
  
]
}

Samples​

Get a page of a PDF attachment as an image​

GET
/v1/chats/{chat_id}/attachments/{attachment_id}/pages/{page}

A PNG of one page. scale is pixels per PDF unit.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"
attachment_id*
Type
string
Required
Format
"uuid"
page*
Type
integer
Required

Query Parameters

scale

Pixels per PDF unit; large pages are capped.

Type
number
Default
2
Maximum
3
Minimum
1

Responses​

Successful Response

JSON
[
]

Samples​

Get the words on a page of a PDF attachment and where they are​

GET
/v1/chats/{chat_id}/attachments/{attachment_id}/pages/{page}/text

Words with boxes in page units, for selectable text over the page image.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"
attachment_id*
Type
string
Required
Format
"uuid"
page*
Type
integer
Required

Responses​

Successful Response

application/json
JSON
{
  
"height": 0,
  
"width": 0,
  
"words": [
  
  
{
  
  
  
"text": "string",
  
  
  
"x0": 0,
  
  
  
"x1": 0,
  
  
  
"y0": 0,
  
  
  
"y1": 0
  
  
}
  
]
}

Samples​

Export a chat as a downloadable file​

GET
/v1/chats/{chat_id}/export

Download a chat as Markdown or JSON.

Markdown exports carry the chat title, agent name, date, and each turn as
user/assistant sections. JSON exports carry chat_id, agent, title,
created_at, and a turns array.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Query Parameters

format

Export format: 'markdown' or 'json'.

Type
string
Valid values
"markdown""json"
Default
"markdown"

Responses​

Successful Response

application/json
JSON
[
]

Samples​

Send a message and receive an assistant reply​

POST
/v1/chats/{chat_id}/messages

Send one user turn. Set enable_rag to false to skip document retrieval. Runs Echo pre-processing, calls the inference gateway, persists the turn, and enqueues async Echo post-processing.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Request Body​

application/json

When true, retrieve indexed document excerpts scoped to the caller.

Defaulttrue
Min Length1

reasoning_effort for models with a thinking mode; snapped to the nearest effort the model accepts. Omit to send none and keep the model default.

Any of
Valid values"none""minimal""low""medium""high""xhigh"

When set, controls whether reranking runs for this chat's RAG pipeline.

Any of

Reranking strategy for this chat: cross_encoder or llm.

Any of
Valid values"cross_encoder""llm"

Responses​

Successful Response

application/json
JSON
{
  
"chat_id": "string",
  
"citations": [
  
  
{
  
  
  
"attachment_id": "string",
  
  
  
"chunk_id": "string",
  
  
  
"document_id": "string",
  
  
  
"excerpt": "string",
  
  
  
"filename": "string",
  
  
  
"images": [
  
  
  
  
{
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
"image_id": "string",
  
  
  
  
  
"kind": "string",
  
  
  
  
  
"label": "string",
  
  
  
  
  
"marker": 0,
  
  
  
  
  
"page": 0,
  
  
  
  
  
"x0": 0,
  
  
  
  
  
"x1": 0,
  
  
  
  
  
"y0": 0,
  
  
  
  
  
"y1": 0
  
  
  
  
}
  
  
  
],
  
  
  
"source_type": "rag",
  
  
  
"source_url": "string",
  
  
  
"spans": [
  
  
  
  
{
  
  
  
  
  
"chunk_id": "string",
  
  
  
  
  
"doc_end": 0,
  
  
  
  
  
"doc_start": 0,
  
  
  
  
  
"document_id": "string",
  
  
  
  
  
"mark_index": 0,
  
  
  
  
  
"n": 0,
  
  
  
  
  
"page": 0,
  
  
  
  
  
"quote": "string"
  
  
  
  
}
  
  
  
]
  
  
}
  
],
  
"context": {
  
  
"compacted": false,
  
  
"limit": 0,
  
  
"used": 0
  
},
  
"echo": {
  
  
"alignment_score": 0,
  
  
"events": [
  
  
  
"string"
  
  
],
  
  
"round": 0,
  
  
"state": "string"
  
},
  
"model": "string",
  
"postprocess_job_id": "string",
  
"reply": "string",
  
"title": "string",
  
"title_job_id": "string"
}

Samples​

Send a message and stream the assistant reply (SSE)​

POST
/v1/chats/{chat_id}/messages/stream

Same semantics as POST /chats/{chat_id}/messages, but streams assistant text deltas as text/event-stream JSON events before persisting the turn. The first event is meta with chat_id and first_turn. If another reply in this chat starts in the meantime, the stream sends one error event with code reply_in_progress instead.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Request Body​

application/json

When true, retrieve indexed document excerpts scoped to the caller.

Defaulttrue
Min Length1

reasoning_effort for models with a thinking mode; snapped to the nearest effort the model accepts. Omit to send none and keep the model default.

Any of
Valid values"none""minimal""low""medium""high""xhigh"

When set, controls whether reranking runs for this chat's RAG pipeline.

Any of

Reranking strategy for this chat: cross_encoder or llm.

Any of
Valid values"cross_encoder""llm"

Responses​

Successful Response

application/json
JSON
[
]

Samples​

List a chat's rounds​

GET
/v1/chats/{chat_id}/rounds

A page of the chat's rounds, oldest first. A round is one user message and the
reply to it; round is its 0-based position in the chat. While a round is
still being scored, scoring_pending is true and its state, score and latency
are omitted. Pass next_cursor back as cursor for the next page.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Query Parameters

cursor

Opaque cursor for keyset pagination.

limit

Max rounds per page.

Type
integer
Default
200
Maximum
500
Minimum
1

Responses​

Successful Response

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"alignment_score": 0,
  
  
  
"assistant_reply": "string",
  
  
  
"created_at": "string",
  
  
  
"latency_ms": 0,
  
  
  
"round": 0,
  
  
  
"scoring_pending": false,
  
  
  
"state": "string",
  
  
  
"user_content": "string"
  
  
}
  
],
  
"next_cursor": "string"
}

Samples​

Get one round of a chat​

GET
/v1/chats/{chat_id}/rounds/{round_index}

One round with its token counts and the alignment state transitions recorded
for it. round is null when the chat has no round at round_index.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"
round_index*

0-based position of the round.

Type
integer
Required
Minimum
0

Responses​

Successful Response

application/json
JSON
{
  
"chat_id": "string",
  
"round": {
  
  
"alignment_score": 0,
  
  
"assistant_reply": "string",
  
  
"completion_tokens": 0,
  
  
"created_at": "string",
  
  
"events": [
  
  
  
{
  
  
  
  
"from": "string",
  
  
  
  
"reason": "string",
  
  
  
  
"to": "string",
  
  
  
  
"transitionReason": "string",
  
  
  
  
"type": "string"
  
  
  
}
  
  
],
  
  
"input_tokens": 0,
  
  
"latency_ms": 0,
  
  
"round": 0,
  
  
"scoring_pending": false,
  
  
"state": "string",
  
  
"user_content": "string"
  
},
  
"round_index": 0,
  
"scoring_pending": false
}

Samples​

Summarize one chat​

GET
/v1/chats/{chat_id}/summary

The chat's header (display title, agent, model, start time) and totals over all
of its rounds: round count, rounds per alignment state, and the average
alignment score and reply latency over the scored rounds.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

chat_id*
Type
string
Required
Format
"uuid"

Responses​

Successful Response

application/json
JSON
{
  
"avg_alignment_score": 0,
  
"avg_latency_ms": 0,
  
"chat": {
  
  
"agent_model": "string",
  
  
"agent_name": "string",
  
  
"created_at": "string",
  
  
"id": "string",
  
  
"title": "string"
  
},
  
"drift_rounds": 0,
  
"refusal_rounds": 0,
  
"stable_rounds": 0,
  
"total_rounds": 0
}

Samples​