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