Collection Config — MDDB API

Per-collection type, description, icon, color, and custom metadata

List collection aliases #

GET /v1/aliases

Aliases whose collection the caller may read (GO-044, v2.18.8). An alias is accepted wherever a collection name is, on every surface, and resolved once per request.

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	The aliases	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.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

Create an alias or move it to another collection #

PUT /v1/aliases/{alias}

Atomic: a request sees the old collection or the new one. The name may not be an existing collection, and the target may not be an alias. Needs write permission on the target and on the previous one.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
alias (required)	path	string

Request body #

Required.

Content type application/json: object

Property	Type	Description
collection (required)	string

{
  "collection": "string"
}

Responses #

Status	Description	Body
200	The alias	Alias (application/json)
400	Invalid name, target is an alias, or name is a collection	ErrorResponse (application/json)
403	Forbidden, or read-only mode

Remove an alias (the collection stays) #

DELETE /v1/aliases/{alias}

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
alias (required)	path	string

Responses #

Status	Description	Body
200	Removed
404	No such alias
403	Forbidden, or read-only mode

Get collection configuration #

GET /v1/collection-config

Get the configuration for a specific collection including type, description, icon, color, and custom metadata.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
collection (required)	query	string	Collection name

Responses #

Status	Description	Body
200	Collection configuration retrieved successfully	object (application/json)
400	Missing collection parameter	ErrorResponse (application/json)

Set collection configuration #

PUT /v1/collection-config

Set or update the configuration for a collection.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
collection (required)	string	Collection name
type	string	Collection type
description	string	Collection description
icon	string	Collection icon (emoji or icon name)
color	string	Collection color (hex code)
customMeta	object	Custom key-value metadata for the collection
wordpress	WordPressTargetConfig
retrieval	RetrievalProfile
responsePrompt	string	(v2.12.0+) How to format answers from this collection (RAG-002) At most 4096 characters.
code	CodeConfig
embedding	EmbeddingChunking
fts	CollectionFTS
quota	CollectionQuota
trackAccess	boolean	Record per-read access events for temporal analytics
trackHot	boolean	Maintain a hot-documents leaderboard for this collection
spellCorrect	boolean	Auto-correct FTS queries using the spell checker
spellLang	string	Override language for spell correction
storageBackend	string	Storage backend for this collection. Default: boltdb One of "boltdb", "memory", "s3".
storageConfig	StorageConfigDef
quantization	string	Vector quantization level for this collection. int8 gives 4x compression (~1% recall drop), int4 gives 8x compression (~2-3% recall drop). Default: float32 (no quantization). Requires vector-reindex after changing. One of "float32", "int8", "int4".
diskOnlyVectors	boolean	Low-memory vector mode: RAM holds only the quantized vectors while full-precision vectors stay on disk and are read back to rescore the candidate set exactly. Requires quantization (int8 or int4) and a vector-reindex after enabling. Default: false

{
  "code": {
    "includePaths": [
      "src"
    ],
    "role": "reference"
  },
  "collection": "blog",
  "color": "#3B82F6",
  "description": "Blog posts and articles",
  "diskOnlyVectors": true,
  "embedding": {
    "chunkMode": "code",
    "chunkSize": 4000
  },
  "fts": {
    "enabled": false,
    "excludeMetaKeys": [
      "url",
      "license",
      "vulnerable"
    ]
  },
  "icon": "🌐",
  "quantization": "int8",
  "quota": {
    "embeddingCallsPerDay": 0,
    "embeddingTokensPerDay": 0,
    "maxBytes": 0,
    "maxDocuments": 0,
    "maxVectors": 0
  },
  "responsePrompt": "string",
  "retrieval": {
    "contextTokenBudget": 8000,
    "defaultSearchType": "hybrid",
    "retrievalMode": "chunk",
    "topK": 40
  },
  "spellCorrect": false,
  "spellLang": "string",
  "storageBackend": "boltdb",
  "storageConfig": {
    "accessKey": "AKIAIOSFODNN7EXAMPLE",
    "bucket": "my-mddb-bucket",
    "endpoint": "s3.amazonaws.com",
    "prefix": "mddb/",
    "region": "us-east-1",
    "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "useTLS": true
  },
  "trackAccess": false,
  "trackHot": false,
  "type": "website",
  "wordpress": {
    "apiKey": "string",
    "url": "https://blog.example.com"
  }
}

Responses #

Status	Description	Body
200	Collection configuration set successfully	object (application/json)
400	Invalid request	ErrorResponse (application/json)

Delete collection configuration #

DELETE /v1/collection-config

Delete the configuration for a specific collection.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
collection (required)	query	string	Collection name

Responses #

Status	Description	Body
200	Collection configuration deleted successfully	object (application/json)
400	Missing collection parameter	ErrorResponse (application/json)

List all collection configurations #

GET /v1/collection-configs

Get all collection configurations.

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	All collection configurations retrieved successfully	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)
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.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

List installed corpus packs #

GET /v1/corpus

The collections installed from corpus packs (AGT-005), with what each pack's manifest said.

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	Installed packs	object (application/json)
403	No read permission

Build a corpus pack of a collection #

POST /v1/corpus/build

Takes a consistent snapshot of the collection — documents, full-text index, vectors, geo points — and streams it as a tar.zst pack with manifest.json and collection.db (AGT-005, docs/CORPUS-PACKS.md). Refused without a licence, for an encrypted collection and for one whose documents live in S3 or memory. Requires the admin permission.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: CorpusBuildRequest

{
  "collection": "string",
  "description": "string",
  "license": "CC-BY-4.0",
  "sources": [
    {
      "commit": "5f2c1e0",
      "license": "CC-BY-4.0",
      "repo": "https://github.com/kubernetes/website"
    }
  ],
  "version": "1.31"
}

Responses #

Status	Description	Body
200	The pack	string (binary) (application/zstd)
400	No licence, an invalid name, or a collection that cannot be packed	ErrorResponse (application/json)
403	Admin access required
404	The collection has no documents	ErrorResponse (application/json)

Install a corpus pack #

POST /v1/corpus/install

Installs an uploaded pack as a read-only collection, without a restart, re-embedding or reindexing. The pack is an upload, never a path or a URL for the server to fetch. A pack whose vectors were made by another model than the server's is installed with vectorsDisabled and a warning: hybrid search on it answers from full text. Requires the admin permission; refused in read-only mode.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type multipart/form-data: object

Property	Type	Description
pack (required)	string (binary)

{
  "pack": "string"
}

Responses #

Status	Description	Body
200	Installed	CorpusInstallResult (application/json)
400	Not a pack, a manifest without a licence, a checksum that does not match, a newer storage format, or a collection.db holding keys of another collection	ErrorResponse (application/json)
403	Admin access required, or read-only mode
409	A collection of that name already holds data	ErrorResponse (application/json)

Remove an installed corpus pack #

POST /v1/corpus/remove

Deletes the pack's collection — data, file and config. Requires the admin permission.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
name (required)	string

{
  "name": "string"
}

Responses #

Status	Description	Body
200	Removed	object (application/json)
403	Admin access required, or read-only mode
404	No pack of that name is installed	ErrorResponse (application/json)