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