Chat Conversations — MDDB API
Persistent per-user chat conversations (v2.19.0+, issue 405) — the host API a signed-in application (or mddb-chat on its behalf) uses to create, resume, export and delete a user's conversations
List a user's conversations #
GET /v1/chat/conversations
One page of the conversations of sub, newest first (by last message), without messages. Needs read on the chat collection.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
sub (required) |
query | string |
The user's id — the sub of the host's signed join token. Never taken from the browser. At most 256 characters. |
scenario |
query | string |
Only conversations of this scenario |
limit |
query | integer |
Default 50. Maximum 200. |
cursor |
query | string |
nextCursor of the previous page |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
A page of conversation summaries | object (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode |
401 example (application/json)
{
"error": "missing authentication"
}
Create a conversation for a user #
POST /v1/chat/conversations
Creates an empty conversation of sub in a scenario (v2.19.0+, #405). Needs write on the chat collection of the caller's tenant (chat_conversations, or <tenant>/chat_conversations).
Authorization: BearerAuth or APIKeyAuth or none
Request body #
Required.
Content type application/json: ChatCreateRequest
{
"displayName": "string",
"retentionDays": 0,
"scenario": "string",
"sub": "string"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The new conversation, with an empty message list | ChatConversation (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode |
401 example (application/json)
{
"error": "missing authentication"
}
Delete everything of a user (GDPR erasure) #
DELETE /v1/chat/conversations
Deletes every conversation of sub. Needs write on the chat collection.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
sub (required) |
query | string |
The user's id — the sub of the host's signed join token. Never taken from the browser. At most 256 characters. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
How many conversations were deleted | object (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode |
401 example (application/json)
{
"error": "missing authentication"
}
Export everything of a user (GDPR export) #
GET /v1/chat/conversations/export
Every conversation of sub with all its messages, newest conversation first. Needs read on the chat collection.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
sub (required) |
query | string |
The user's id — the sub of the host's signed join token. Never taken from the browser. At most 256 characters. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The user's conversations | object (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode |
401 example (application/json)
{
"error": "missing authentication"
}
Read a conversation with its messages #
GET /v1/chat/conversations/{id}
The conversation of sub with its messages, oldest first. limit keeps only the last N (the chat's max_history_length); messageCount is always the whole conversation's.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string |
The conversation id |
sub (required) |
query | string |
The user's id — the sub of the host's signed join token. Never taken from the browser. At most 256 characters. |
limit |
query | integer |
Only the last N messages (default all) |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The conversation | ChatConversation (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode | |
404 |
No such conversation for this sub — also the answer for another user's conversation, so its existence does not leak |
ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
Delete a conversation #
DELETE /v1/chat/conversations/{id}
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string |
The conversation id |
sub (required) |
query | string |
The user's id — the sub of the host's signed join token. Never taken from the browser. At most 256 characters. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Deleted | object (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode | |
404 |
No such conversation for this sub — also the answer for another user's conversation, so its existence does not leak |
ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
Append messages to a conversation #
POST /v1/chat/conversations/{id}/messages
Appends 1 to 100 messages and refreshes the conversation's retention. The server sets each message's id; createdAt defaults to now. The first user message becomes the title.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string |
The conversation id |
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
sub (required) |
string |
|
messages (required) |
array of ChatMessage |
|
redact |
boolean |
Redact these messages and every later write of the conversation (issue 406) |
{
"messages": [
{
"content": "string",
"createdAt": 0,
"id": "string",
"latencyMs": 0,
"loopStopped": false,
"model": "string",
"outcome": "answered",
"provider": "string",
"role": "user",
"tokens": {
"completion": 0,
"prompt": 0
},
"toolCalls": [
{}
]
}
],
"redact": false,
"sub": "string"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The conversation, holding only the messages just added (with their ids) | ChatConversation (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode | |
404 |
No such conversation for this sub — also the answer for another user's conversation, so its existence does not leak |
ErrorResponse (application/json) |
409 |
The conversation has ended | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
End a conversation #
POST /v1/chat/conversations/{id}/end
Marks the conversation ended; it stays readable until its retention runs out and refuses further messages. Ending twice changes nothing.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string |
The conversation id |
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
sub (required) |
string |
{
"sub": "string"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The ended conversation, without messages | ChatConversation (application/json) |
400 |
Missing sub, or a request the store refuses |
ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No permission on the chat collection of the caller's tenant, or read-only mode | |
404 |
No such conversation for this sub — also the answer for another user's conversation, so its existence does not leak |
ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
Rate an answer #
POST /v1/chat/conversations/{id}/feedback
Stores a rating (up or down) and an optional comment with one assistant message (v2.19.0+, issue 406). Rating again replaces the earlier rating; an ended conversation can still be rated. A comment of a conversation with redact on is redacted.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
id (required) |
path | string |
The conversation id |
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
sub (required) |
string |
|
messageId (required) |
string |
The answer's id — the done frame's message_id |
rating (required) |
string |
One of "up", "down". |
comment |
string |
Trimmed; line breaks allowed At most 2000 characters. |
{
"comment": "string",
"messageId": "string",
"rating": "up",
"sub": "string"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The stored rating | object (application/json) |
400 |
Missing messageId, a rating other than up/down, or a comment that is too long or holds control characters | ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
No write permission on the chat collection of the caller's tenant, or read-only mode | |
404 |
No such conversation for this sub, or no assistant message with that id |
ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
The conversation log #
GET /v1/chat/log
Logged chat turns across users, newest first (v2.19.0+, issue 406): assistant messages with an outcome, from scenarios with logging on, in the caller's chat collection. Global admin only. Anonymous turns carry anonymous: true and no identity.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
scenario |
query | string |
|
from |
query | string |
Earliest turn, inclusive — unix seconds, RFC 3339 or YYYY-MM-DD |
to |
query | string |
Latest turn, inclusive — unix seconds, RFC 3339 or YYYY-MM-DD (a date is its whole day, UTC) |
rating |
query | string |
up, down, none (unrated) or any (rated) One of "up", "down", "none", "any". |
outcome |
query | string |
One of "answered", "noResults", "refused", "error". |
cursor |
query | string |
|
limit |
query | integer |
Default 50. Maximum 200. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
One page of turns | ChatLogPage (application/json) |
400 |
An unreadable time, rating, outcome, format, cursor or a negative number | ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
Not a global administrator |
401 example (application/json)
{
"error": "missing authentication"
}
Export the conversation log #
GET /v1/chat/log/export
Every turn the filters select (at most 100000), streamed row by row as a download (v2.19.0+, issue 406). CSV is RFC 4180; a cell starting with = + - @ or a tab gets a leading apostrophe (CSV injection). Global admin only.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
format |
query | string |
One of "csv", "json". Default "json". |
scenario |
query | string |
|
from |
query | string |
Earliest turn, inclusive — unix seconds, RFC 3339 or YYYY-MM-DD |
to |
query | string |
Latest turn, inclusive — unix seconds, RFC 3339 or YYYY-MM-DD (a date is its whole day, UTC) |
rating |
query | string |
up, down, none (unrated) or any (rated) One of "up", "down", "none", "any". |
outcome |
query | string |
One of "answered", "noResults", "refused", "error". |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The turns, as an attachment | array of ChatLogTurn (application/json) |
400 |
An unreadable time, rating, outcome, format, cursor or a negative number | ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
Not a global administrator |
401 example (application/json)
{
"error": "missing authentication"
}
Docs gaps #
GET /v1/chat/gaps
Questions whose searches found nothing or scored below a threshold, grouped by normalised text (lowercase, punctuation stripped, whitespace collapsed), most frequent first (v2.19.0+, issue 406). Global admin only.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
scenario |
query | string |
|
from |
query | string |
Earliest turn, inclusive — unix seconds, RFC 3339 or YYYY-MM-DD |
to |
query | string |
Latest turn, inclusive — unix seconds, RFC 3339 or YYYY-MM-DD (a date is its whole day, UTC) |
minCount |
query | integer |
Default 1. Minimum 0. |
threshold |
query | number |
A best score below this is a gap; default MDDB_CHAT_GAP_SCORE or 0.3 Minimum 0. |
limit |
query | integer |
Default 100. Maximum 1000. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The gaps | ChatGapsResponse (application/json) |
400 |
An unreadable time, rating, outcome, format, cursor or a negative number | ErrorResponse (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
403 |
Not a global administrator |
401 example (application/json)
{
"error": "missing authentication"
}