API: AI Chat
Ask questions of your data (streamed or not), conversations and their history, feedback, and the workspace AI settings, quota and usage. All endpoints require authentication unless noted. 27 endpoints.
GET /api/ai/audit
Section titled “GET /api/ai/audit”AI tool-call audit log for the workspace (admin only)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit |
integer | no | |
offset |
integer | no | |
toolName |
string | no |
Responses: 200
GET /api/ai/escalations
Section titled “GET /api/ai/escalations”AI escalation queue for the workspace (admin only)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status |
"awaiting_human" | "claimed" | "resolved" |
no | |
limit |
integer | no | |
offset |
integer | no |
Responses: 200
POST /api/ai/escalations/{id}/claim
Section titled “POST /api/ai/escalations/{id}/claim”Claim an AI escalation ticket (admin only)
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Responses: 200
POST /api/ai/escalations/{id}/resolve
Section titled “POST /api/ai/escalations/{id}/resolve”Resolve an AI escalation ticket (admin only)
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
notes |
string | null | no |
Responses: 200
GET /api/ai/feedback-trends
Section titled “GET /api/ai/feedback-trends”Thumbs, reasons and corrections on the workspace’s AI answers (admin only)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
days |
integer | no |
Responses: 200
GET /api/ai/prompts
Section titled “GET /api/ai/prompts”List AI agent prompt overrides (platform admin only)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
agentName |
string | no |
Responses: 200
GET /api/ai/quota
Section titled “GET /api/ai/quota”AI quota config for the workspace (admin only)
Responses: 200
PUT /api/ai/quota
Section titled “PUT /api/ai/quota”Set an AI quota for the workspace (admin only)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
period |
"day" | "month" |
yes | |
tokensLimit |
integer | null | no | |
requestsLimit |
integer | null | no |
Responses: 200
GET /api/ai/settings
Section titled “GET /api/ai/settings”The workspace’s AI settings (admin only)
Responses: 200
PUT /api/ai/settings
Section titled “PUT /api/ai/settings”Set the workspace’s AI level, longest answer and conversation retention (admin only)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
level |
"fast" | "standard" | "advanced" | "max" | null |
yes | |
maxOutputTokens |
integer | null | yes | |
retentionDays |
integer | null | yes |
Responses: 200
GET /api/ai/tools
Section titled “GET /api/ai/tools”The AI tools of the workspace, with their switch (admin only)
Responses: 200
PUT /api/ai/tools/{name}
Section titled “PUT /api/ai/tools/{name}”Switch an AI tool on or off for the workspace (admin only)
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | yes |
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
enabled |
boolean | yes | |
notes |
string | no |
Responses: 200
GET /api/ai/usage
Section titled “GET /api/ai/usage”AI token-usage summary for the workspace (admin only)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
days |
integer | no |
Responses: 200
POST /api/chat
Section titled “POST /api/chat”Send a chat message (non-streaming)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | yes | |
conversationId |
string | no | |
pageContext |
object | no | |
assistantIntent |
object | no | |
authoringIntent |
object | no | |
approvalReceiptId |
string | no | |
suggestion |
object | no | |
effort |
"auto" | "quick" | "balanced" | "thorough" | "max" |
no | |
suggestionArm |
"set" | "generic" |
no |
Responses: 200 · 400 · 401 · 404 · 422 · 503
POST /api/chat/approvals/{receiptId}/approve
Section titled “POST /api/chat/approvals/{receiptId}/approve”Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
receiptId |
string | yes |
Responses: 200 · 400 · 401 · 404 · 409
POST /api/chat/approvals/{receiptId}/cancel
Section titled “POST /api/chat/approvals/{receiptId}/cancel”Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
receiptId |
string | yes |
Responses: 200 · 400 · 401 · 404 · 409
GET /api/chat/conversations
Section titled “GET /api/chat/conversations”List user conversations (paginated)
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit |
integer | no | |
offset |
integer | no |
Responses: 200 · 400 · 401
GET /api/chat/conversations/{id}
Section titled “GET /api/chat/conversations/{id}”Get conversation with messages
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Responses: 200 · 400 · 401 · 404
PATCH /api/chat/conversations/{id}
Section titled “PATCH /api/chat/conversations/{id}”Rename or pin an owned conversation
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
title |
string | no | |
pinned |
boolean | no |
Responses: 200 · 400 · 401 · 404
DELETE /api/chat/conversations/{id}
Section titled “DELETE /api/chat/conversations/{id}”Delete a conversation
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Responses: 204 — No content · 401 · 404
GET /api/chat/conversations/{id}/export
Section titled “GET /api/chat/conversations/{id}/export”Export a conversation as markdown or JSON
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format |
"md" | "json" |
no |
Responses: 200
POST /api/chat/conversations/{id}/feedback/{messageId}
Section titled “POST /api/chat/conversations/{id}/feedback/{messageId}”Set feedback on a message (thumbs up/down, with a reason and a correction)
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
messageId |
string | yes |
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
feedback |
"thumbs_up" | "thumbs_down" |
yes | |
reason |
"wrong_number" | "wrong_scope" | "wrong_data" | "incomplete" | "not_what_i_asked" | "too_long" | "other" |
no | |
note |
string | no |
Responses: 200 · 400 · 401 · 404
POST /api/chat/conversations/{id}/fork
Section titled “POST /api/chat/conversations/{id}/fork”Fork a conversation from a pivot message
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes |
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
pivotMessageId |
string | yes | |
title |
string | no |
Responses: 200 · 400 · 401 · 404
GET /api/chat/conversations/search
Section titled “GET /api/chat/conversations/search”Full-text search across user’s conversations
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
q |
string | yes | |
limit |
integer | no |
Responses: 200 · 400 · 401 · 404
GET /api/chat/effort-options
Section titled “GET /api/chat/effort-options”Effort choices for a chat message (Auto, Quick, Balanced, Thorough, Max) and which the plan allows
Responses: 200 · 400 · 401 · 404
POST /api/chat/stream
Section titled “POST /api/chat/stream”Send a chat message (SSE streaming)
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | yes | |
conversationId |
string | no | |
turnId |
string | no | |
pageContext |
object | no | |
assistantIntent |
object | no | |
authoringIntent |
object | no | |
approvalReceiptId |
string | no | |
suggestion |
object | no | |
effort |
"auto" | "quick" | "balanced" | "thorough" | "max" |
no | |
suggestionArm |
"set" | "generic" |
no |
Responses: 200 — Server-Sent Events. Each data: line is one AiStreamEvent (@datasquares/contracts AiStreamEventSchema): start, text (delta), tool_start, tool_result, then exactly one terminal done or error, each carrying version, turnId, a monotonic sequence and cursor (\<turnId>:\<sequence>). A terminal frame is followed by event: close; : keepalive comments arrive every 15 s. If the connection ends without a terminal frame, GET /api/chat/turns/{turnId} returns the turn’s durable status and the persisted assistant messageId.
GET /api/chat/turns/{turnId}
Section titled “GET /api/chat/turns/{turnId}”Recover the durable status of an AI turn
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
turnId |
string | yes |
Responses: 200 · 400 · 401 · 404