Chat — MDDB API
Chat scenarios — an assistant's prompt, guardrails, allowed collections, style, LLM parameters and limits, stored in MDDB (v2.19.0+)
List chat scenarios #
GET /v1/chat/scenarios
The chat scenarios the caller may read (#403, v2.19.0), by name, with
the store's version. A scenario is readable when the caller has
read permission on every collection it allows, so a tenant never
sees a scenario over another tenant's collections.
Authorization: BearerAuth or APIKeyAuth or none
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The scenarios and the version counter | object (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) |
429 |
The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body. Since v2.19.8 (GO-054) a request over its tenant's or its credential's rate or concurrency limit is refused with a TenantLimit body. | anyOf RateLimitError | TenantLimit (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
The chat scenario version counter #
GET /v1/chat/scenarios/version
One number that grows on every scenario create, update and delete, and survives restarts. A consumer such as mddb-chat polls it and reloads the scenarios when it changes.
Authorization: BearerAuth or APIKeyAuth or none
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The version counter | object (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) |
429 |
The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body. Since v2.19.8 (GO-054) a request over its tenant's or its credential's rate or concurrency limit is refused with a TenantLimit body. | anyOf RateLimitError | TenantLimit (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
Get a chat scenario #
GET /v1/chat/scenarios/{name}
Needs read permission on every collection the scenario allows.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The scenario's name. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The scenario | ChatScenario (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No chat scenario of that name | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
404 example (application/json)
{
"error": "chat scenario not found"
}
Create or replace a chat scenario #
PUT /v1/chat/scenarios/{name}
The body is the whole scenario; the path names it (a name in the
body is ignored). Empty choices take their defaults: offTopic.mode
refuse, style.emoji off, style.verbosity normal. Every name in
allowedCollections must be an existing collection or alias.
Requires a global administrator. Bumps the version counter.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The scenario's name. |
Request body #
Required.
Content type application/json: ChatScenario
{
"allowedCollections": [
"string"
],
"description": "string",
"enabled": false,
"guardrails": "string",
"llm": {
"loopGuard": {
"enabled": false,
"minOutput": 0,
"ngram": 0,
"ratio": 0,
"unit": "chars",
"window": 0
},
"maxTokens": 0,
"model": "string",
"temperature": 0
},
"logging": {
"enabled": false,
"redact": true,
"retentionDays": 0
},
"maxTurns": 0,
"mcpServers": [
{
"allowedTools": [
"string"
],
"enabled": false,
"forwardIdentity": {},
"name": "string",
"resultMaxChars": 4000,
"secretRef": "string",
"timeoutMs": 8000,
"url": "https://example.com/"
}
],
"name": "string",
"offTopic": {
"mode": "refuse",
"redirectTemplate": "string"
},
"operatorPrompt": "string",
"rateLimit": {
"messagesPerMinute": 0
},
"skills": [
"string"
],
"style": {
"citationTemplate": "https://example.org/blob/main/",
"emoji": "off",
"markdown": false,
"verbosity": "normal"
},
"tokenBudgetPerSession": 0
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Replaced | ChatScenario (application/json) |
201 |
Created | ChatScenario (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Delete a chat scenario #
DELETE /v1/chat/scenarios/{name}
Requires a global administrator. Bumps the version counter.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The scenario's name. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Deleted | object (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No chat scenario of that name | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
404 example (application/json)
{
"error": "chat scenario not found"
}
The composed system prompt of a chat scenario #
GET /v1/chat/scenarios/{name}/prompt
The prompt in the order it is sent: operator prompt, guardrails, the
off-topic clause, the scenario's skills in its order (#404, under a
line saying the guardrails take precedence), the style clause, then
the responsePrompt of each allowed collection that has one, with
its size. Same permission as reading the scenario.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The scenario's name. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The composed prompt | object (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No chat scenario of that name | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
404 example (application/json)
{
"error": "chat scenario not found"
}
List chat skills #
GET /v1/chat/skills
Every chat skill (#404, v2.19.0) without content or history, with the chat scenarios' version counter, which a skill change bumps too. Requires a global administrator: a skill's text is part of system prompts.
Authorization: BearerAuth or APIKeyAuth or none
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The skills and the version counter | object (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Preview a SKILL.md from a URL or pasted text #
POST /v1/chat/skills/import
Parses a SKILL.md and returns it whole without storing anything. A
url must be https; it is fetched through the SSRF guard, capped at
MDDB_CHAT_SKILL_MAX_BYTES plus 8 KiB. A GitHub blob or raw URL is
resolved to a commit and read at it. Requires a global administrator.
Authorization: BearerAuth or APIKeyAuth or none
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
url |
string (uri) |
|
content |
string |
{
"content": "string",
"url": "https://example.com/"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The preview | ChatSkillPreview (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Get a chat skill #
GET /v1/chat/skills/{name}
The current version with its content and the list of kept earlier
versions (without contents), or with version one of those.
Requires a global administrator.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The skill's name. |
version |
query | integer |
Minimum 1. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The skill | ChatSkill (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No chat skill of that name, or a version not kept | ErrorResponse (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
404 example (application/json)
{
"error": "chat skill not found"
}
Create a chat skill or store a new version #
PUT /v1/chat/skills/{name}
content is the instructions, or a whole SKILL.md whose front matter
gives the description when none is sent. A change stores a new
version and keeps the previous one (the last 10); a put that changes
nothing stores nothing. Requires a global administrator. Bumps the
chat scenarios' version counter.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The skill's name. |
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
description |
string |
|
content (required) |
string |
|
source |
ChatSkillSource |
{
"content": "string",
"description": "string",
"source": {
"commit": "string",
"fetchedAt": "2026-01-31T12:00:00Z",
"url": "https://example.com/"
}
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
A new version, or unchanged | ChatSkill (application/json) |
201 |
Created | ChatSkill (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Delete a chat skill #
DELETE /v1/chat/skills/{name}
Refused while a scenario attaches it. Requires a global administrator. Bumps the version counter.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The skill's name. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Deleted | object (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No chat skill of that name, or a version not kept | ErrorResponse (application/json) |
409 |
Scenarios attach the skill | object (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
404 example (application/json)
{
"error": "chat skill not found"
}
The scenarios attaching a chat skill #
GET /v1/chat/skills/{name}/used-by
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The skill's name. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The scenario names | object (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No chat skill of that name, or a version not kept | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
404 example (application/json)
{
"error": "chat skill not found"
}
Fetch a chat skill's source again #
POST /v1/chat/skills/{name}/update
Without confirm a preview of what the source holds now next to the
stored skill. With confirm: true a changed text is stored as a new
version; with sha256 (of the preview's content) a source that
changed since the preview is refused. Requires a global administrator.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The skill's name. |
Request body #
Content type application/json: object
| Property | Type | Description |
|---|---|---|
confirm |
boolean |
|
sha256 |
string |
{
"confirm": false,
"sha256": "string"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The stored skill and the preview | object (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No chat skill of that name, or a version not kept | ErrorResponse (application/json) |
409 |
The source changed since the preview | ErrorResponse (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
404 example (application/json)
{
"error": "chat skill not found"
}
List chat MCP secrets #
GET /v1/chat/mcp-secrets
The credentials of the external MCP servers chat scenarios use (MCP-005, v2.19.0): names, headers and set, never a value, and whether a secret can be set at all. Requires a global administrator.
Authorization: BearerAuth or APIKeyAuth or none
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The secrets | object (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Set or replace a chat MCP secret #
PUT /v1/chat/mcp-secrets/{name}
A bearer token, or the value of the header named in header. Stored
only sealed with the at-rest key: without MDDB_ENCRYPTION_KEY the put
is refused with 409 and nothing is stored. Never returned. Requires a
global administrator.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The secret's name. |
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
value (required) |
string |
At most 8192 characters. Write-only. |
header |
string |
Pattern ^[A-Za-z0-9-]{1,64}$. |
{
"header": "string",
"value": "string"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Replaced | ChatMcpSecretSaved (application/json) |
201 |
Created | ChatMcpSecretSaved (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
409 |
No at-rest key is configured, and a secret is never stored in plain text. Set MDDB_ENCRYPTION_KEY and restart mddbd. | ChatMcpSecretNeedsKey (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Delete a chat MCP secret #
DELETE /v1/chat/mcp-secrets/{name}
Refused while a scenario's server names it. Requires a global administrator.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
name (required) |
path | string |
The secret's name. |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Deleted | object (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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
No secret of that name | ErrorResponse (application/json) |
409 |
Scenarios use the secret | object (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
List an external MCP server's tools #
POST /v1/chat/mcp/inspect
Connects over MCP Streamable HTTP (https only, through the SSRF guard, redirects held to https, 8 s), runs initialize and tools/list, and returns the tools with their annotations and whether a scenario may allow each. Requires a global administrator and the chatExternalMcp feature.
Authorization: BearerAuth or APIKeyAuth or none
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
url (required) |
string (uri) |
|
secretRef |
string |
{
"secretRef": "string",
"url": "https://example.com/"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The server and its tools | object (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode). | ErrorResponse (application/json) |
404 |
The chatExternalMcp feature is off, or no secret of that name | object (application/json) |
409 |
The secret named in secretRef is stored unsealed and is not used; set it again. | ChatMcpSecretNeedsKey (application/json) |
502 |
The server cannot be reached or answered with an error | ErrorResponse (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Call an allowed external MCP tool of a scenario #
POST /v1/chat/mcp/call
For mddb-chat: mddbd checks every switch (the chat and chatExternalMcp features, the scenario, the server, the tool in allowedTools and still read-only on the server), attaches the credential and calls the tool. A timeout or an upstream failure is 200 with isError and a short content. Needs read permission on every collection the scenario allows.
(v2.19.2, #414) A server with forwardIdentity also needs sub —
the verified join token's user — and write permission on the chat
collection; without sub the call is 403 and nothing is sent. Every
request to the server then carries a fresh MCP identity token
(docs/API.md, "The MCP identity token"). Other servers ignore sub.
Authorization: BearerAuth or APIKeyAuth or none
Request body #
Required.
Content type application/json: object
| Property | Type | Description |
|---|---|---|
scenario (required) |
string |
|
server (required) |
string |
|
tool (required) |
string |
|
arguments |
object |
|
sub |
string |
(v2.19.2, At most 256 characters. |
{
"scenario": "string",
"server": "string",
"sub": "string",
"tool": "string"
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The tool's result, cut to the server's resultMaxChars | object (application/json) |
400 |
The request is malformed (a body that is not JSON, a missing or invalid field, an unreadable body) or names a subsystem that is not initialized. The message says which. | 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 |
A switch is off, the tool is not allowed, or the caller may not read the scenario | ErrorResponse (application/json) |
404 |
No such scenario, or no such server in it | ErrorResponse (application/json) |
400 example (application/json)
{
"error": "missing collection"
}
401 example (application/json)
{
"error": "missing authentication"
}