Schemas — MDDB API

ESInfo #

Type: object

Property	Type	Description
name	string
cluster_name	string
cluster_uuid	string
version	object
version.number	string
version.build_flavor	string
version.build_type	string
version.build_hash	string
tagline	string

ESSearchRequest #

The Query DSL subset; see docs/ELASTICSEARCH-COMPAT.md.

Type: object

Property	Type	Description
query	object
knn	object
knn.field	string
knn.query_vector	array of number
knn.query_vector_builder	object
knn.query_vector_builder.text_embedding	object
knn.k	integer
knn.num_candidates	integer
knn.filter	object
size	integer	Default 10.
from	integer	Default 0.
sort	any
_source	any
highlight	object
aggs	object

ESSearchResponse #

Type: object

Property	Type	Description
took	integer
timed_out	boolean
hits	object
hits.total	object
hits.total.value	integer
hits.total.relation	string	One of "eq".
hits.max_score	number | null
hits.hits	array of object
hits.hits[]._index	string
hits.hits[]._id	string
hits.hits[]._score	number | null
hits.hits[]._source	object
hits.hits[].highlight	object
aggregations	object
limitCapped	boolean	from+size was lowered to the server's cap (#368)
limit	integer

ESWriteResult #

Type: object

Property	Type	Description
_index	string
_id	string
_version	integer
result	string	One of "created", "updated", "deleted", "not_found".
status	integer

ESBulkResponse #

Type: object

Property	Type	Description
took	integer
errors	boolean
items	array of object

ESError #

Type: object

Property	Type	Description
error	object
error.type	string
error.reason	string
error.root_cause	array of object
status	integer

CollectionQuota #

(v2.18.9+, GO-043) Limits for one collection; 0 or absent = no limit. On a write, an omitted quota keeps the stored one and {} removes it; changing it needs a global admin when auth is on (403 otherwise).

Type: object

Property	Type	Description
maxDocuments	integer (int64)	Documents the collection may hold Minimum 0.
maxBytes	integer (int64)	Stored bytes of its documents (revisions and indexes not counted) Minimum 0.
maxVectors	integer (int64)	Chunk vectors it may hold Minimum 0.
embeddingCallsPerDay	integer (int64)	Embedding provider calls per UTC day; over it documents wait as pending Minimum 0.
embeddingTokensPerDay	integer (int64)	Estimated tokens (characters / 4) embedded per UTC day Minimum 0.

CollectionQuotaUsage #

(v2.18.10, GO-043) What a collection uses of its quota, returned by GET /v1/collection-config only for a collection with a quota. Compare each field with the matching CollectionQuota limit. Embedding use is today's (UTC), counted only while the collection has an embedding budget, and starts from zero after a restart.

Type: object

Property	Type	Description
documents	integer (int64)	Documents the collection holds (maxDocuments)
bytes	integer (int64)	Stored bytes of its documents (maxBytes)
vectors	integer (int64)	Chunk vectors it holds (maxVectors)
embeddingCalls	integer (int64)	Embedding provider calls today (embeddingCallsPerDay)
embeddingTokens	integer (int64)	Estimated tokens embedded today (embeddingTokensPerDay)

QuotaExceeded #

(v2.18.9+, GO-043) A write or reindex refused by a quota.

Type: object

Property	Type	Description
error	string
code	string	One of "QUOTA_EXCEEDED".
status	integer	One of 429, 507.
collection	string	Empty for the server-wide limits
resource	string	One of "documents", "bytes", "vectors", "diskReserve", "vectorRam", "embeddingCalls", "embeddingTokens".
limit	integer (int64)
used	integer (int64)	Current use; for diskReserve, the bytes available
retryAfterSeconds	integer	Embedding budget only

RevisionConflict #

Type: object

Property	Type	Description
error	string
expectedRevision	string
currentRevision	string	The document's revision now; empty when it does not exist.

LimitUsed #

(v2.18.10, #368) The result count the search used. Present only with limitCapped.

Type: integer

LimitCapped #

(v2.18.10, #368) The requested (or default) limit was above MDDB_SEARCH_MAX_LIMIT or the collection's retrieval.maxTopK and was lowered to limit. Absent when nothing was capped.

Type: boolean

PassagesResponse #

What a search returns with format "passages" (AGT-002).

Type: object

Property	Type	Description
limit	LimitUsed
limitCapped	LimitCapped
passages (required)	array of Passage
total	integer
contextTruncated	boolean
indexing	IndexWaitResult
imageHits	array of ImageRef	(v2.18.9, RAG-010) Images the query matched by their picture, with includeImages.

Passage #

A place in a document (AGT-002, CODE-008): file, inclusive 1-based line range, the innermost definition holding the first line, and optionally the text.

Type: object

Property	Type	Description
collection (required)	string
key (required)	string
lang	string
path (required)	string	meta.path, or the key when there is none.
lines (required)	object
lines.start (required)	integer
lines.end (required)	integer
symbol	string	The innermost definition holding the first line.
kind	string	The definition kind when the passage is one: function, method, type, class, rule…
content	string
score	number
source	string	fts, vector, hybrid, cross, or a symbol relation.
tokens (required)	integer	Estimated tokens of content.
images	array of ImageRef	(v2.18.9, RAG-010) The document's images, with includeImages.

ImageRef #

(v2.18.9, RAG-010) An image document: one stored from a Markdown image link or a PDF picture, with kind image and meta.parent.

Type: object

Property	Type	Description
key (required)	string
lang (required)	string
altText	string
caption	string	The figure caption: a link title, an emphasised or "Figure" line under the image, a PDF page's "Figure" line.
page	integer	The PDF page; absent when unknown.
mimeType	string	One of "image/jpeg", "image/png", "image/gif", "image/webp".
width	integer
height	integer
parent	string	The document the image came from.
score	number	Similarity to the query, on image hits.
url (required)	string	GET path of the bytes: /v1/image?collection=…&key=…&lang=…

ImageIndexingStatus #

(v2.18.9, RAG-010) Image documents and their vectors.

Type: object

Property	Type	Description
documents	integer	Image documents holding an image.
embedded	integer	Of them, with an image vector.
model	string	The multimodal model; absent when the provider embeds no images.
note	string	Why images are not embedded: they are then found by alt text and captions only.

SymbolRequest #

Type: object

Property	Type	Description
collection (required)	string
name (required)	string
include	array of string
limit	integer	Per relation; also never above MDDB_SEARCH_MAX_LIMIT or the collection's retrieval.maxTopK (v2.18.10+). Default 20. Maximum 200.
includeContent	boolean

SymbolResult #

Type: object

Property	Type	Description
limit	LimitUsed
limitCapped	LimitCapped
collection	string
symbol	string
definitions	array of Passage
references	array of Passage
callers	array of Passage
callees	array of Passage
tests	array of Passage
siblings	array of Passage
truncated	boolean

GraphExpandOptions #

Tunes retrievalMode "graph" (SRCH-006; graphKinds CODE-008).

Type: object

Property	Type	Description
graphDepth	integer	Default 1. Maximum 3.
graphDecay	number	Default 0.5.
graphMaxNeighbours	integer	Default 10.
graphDirection	string	One of "in", "out", "both". Default "both".
graphKinds	array of string	Expand by symbol relation instead of following graphDirection.

IndexingStatus #

Queued indexing work (GO-042). Counters are since server start.

Type: object

Property	Type	Description
collection	string	Empty for the server-wide aggregate.
pendingEmbeddings	integer	Embedding jobs queued or running.
failedEmbeddings	integer	Jobs that left a document without vectors (provider failure or a full queue); reindex to recover.
completedEmbeddings	integer
pendingMetadata	integer	Queued metadata-index updates from batch updates. Single writes never appear here.
progress	number	completed / (completed + pending); 1 when nothing is pending.
oldestPendingAt	string (date-time)
provider	string	Embedding model; absent when none is configured.
indexed	boolean	Nothing pending — a search sees every document written so far.
images	ImageIndexingStatus
trainingCollections	array of string	(v2.18.10+, GO-047) Collections whose trainable indexes (ivf, pq, opq, sq, sq4) are still training after a load; flat and hnsw already answer for them. Absent when none are.

IndexWaitResult #

Type: object

Property	Type	Description
waitedMs	integer
timedOut	boolean	The wait ran out before the work drained; results may miss the newest documents.

WriteIndexing #

Type: object

Property	Type	Description
embeddingQueued	boolean	The write queued an embedding: searchable by text now, by meaning when it finishes.

AddResponse #

Type: allOf Document & object

GroupBy #

Result grouping (SRCH-016, v2.18.8). Keeps at most perGroup results for each value of key, best first, then cuts to topK. key is a metadata key (its first value), document (chunks of one document — use with retrievalMode: chunk) or collection (cross-search). Documents without the metadata key are never merged with each other. Order: candidates (topK × oversample) → parent dedupe → groupBy → MMR → topK. Parent-mode deduplication is {key: document, perGroup: 1}. A collection's retrieval profile may set a default; a request's own groupBy wins.

Type: object

Property	Type	Description
key (required)	string
perGroup	integer	Default 1. Minimum 1. Maximum 100.

MetaFilter #

Operator metadata filter (SRCH-017, v2.18.8), ANDed with filterMeta. One condition per metadata key; keys are ANDed. Inside a condition the value operators (in, prefix, contains, gt, gte, lt, lte) must all hold for the same value, and a document with several values matches when any one does. not and exists judge the whole document, so not keeps documents that lack the key. Every operator is answered from the metadata index without reading document bodies. Bounds compare numerically when both sides are numbers, by time when the value is a date and the bound a date or unix timestamp, lexically otherwise. An unknown operator is a 400 that names it.

Type: object

MetaCondition #

Type: object

Property	Type	Description
in	oneOf string | array of string	Exact values; one string or an array.
prefix	string	Value starts with (exact case; seeks the index).
contains	string	Value contains the substring (case-insensitive).
gt	oneOf string | number
gte	oneOf string | number
lt	oneOf string | number
lte	oneOf string | number
not	oneOf string | array of string	The document has none of these values (documents without the key match).
exists	boolean	The document has (true) or lacks (false) the key.

CodeGraphResponse #

One traversal of the code connection graph. Nodes and edges are sorted, so two responses can be diffed to see what a change did.

Type: object

Property	Type	Description
collection	string
root	string	The key the traversal started from
direction	string	One of "in", "out", "both".
depth	integer
nodes	array of object
nodes[].key	string
nodes[].docId	string
nodes[].lang	string
nodes[].language	string	Source language, e.g. css, html, javascript, c, go, python, terraform, yaml
nodes[].depth	integer	Hops from the root, by the shortest path
edges	array of object
edges[].from	string
edges[].to	string
edges[].kind	string	One of "uses-selector", "calls", "references", "imports".
edges[].symbol	string	The selector or path that justifies this edge. Without it the answer is only "these files are related", which is not actionable.
edges[].direction	string	One of "in", "out".
edges[].lines	object	Present only when lines was requested. A symbol usually occurs more than once, so these are the first occurrence — a place to jump to, not a complete answer. Zero means the symbol is not literal text in that file.
edges[].lines.fromLine	integer
edges[].lines.toLine	integer
truncated	boolean	A depth or degree limit cut the walk short, so "nothing else depends on this" cannot be read from a truncated result.

MCPAPIKeySummary #

Public view of an MCP API key. Carries no key material: fingerprint is four bytes of SHA-256 over the key, and keyPrefix holds only the scheme marker every key starts with.

Type: object

Property	Type	Description
toolsets	array of string	Toolsets the key is limited to (MCP-003); absent means all.
keyPrefix	string	Scheme marker only — never a slice of the key.
fingerprint	string	Stable, non-reversible identifier; matches what the server logs.
name	string
createdAt	integer (int64)
expiresAt	integer (int64)	Unix timestamp; absent when the key never expires.
disabled	boolean

MCPAPIKeyRef #

Identifies an existing key by its full value.

Type: object

Property	Type	Description
key (required)	string

RotationJob #

Encryption re-keying job descriptor (2.9.16+).

Type: object

Property	Type	Description
id	string
status	string	One of "queued", "running", "completed", "failed".
primaryKeyID	integer
startedAt	integer (int64)	Unix nanoseconds
finishedAt	integer (int64)
scanned	integer (int64)
reencrypted	integer (int64)
skipped	integer (int64)
errors	integer (int64)
lastError	string

WikiImportResponse #

Type: object

Property	Type	Description
imported	integer	Number of pages successfully imported
skipped	integer	Number of pages skipped (wrong namespace, redirects, empty)
failed	integer	Number of pages that failed to import
errors	array of string	Error messages (capped at 10)
collection	string	Target collection name
durationMs	integer (int64)	Total import duration in milliseconds

TemporalEvent #

Type: object

Property	Type	Description
docId	string
collection	string
eventType	string	One of "create", "update", "access".
timestamp	integer (int64)

Document #

Type: object

Property	Type	Description
id	string	Auto-generated document ID
key	string	Document key (unique within collection and language)
lang	string	Language code (e.g., en_US, pl_PL, de_DE)
meta	object	Metadata key-value pairs (values are arrays)
contentMd	string	Markdown content
addedAt	integer (int64)	Unix timestamp when document was created
updatedAt	integer (int64)	Unix timestamp when document was last updated

AddRequest #

Type: object

Property	Type	Description
expectedRevision	string	(v2.18.8, INT-021) Write only if the document is at this revision; 409 otherwise, including when it does not exist yet.
collection (required)	string	Collection name
key (required)	string	Document key
lang (required)	string	Language code
meta	object	Metadata key-value pairs
contentMd (required)	string	Markdown content

AddBatchRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
documents (required)	array of AddBatchDocument	Documents to add

AddBatchDocument #

Type: object

Property	Type	Description
key (required)	string	Document key
lang (required)	string	Language code
contentMd (required)	string	Markdown content
meta	object	Metadata key-value pairs
saveRevision	boolean	Whether to save a revision Default false.

AddBatchResponse #

Type: object

Property	Type	Description
added	integer	Number of documents added
updated	integer	Number of documents updated
failed	integer	Number of documents that failed
errors	array of string	Error messages for failed documents
embeddingDropped	integer	(v2.15.0+) Documents stored without a vector because the embedding queue was full and the write gave up waiting. Present only when non-zero. failed stays 0: the documents ARE stored, they are just unreachable by vector and hybrid search until POST /v1/vector-reindex fills them in. See MDDB_EMBEDDING_QUEUE_SIZE / MDDB_EMBEDDING_QUEUE_WAIT.

BulkIngestSubmitRequest #

Type: object

Property	Type	Description
collection (required)	string	Target collection
documents (required)	array of AddBatchDocument	Documents to ingest; processed in chunks of 500
callbackUrl	string	Optional URL that receives a POST with the final job record on completion

BulkIngestJob #

Type: object

Property	Type	Description
id	string	Unique job identifier
collection	string
status	string	- pending: queued, worker has not picked it up yet - processing: worker is actively committing chunks - completed: finished (may include per-document failures) - failed: all documents failed or the server restarted mid-job - cancelled: user cancelled while still pending One of "pending", "processing", "completed", "failed", "cancelled".
total	integer	Total documents submitted
processed	integer	Documents processed so far (includes successes and failures)
added	integer	Documents added to the collection
updated	integer	Documents updated
failed	integer	Documents that failed to commit
errors	array of string	Up to 50 error messages recorded during processing
callbackUrl	string	Webhook URL supplied at submit time
submittedAt	integer (int64)	Unix timestamp (seconds) when the job was submitted
startedAt	integer (int64)	Unix timestamp when the worker picked up the job
completedAt	integer (int64)	Unix timestamp when the job reached a terminal status

GeoJSONPolygon #

Type: object

Property	Type	Description
type	string	GeoJSON geometry type. Optional — the handler fills it in when omitted. One of "Polygon".
coordinates (required)	array of array of array of number	Array of linear rings. The first ring is the outer boundary; any subsequent rings are holes. Each ring is an array of [lng, lat] pairs (RFC 7946 order) with at least 3 points.

GeoJSONMultiPolygon #

Type: object

Property	Type	Description
type	string	One of "MultiPolygon".
coordinates (required)	array of array of array of array of number	Array of Polygon coordinate arrays. Union semantics — a document matches if it lies inside any member polygon.

GeoPolygonRequest #

Exactly one of polygon or multiPolygon must be set.

Type: object

Property	Type	Description
collection (required)	string
polygon	GeoJSONPolygon
multiPolygon	GeoJSONMultiPolygon
filterMeta	object	Optional metadata pre-filter (AND across keys, OR within key)
includeContent	boolean	Default false.

GeoPolygonResponse #

Type: object

Property	Type	Description
results	array of object
results[].document	object
results[].rank	integer
total	integer
shape	string	One of "polygon", "multiPolygon".
algorithm	string

IngestRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
documents (required)	array of IngestDocument	Documents to ingest
options	IngestOptions

IngestDocument #

A document to store. Send Markdown in contentMd, or (v2.18.9+) a file in contentBase64 with its format: the server converts it with the same converters /v1/upload uses and stores the Markdown, with meta.sourceFormat set to the format.

Type: object

Property	Type	Description
url	string (uri)	Source URL (used for key derivation and auto-injected as source_url metadata)
key	string	Document key (derived from URL if empty)
lang (required)	string	Language code
contentMd	string	Markdown content
meta	object	Metadata key-value pairs
extractFrontmatter	boolean	Parse YAML frontmatter from content and merge into metadata Default false.
scrapedAt	integer (int64)	Unix timestamp of when the content was scraped (auto-injected as scraped_at metadata)
scraper	string	Scraper identifier (auto-injected as scraper metadata)
ttl	integer (int64)	Time-to-live in seconds
format	string	(v2.18.9+) Convert the document from this format: html, pdf, docx, odt, rtf, xlsx, ods, csv, tsv, pptx, odp, epub, eml, mbox, tex, yaml, log. Empty means the key's extension; a signature in the content (%PDF, a zip's main part) wins over both. Without contentBase64, contentMd is taken as the file's text (HTML sent as a string, say).
contentBase64	string (byte)	(v2.18.9+) The file to convert, base64-encoded. With skipDuplicates, the converted Markdown is what is compared, so an unchanged file is skipped.
images	array of object	(v2.18.9, RAG-010) The files a Markdown document's image links name by relative path, read with options.extractImages. An image whose bytes changed is written even under skipDuplicates.
images[].path (required)	string
images[].contentBase64 (required)	string (byte)

IngestOptions #

Type: object

Property	Type	Description
skipDuplicates	boolean	Skip documents whose content hasn't changed (CRC32 hash comparison) Default false.
skipEmbeddings	boolean	Skip embedding generation for this batch Default false.
skipFts	boolean	Skip FTS indexing for this batch Default false.
skipWebhooks	boolean	Skip webhook firing for this batch Default false.
autoConfigureCollection	boolean	Auto-configure collection as "scraping" type if it doesn't exist Default false.
saveRevision	boolean	Save revision history for all documents in this batch Default false.
profile	string	(v2.12.0+) Named preset of the flags above. default keeps every step. fast trades parsing fidelity and per-document bookkeeping for throughput: text-only parsing, no webhooks, no revisions, duplicates skipped. Notably fast does NOT skip embeddings or FTS — that is a separate decision with its own flag. Any flag set explicitly overrides the preset, so fast plus saveRevision: true keeps revisions. An unknown name is rejected with 400 rather than falling back silently. One of "default", "fast". Default "default".
textOnly	boolean	(v2.12.0+) Extract plain text from html/docx/odt instead of rebuilding their structure as Markdown. Implied by profile: fast. PDF has no text-only variant: its extractor already produces plain text and builds no structure. Default false.
extractImages	boolean	(v2.18.9, RAG-010) Store the images of Markdown documents (data URIs, files sent in images) and PDFs (JPEG and 8-bit RGB/gray Flate pictures) as image documents under KEY/images/: kind image, meta.parent, altText, caption, page. At most 2 MB each; JPEG, PNG, GIF, WebP. On by default in a collection of type images. Default false.
fetchRemoteImages	boolean	(v2.18.9, RAG-010) With extractImages, fetch Markdown image links to http(s) URLs through the SSRF guard. Off by default. Default false.

IngestResponse #

Type: object

Property	Type	Description
added	integer	Number of documents added
updated	integer	Number of documents updated
skipped	integer	Number of documents skipped (deduplication)
failed	integer	Number of documents that failed
errors	array of string	Error messages for failed documents
collection	string	Collection name
durationMs	integer (int64)	Total processing time in milliseconds
profile	string	(v2.12.0+) Which ingest profile actually applied, so a corpus loaded months ago can be explained without guessing which flags the caller sent.
sanitized	integer	How many documents had undecodable bytes dropped because their text was not valid UTF-8 (GO-036). A bulk import sanitises rather than failing, so one page in Windows-1250 cannot abort the other twenty thousand — but the count says how many were changed. Single-document writes refuse instead, with an error naming the encoding.
keyCollisions	array of string	(v2.12.0+) Input keys that differ only in letter case and therefore name one document — README.md and readme.md are the same document, and the last write wins. The write still happens; refusing a large import over a spelling would be worse. Absent when there are no collisions.
conversions	array of IngestConversion	(v2.18.9+, GO-046) Every document converted from a file sent with contentBase64/format — including an email's attachments and a mailbox's messages — with how well it converted. A scan without a text layer is named here, not found later.

IngestConversion #

Type: object

Property	Type	Description
key	string
format	string	The format the document was converted from
conversionConfidence	number (double)	Minimum 0. Maximum 1.
conversionWarnings	array of string

GetRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
key (required)	string	Document key
lang (required)	string	Language code
env	object	Template variables for substitution

SearchRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
filterMeta	object	Metadata filters (AND between keys, OR between values)
filter	MetaFilter
sort	string	Sort field One of "addedAt", "updatedAt", "key".
asc	boolean	Sort ascending (default false)
limit	integer	Maximum number of results
offset	integer	Number of results to skip

DeleteRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
key (required)	string	Document key
lang (required)	string	Language code

DeleteCollectionRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name to delete

ExportRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
filterMeta	object	Optional metadata filters
format (required)	string	Export format One of "ndjson", "zip".

TruncateRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
keepRevs (required)	integer	Number of revisions to keep per document (0 = delete all history)
dropCache	boolean	Clear document cache after truncation

Stats #

Type: object

Property	Type	Description
databasePath	string
databaseSize	integer (int64)	Database file size in bytes
mode	string	One of "read", "write", "wr".
collections	array of object
collections[].name	string
collections[].documentCount	integer
collections[].revisionCount	integer
collections[].metaIndexCount	integer
collections[].checksum	string	8-character hex CRC32 checksum of the collection
totalDocuments	integer
totalRevisions	integer
totalMetaIndices	integer
indexing	IndexingStatus
statsComputedAt	string (date-time)	(v2.18.5+) When the counts were computed (#349)
statsAgeSeconds	integer	(v2.18.5+) Age of the counts. Zero-ish on a database written since only by cheap walks
statsPending	boolean	(v2.18.5+) The first walk after a start is still running; counts are omitted, ask again shortly
indexQueue	object	Async metadata-indexing queue health. fallbacks counts jobs that were indexed synchronously because the queue was full (they are never dropped). Omitted when the queue is not initialised.
indexQueue.processed	integer
indexQueue.failed	integer
indexQueue.fallbacks	integer
indexQueue.queueLen	integer
uptime	string

VectorSearchRequest #

Type: object

Property	Type	Description
includeImages	boolean	(v2.18.9, RAG-010) Attach each hit's image documents — those whose meta.parent is the hit's key — as images, with alt text, caption and page. Without it nothing is looked up and the response is unchanged.
queryImage	string	(v2.18.9, RAG-010) Search by an image instead of text: base64, a data URI, or an http(s) URL fetched through the SSRF guard (at most 2 MB; JPEG, PNG, GIF or WebP). Needs a provider that embeds images (Voyage, Cohere Embed v3+); otherwise 400. The results are image documents (algorithm image), each naming its meta.parent.
format	string	passages returns path + lines + enclosing definition + text per hit instead of documents (AGT-002, v2.18.8); the response is a PassagesResponse. One of "results", "passages".
passageLines	integer	Lines of context on each side of a hit (default 10); a hit inside a shorter definition returns the definition. Minimum 0. Maximum 200.
graphExpand	GraphExpandOptions
readLevel	string	indexedPlusPending also returns documents whose embedding is still queued, found by their text and marked pendingEmbedding (vector search; hybrid search already includes them). GO-042. One of "indexed", "indexedPlusPending".
waitForIndex	integer	Wait up to this many ms for queued embeddings before searching; running out of time is not an error (indexing.timedOut). Minimum 0. Maximum 30000.
waitForKeys	array of string	With waitForIndex, wait only for these document keys.
groupBy	GroupBy
oversample	number	(v2.12.0+) Recall/latency knob: candidates fetched per requested result before deduplication, merging or rescoring trims them. Omitted, uses the collection's retrieval profile then MDDB's default of 3.0. Out of range returns 422 rather than clamping. See SEARCH.md#oversampling-v2120 for measured effect. Minimum 1. Maximum 10.
collection (required)	string	Collection name to search
query	string	Natural language query string (required if queryVector is not provided)
queryVector	array of number (float)	Raw embedding vector (optional, use instead of query for pre-computed embeddings)
topK	integer	Number of top results to return (default 5) Default 5.
threshold	number (float)	Minimum cosine similarity score (0.0 to 1.0) Minimum 0. Maximum 1.
filterMeta	object	Metadata filters to narrow results before ranking
filter	MetaFilter
includeContent	boolean	Whether to include document content in results (default false) Default false.
algorithm	string	Search algorithm to use (default "flat", or the collection profile's retrieval.vectorAlgorithm). - auto (v2.18.9+): the query planner chooses per query from the collection size, the indexes already built and the filter's selectivity; it never builds an index on the query path. See SEARCH.md#auto-the-server-chooses-v2189. - flat: Exact brute-force cosine similarity (most accurate, slower for large datasets) - hnsw: Hierarchical Navigable Small World graph (fast approximate, best general-purpose) - ivf: Inverted File Index with k-means clustering (good for large datasets) - pq: Product Quantization (compressed, lowest memory, slightly less accurate) - opq: Optimised Product Quantization — PQ with a learned rotation - sq: Scalar Quantization to 8 bits per dimension (4x smaller than float32) - sq4: Scalar Quantization to 4 bits, two dimensions per byte (8x smaller). Measured at 99.5% of sq's recall@10 for half its storage — see TestQuantizerRecallCurve. Reach for it when a collection no longer fits in RAM at sq. - bq: Binary Quantization to 1 bit per dimension (32x smaller, much coarser) - quantized: Follows the collection's own quantization setting One of "flat", "auto", "hnsw", "ivf", "pq", "opq", "sq", "sq4", "bq", "quantized". Default "flat".
distanceMetric	string	Distance metric for similarity computation One of "cosine", "dot_product", "euclidean". Default "cosine".
retrievalMode	string	Result granularity (default "parent"). - parent: One result per document, scored by its best-matching chunk. - chunk: One result per matching chunk; each result carries chunkIndex and chunkText with the exact matching passage — ideal for feeding precise context to an LLM. - window: Like chunk, but the passage is widened with windowSize neighboring chunks on each side. One of "parent", "chunk", "window", "graph". Default "parent".
windowSize	integer	Neighbor chunks per side in "window" retrieval mode (default 1) Default 1.
mmr	boolean	Diversify results with Maximal Marginal Relevance reranking. Selection balances query relevance against similarity to already selected results, so near-duplicate documents stop crowding out distinct ones. Default false.
mmrLambda	number (float)	MMR relevance/diversity balance in [0,1] — 1.0 keeps the pure relevance order, 0.0 maximizes diversity (default 0.5). Default 0.5. Minimum 0. Maximum 1.
explain	PlanExplain
latencyTargetMs	PlanLatencyTarget
positive	FeedbackExamples
negative	FeedbackExamples
feedbackMode	FeedbackMode
feedbackWeight	FeedbackWeight
rocchio	RocchioWeights
queryDecomposition	QueryDecompositionMode

PlanExplain #

(v2.18.9+, SRCH-013) Add plan to the response — the vector index that answered and why.

Type: boolean

Default false.

PlanLatencyTarget #

(v2.18.9+, SRCH-013) Latency goal in ms for algorithm auto; 10 or less favours a quantized index (bq, sq4, sq) on 10,000+ vectors. Out of range returns 422.

Type: integer

Minimum 0. Maximum 60000.

SearchPlan #

How a vector search ran and why (v2.18.9+, SRCH-013). Present only when the request set explain.

Type: object

Property	Type	Description
algorithm	string	The index that answered; auto for a cross search, whose targets are planned one by one.
prefilter	boolean	The filter was applied first and the admitted documents scanned exactly.
candidates	integer	Hits asked of the index, topK × oversample.
iterativeScan	boolean	A filtered index search came back short of topK and the scan continued further into the index.
reasons	array of string
collections	object	Cross search with auto, one plan per target collection.
feedback	FeedbackApplied
decomposition	QueryDecomposition

QueryDecompositionMode #

(v2.18.10+, SRCH-020) auto searches a query of several clauses — split at sentence punctuation and at "and" between clauses, at most 4 parts — part by part as well as whole, and each document keeps its best score. One embedding call per part. A query with nothing to split, or sent as queryVector, is searched whole. Hybrid search splits the vector half only. off is today's search. Another value returns 422.

Type: string

One of "off", "auto". Default "off".

QueryDecomposition #

(v2.18.10+, SRCH-020) How the query was split, in the plan; set with queryDecomposition auto.

Type: object

Property	Type	Description
parts	integer	Parts searched besides the whole query; 1 = not split.
texts	array of string	The parts, when there was more than one.

FeedbackExamples #

(v2.18.9+, SRCH-015) Relevance feedback examples: a document key or ID from an earlier result, or a vector of the query's dimensions. {"key": ...} and {"vector": [...]} are accepted too. A key with no embedding returns 422.

Type: array of oneOf string \| array of number (float) \| object

FeedbackMode #

(v2.18.9+, SRCH-015) query moves the query vector (Rocchio) and works with every index; rescore re-ranks the topK × oversample candidates by similarity to the examples.

Type: string

One of "query", "rescore". Default "query".

FeedbackWeight #

(v2.18.9+, SRCH-015) rescore mode — how much the examples move a score.

Type: number

Default 0.5. Minimum 0. Maximum 10.

RocchioWeights #

(v2.18.9+, SRCH-015) query mode weights of q′ = alpha·q + beta·mean(positive) − gamma·mean(negative).

Type: object

Property	Type	Description
alpha	number	Default 1. Minimum 0. Maximum 10.
beta	number	Default 0.75. Minimum 0. Maximum 10.
gamma	number	Default 0.25. Minimum 0. Maximum 10.

FeedbackApplied #

(v2.18.9+, SRCH-015) The correction relevance feedback made, in the plan.

Type: object

Property	Type	Description
mode	string	One of "query", "rescore".
positive	integer
negative	integer
alpha	number
beta	number
gamma	number
queryShift	number	1 − cosine(query, corrected query), query mode.
weight	number
rescored	integer	Candidates rescored, rescore mode.

VectorSearchResponse #

Type: object

Property	Type	Description
limit	LimitUsed
limitCapped	LimitCapped
imageHits	array of ImageRef	(v2.18.9, RAG-010) With includeImages and a provider that embeds images: the images whose picture matches the query, scored in the image space and kept apart from results.
plan	SearchPlan
indexing	IndexWaitResult
results (required)	array of VectorSearchResultItem
total	integer	Number of results returned
model	string	Embedding model used
dimensions	integer	Embedding vector dimensions
algorithm	string	Algorithm used for this search
distanceMetric	string	Distance metric used for this search
searchStats	SearchStats

VectorSearchResultItem #

Type: object

Property	Type	Description
images	array of ImageRef	(v2.18.9, RAG-010) The document's images, with includeImages.
pendingEmbedding	boolean	The document's embedding is still queued; it was found by its text (GO-042).
group	string	Group this result counted against (only with groupBy, SRCH-016).
groupRank	integer	1-based place of this result within its group (only with groupBy).
document	Document
score	number (float)	Cosine similarity score (0.0 to 1.0)
rank	integer	Result rank (1-based)
chunkIndex	integer	Index of the matching chunk (only in chunk/window retrieval modes)
chunkText	string	The matching passage text (only in chunk/window retrieval modes)

VectorReindexRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name to reindex
force	boolean	If true, re-embed even if content is unchanged Default false.
async	boolean	(v2.18.4+) Run as a background job; poll /v1/vector-reindex/jobs/{id} Default false.

VectorReindexResponse #

Type: object

Property	Type	Description
embedded	integer	Number of documents embedded
skipped	integer	Number of documents skipped (content unchanged)
failed	integer	Number of documents that failed to embed
totalChunks	integer	Total number of chunks embedded across all documents
errors	array of string	Error messages for failed embeddings

VectorStatsResponse #

Type: object

Property	Type	Description
enabled	boolean	Whether vector search is enabled
provider	string	Embedding provider name
model	string	Embedding model name
dimensions	integer	Embedding vector dimensions
index_ready	boolean	Whether the vector index is loaded and ready
statsComputedAt	string (date-time)	(v2.18.5+) When the counts were computed; they come from the shared statistics snapshot (#349)
statsAgeSeconds	integer	(v2.18.5+) Age of the counts
statsPending	boolean	(v2.18.5+) The first count after a start is still running
indexProgress	object	(v2.18.4+) Present while the index loads at startup (#346).
indexProgress.collectionsDone	integer
indexProgress.collectionsTotal	integer
indexProgress.vectorsDone	integer
indexProgress.vectorsTotal	integer
indexProgress.percent	number
indexProgress.etaSeconds	integer	-1 until it can be estimated
indexProgress.current	string	Collection being loaded
indexProgress.readyCollections	array of string	Collections that already answer
indexTraining	object	(v2.18.10+, GO-047) Present while the trainable indexes are training after a load. A collection is searchable with flat and hnsw once its vectors are in; the indexes listed refuse it with 503 until it is trained, and algorithm auto does not pick them.
indexTraining.current	string	Collection being trained now
indexTraining.pending	array of string	Collections not trained yet, current included, in training order
indexTraining.indexes	array of string	Indexes that wait for the training (ivf, opq, pq, sq, sq4)
collections	object	Per-collection embedding statistics
queue	object	(v2.15.0+) Embedding queue state. It answers the question the two document counts cannot: whether embedding is still running or gave up. Absent when no embedding worker is configured.
queue.size	integer	Queue capacity (MDDB_EMBEDDING_QUEUE_SIZE)
queue.depth	integer	Jobs waiting now; above zero means embedding is still running
queue.dropped	integer (int64)	Documents stored without a vector since startup, because the queue was full and the write gave up waiting. Repair with POST /v1/vector-reindex.
queue.wait	string	How long a write waits for queue room (MDDB_EMBEDDING_QUEUE_WAIT)
chunking	object	Chunking configuration
chunking.enabled	boolean	Whether document chunking is enabled
chunking.chunkSize	integer	Maximum characters per chunk

FTSSearchRequest #

Type: object

Property	Type	Description
includeImages	boolean	(v2.18.9, RAG-010) Attach each hit's image documents — those whose meta.parent is the hit's key — as images, with alt text, caption and page. Without it nothing is looked up and the response is unchanged.
format	string	passages returns path + lines + enclosing definition + text per hit instead of documents (AGT-002, v2.18.8); the response is a PassagesResponse. One of "results", "passages".
passageLines	integer	Lines of context on each side of a hit (default 10); a hit inside a shorter definition returns the definition. Minimum 0. Maximum 200.
groupBy	GroupBy
collection (required)	string	Collection name to search
query (required)	string	Full-text search query string
limit	integer	Maximum number of results (default 50) Default 50.
algorithm	string	Scoring algorithm to use (default "tfidf"). - tfidf: Classic TF-IDF scoring - bm25: Okapi BM25 with document length normalization (k1=1.2, b=0.75) - bm25f: BM25F field-weighted scoring — applies different weights to title, metadata, and content - pmisparse: PMISparse — BM25 + PMI query expansion (invented by Tradik Limited) One of "tfidf", "bm25", "bm25f", "pmisparse". Default "tfidf".
fuzzy	integer	Typo tolerance level (default 0). - 0: Off — exact term matching only - 1: Low — matches terms within 1 edit distance (e.g. "javascrip" → "javascript") - 2: Medium — matches terms within 2 edit distances One of 0, 1, 2. Default 0.
filterMeta	object	Metadata filters to narrow results before scoring (AND between keys, OR between values)
filter	MetaFilter
fieldWeights	object	Field weights for BM25F algorithm (keys are "title", "meta", "content")
bm25K1	number	(v2.18.8, SRCH-018) BM25 term-frequency saturation for this query; default the collection profile, then 1.2. bm25 and bm25f only. Minimum 0. Maximum 3.
bm25B	number	(v2.18.8, SRCH-018) BM25 length normalisation for this query; 0 ignores length. Default the collection profile, then 0.75. Minimum 0. Maximum 1.
disableStem	boolean	Disable stemming for this query Default false.
disableSynonyms	boolean	Disable synonym expansion for this query Default false.
mode	string	Search mode (default "auto"). Auto-detect parses the query to determine the appropriate mode. - auto: Auto-detect from query syntax - simple: Classic keyword search - boolean: AND/OR/NOT operators, +required, -excluded - phrase: Exact word sequence ("quoted phrases") - wildcard: Pattern matching (* any chars, ? single char) - proximity: Terms within N words ("term1 term2"~5) - expression: Full query DSL with nested parens, precedence, and mixed atoms (v2.9.15+) One of "auto", "simple", "boolean", "phrase", "wildcard", "proximity", "expression". Default "auto".
distance	integer	Maximum word distance for proximity search (default 5) Default 5.
lang	string	Language code for query tokenization (e.g., "en", "pl", "de"). Uses language-specific stemmer and stop words. Language codes are normalized: "en_US" → "en", "pl_PL" → "pl". Falls back to server default if omitted.
rangeMeta	array of RangeFilter	Range filters on metadata or timestamp fields
boost	object	Per-query boost map. Keys follow the format "metaKey:metaValue". Positive values multiply the score of documents matching that metadata pair (e.g. 5.0 = 5× boost); negative values demote (e.g. -2.0 = ½× penalty). Zero is ignored. Multipliers from multiple matching entries combine multiplicatively; the final per-document multiplier is floored at 0.001 to prevent total score collapse.
highlight	boolean	When true (v2.9.15+), each result gains a highlights array with text snippets around matched terms. Works uniformly across every FTS mode. Default false.
highlightTag	string	Wrap tag for matched terms (close tag derived automatically) Default "\u003cmark\u003e".
maxHighlights	integer	Cap fragments per result Default 3.
fragmentSize	integer	Approximate chars per fragment (snapped to word boundaries) Default 150.
facetBy	array of string	(v2.9.15+) Metadata keys to aggregate into facets on the response. What is counted is set by facetScope.
facetMaxValues	integer	(v2.9.15+) Cap per-key bucket count; 0 = unlimited Default 0.
facetScope	string	(v2.17.0+) returned counts facets over the documents in results (after filtering, boosts, curation, the limit). all counts over every document that matched the query and filters, before pagination, and reports their number in matched. One of "returned", "all". Default "returned".
cacheTtl	integer	Serve this search from the result cache when a matching response is no older than this many seconds, and store the response for that long. Omitted or 0 means no caching at all — neither served nor stored — so a request that says nothing keeps the default behaviour and the default freshness. Writes to the collection invalidate its cached results immediately. The response carries X-MDDB-Cache: hit|miss. Capped at 3600; MDDB_SEARCH_CACHE_SIZE=0 disables the cache server-wide. Minimum 0. Maximum 3600.

Highlight #

Type: object

Property	Type	Description
fragment	string	Snippet with matched terms wrapped in the configured tag; ellipsis … markers denote truncation
matchedTerms	array of string
startOffset	integer	Byte offset into the raw ContentMD where the fragment begins
endOffset	integer
startLine	integer	(v2.12.0+) 1-based, inclusive line where the fragment begins. This is what makes a result a place to edit rather than a document to read — see docs/API.md#finding-the-place-not-just-the-file.
endLine	integer	(v2.12.0+) 1-based, inclusive line where the fragment ends

RangeFilter #

Type: object

Property	Type	Description
field	string	Field name — metadata key, or built-in "addedAt" / "updatedAt"
gte	string	Greater than or equal (numeric, date string, or unix timestamp)
lte	string	Less than or equal
gt	string	Greater than
lt	string	Less than

FTSSearchResponse #

Type: object

Property	Type	Description
limit	LimitUsed
limitCapped	LimitCapped
results (required)	array of FTSResultItem
total	integer	Number of results returned
algorithm	string	Algorithm used for this search
mode	string	Search mode used (simple, boolean, phrase, wildcard, proximity)
lang	string	Language used for query tokenization
fuzzy	integer	Typo tolerance level used
searchStats	SearchStats
facets	FacetMap
matched	integer	(v2.17.0+) Documents that matched the query and filters before pagination. Present only with facetScope: all.
stemmingActive	boolean	Whether stemming was applied to this query
synonymsActive	boolean	Whether synonym expansion was applied to this query
fieldWeights	object	Effective per-field weights used for scoring (BM25F)
spellCorrected	object | null	Spell-correction info when the collection has spellCorrect enabled and the query was auto-corrected (original and corrected terms).

FacetBucket #

Type: object

Property	Type	Description
value (required)	string
count (required)	integer

FacetMap #

(v2.9.15+) Per-key facet counts. Buckets are ordered by count desc, value asc. Missing keys produce an empty bucket list so UIs can render a stable facet group layout across queries.

Type: object

FTSResultItem #

Type: object

Property	Type	Description
images	array of ImageRef	(v2.18.9, RAG-010) The document's images, with includeImages.
group	string	Group this result counted against (only with groupBy, SRCH-016).
groupRank	integer	1-based place of this result within its group (only with groupBy).
document	Document
score	number (float)	TF-IDF relevance score
matchedTerms	array of string	Terms from the query that matched
highlights	array of Highlight	(v2.9.15+) Snippets around the matched terms; only with highlight=true.
pinned	boolean	(v2.9.15+) Marked true when a curation rule injected this row at a fixed position. Clients can use this for distinct styling. Default false.

ImportURLRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
url (required)	string (uri)	URL to fetch content from
key	string	Document key (derived from URL if empty)
lang (required)	string	Language code
meta	object	Additional metadata to merge with frontmatter
ttl	integer	Time-to-live in seconds (0 = no expiration)

SetTTLRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
key (required)	string	Document key
lang (required)	string	Language code
ttl (required)	integer	Time-to-live in seconds (0 = remove TTL)

Webhook #

Type: object

Property	Type	Description
id	string	Unique webhook ID
url	string (uri)	Webhook callback URL
events	array of string	Event types to listen for. In 2.18.9, backup.failed fires when a scheduled backup fails, and quota.exceeded when a write or embedding is refused by a collection quota, the disk reserve or the vector RAM limit. In 2.18.10, source.synced fires when a run of a synced source (a cron rule's sync) finishes.
collection	string	Collection filter (empty = all collections)
createdAt	integer (int64)	Unix timestamp when the webhook was created

RegisterWebhookRequest #

Type: object

Property	Type	Description
url (required)	string (uri)	Webhook callback URL
events (required)	array of string	Event types to listen for. In 2.18.9, backup.failed fires when a scheduled backup fails, and quota.exceeded when a write or embedding is refused by a collection quota, the disk reserve or the vector RAM limit. In 2.18.10, source.synced fires when a run of a synced source (a cron rule's sync) finishes.
collection	string	Collection filter (empty = all collections)

DeleteWebhookRequest #

Type: object

Property	Type	Description
id (required)	string	Webhook ID to delete

SetSchemaRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
schema (required)	string	The collection's metadata schema as a JSON string (not an object): required lists keys every document must carry, and properties gives each key a type (string, number, integer or boolean) and optional rules such as enum, pattern, minItems, maxItems. See docs/SCHEMA-VALIDATION.md.

SchemaResponse #

Type: object

Property	Type	Description
collection	string	Collection name
schema	string	JSON Schema string
enabled	boolean	Whether schema validation is enabled for this collection

ValidateRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
meta (required)	object	Metadata to validate against the collection schema

ValidateResponse #

Type: object

Property	Type	Description
valid	boolean	Whether the metadata is valid according to the schema
errors	array of string	Validation error messages (empty if valid)
warnings	array of string	Advisory findings that do not make the document invalid. Today: metadata values that look like a structure lost on the way in — Go's %v rendering of a map or a list of maps. A warning rather than an error, because such a value is a valid string and rejecting it would break callers legitimately storing text that looks like it.

ReplicationStatusResponse #

Type: object

Property	Type	Description
node_id	string	Unique node identifier
role	string	Replication role of this node One of "standalone", "leader", "follower".
current_lsn	integer (uint64)	Current Log Sequence Number
binlog_oldest_lsn	integer (uint64)	Oldest LSN still in the binlog (leader only)
binlog_size_bytes	integer (int64)	Binlog file size in bytes (leader only)
leader_addr	string	Address of the leader node (follower only)
replication_lag_ms	integer (int64)	Replication lag in milliseconds (follower only)
healthy	boolean	Whether this node is healthy
followers	array of FollowerInfo	Connected followers (leader only)
uptime_seconds	integer (int64)	Node uptime in seconds

FollowerInfo #

Type: object

Property	Type	Description
follower_id	string	Follower node identifier
address	string	Follower network address
confirmed_lsn	integer (uint64)	Last LSN confirmed by this follower
lag_ms	integer (int64)	Estimated replication lag in milliseconds
last_seen_at	integer (int64)	Unix timestamp of last communication
status	string	Follower health status (healthy: <1s lag, warning: 1-30s, unhealthy: >30s) One of "healthy", "warning", "unhealthy".

HybridSearchRequest #

Type: object

Property	Type	Description
includeImages	boolean	(v2.18.9, RAG-010) Attach each hit's image documents — those whose meta.parent is the hit's key — as images, with alt text, caption and page. Without it nothing is looked up and the response is unchanged.
format	string	passages returns path + lines + enclosing definition + text per hit instead of documents (AGT-002, v2.18.8); the response is a PassagesResponse. One of "results", "passages".
passageLines	integer	Lines of context on each side of a hit (default 10); a hit inside a shorter definition returns the definition. Minimum 0. Maximum 200.
readLevel	string	indexedPlusPending also returns documents whose embedding is still queued, found by their text and marked pendingEmbedding (vector search; hybrid search already includes them). GO-042. One of "indexed", "indexedPlusPending".
waitForIndex	integer	Wait up to this many ms for queued embeddings before searching; running out of time is not an error (indexing.timedOut). Minimum 0. Maximum 30000.
waitForKeys	array of string	With waitForIndex, wait only for these document keys.
groupBy	GroupBy
oversample	number	(v2.12.0+) Recall/latency knob: candidates fetched per requested result before deduplication, merging or rescoring trims them. Omitted, uses the collection's retrieval profile then MDDB's default of 3.0. Out of range returns 422 rather than clamping. See SEARCH.md#oversampling-v2120 for measured effect. Minimum 1. Maximum 10.
collection (required)	string	Collection name to search
query (required)	string	Search query string (used for both FTS and embedding)
topK	integer	Number of top results to return (default 10) Default 10.
algorithm	string	FTS algorithm (default "bm25") One of "bm25", "bm25f", "pmisparse". Default "bm25".
vectorAlgorithm	string	Vector search algorithm (default "flat", or the collection profile's retrieval.vectorAlgorithm). auto (v2.18.9+) lets the query planner choose; the response's vectorAlgorithm then names the index it chose. One of "flat", "auto", "hnsw", "ivf", "pq", "opq", "sq", "sq4", "bq". Default "flat".
explain	PlanExplain
latencyTargetMs	PlanLatencyTarget
positive	FeedbackExamples
negative	FeedbackExamples
feedbackMode	FeedbackMode
feedbackWeight	FeedbackWeight
rocchio	RocchioWeights
queryDecomposition	QueryDecompositionMode
signals	FusionSignals
strategy	string	Fusion strategy (default "alpha"). - alpha: Weighted blending — combined = (1-alpha) * normalizedFTS + alpha * vectorScore - rrf: Reciprocal Rank Fusion — score = 1/(k + rank_fts) + 1/(k + rank_vector) - weighted (SRCH-002): alpha's blend, then adjusted by the signals in signals. Nothing changes unless a weight is set, and alpha/rrf are unaffected. One of "alpha", "rrf", "weighted". Default "alpha".
alpha	number (float)	Alpha blending weight: 0 = keyword only, 1 = semantic only. Used by the "alpha" and "weighted" strategies. Omit the field to take the collection's retrieval profile, or 0.5. An explicit 0 means pure keyword search and is honoured as such (SRCH-007) — it used to be indistinguishable from an omitted field and was silently replaced with 0.5, the opposite of the request. Default 0.5. Minimum 0. Maximum 1.
rrfK	integer	RRF parameter k (default 60). Only used with "rrf" strategy. Default 60.
fuzzy	integer	Typo tolerance for FTS (0=off, 1=1 edit, 2=2 edits) One of 0, 1, 2. Default 0.
threshold	number (float)	Minimum vector similarity score (0.0 to 1.0) Minimum 0. Maximum 1.
filterMeta	object	Metadata filters applied to both FTS and vector results
filter	MetaFilter
geo	object	Optional spatial pre-filter. When set, only documents present in the in-memory geo index AND within radiusMeters of the given point are considered by both FTS and vector search; each result then carries a distanceMeters value. Required when sort is distance.
geo.lat (required)	number (double)	Latitude of the center point
geo.lng (required)	number (double)	Longitude of the center point
geo.radiusMeters (required)	number (double)	Search radius in meters
includeContent	boolean	Include document content in results Default false.
fieldWeights	object	Field weights for BM25F (keys are "title", "meta", "content")
bm25K1	number	(v2.18.8, SRCH-018) BM25 term-frequency saturation of the full-text half; default the collection profile, then 1.2. bm25 and bm25f only. Minimum 0. Maximum 3.
bm25B	number	(v2.18.8, SRCH-018) BM25 length normalisation of the full-text half; 0 ignores length. Default the collection profile, then 0.75. Minimum 0. Maximum 1.
disableStem	boolean	Disable stemming for FTS Default false.
disableSynonyms	boolean	Disable synonym expansion for FTS Default false.
lang	string	Language for FTS query tokenization and stemming (e.g. "en", "pl", "de")
distanceMetric	string	Distance metric for similarity computation One of "cosine", "dot_product", "euclidean". Default "cosine".
boost	object	Per-query boost map applied to the fused combined score (not raw FTS/vector sub-scores). Keys follow the format "metaKey:metaValue"; positive values multiply the score of matching documents, negative values demote. See the same field on FTSSearchRequest for full semantics.
sort	string	Result ordering. combined (default) ranks by the fused score — keyword relevance and semantic similarity blended per strategy. distance re-sorts the post-merge result set by distanceMeters ascending so the nearest documents surface first. Requires a geo filter on the request; otherwise the server rejects the call because distances would all be zero. One of "combined", "distance". Default "combined".
facetBy	array of string	(v2.9.15+) Metadata keys to aggregate into facets on the response
facetMaxValues	integer	(v2.9.15+) Cap per-key bucket count; 0 = unlimited

HybridSearchResponse #

Type: object

Property	Type	Description
limit	LimitUsed
limitCapped	LimitCapped
imageHits	array of ImageRef	(v2.18.9, RAG-010) With includeImages and a provider that embeds images: the images whose picture matches the query, scored in the image space and kept apart from results.
plan	SearchPlan
indexing	IndexWaitResult
results (required)	array of HybridSearchResultItem
total	integer	Number of results returned
strategy	string	Fusion strategy used
alpha	number	Alpha value used (only for alpha strategy)
rrfK	integer	RRF k value used (only for rrf strategy)
ftsAlgorithm	string	FTS algorithm used
vectorAlgorithm	string	Vector algorithm used
distanceMetric	string	Distance metric used for this search
searchStats	SearchStats
facets	FacetMap
signals	FusionSignals
signalBreakdown	array of SignalBreakdown	(SRCH-002) The weighted strategy only; one entry per result, in the order of results.

HybridSearchResultItem #

Type: object

Property	Type	Description
images	array of ImageRef	(v2.18.9, RAG-010) The document's images, with includeImages.
pendingEmbedding	boolean	The document's embedding is still queued; it was found by its text (GO-042).
group	string	Group this result counted against (only with groupBy, SRCH-016).
groupRank	integer	1-based place of this result within its group (only with groupBy).
document	Document
combinedScore	number (float)	Fused score from both FTS and vector
ftsScore	number (float)	Normalized FTS score component
vectorScore	number (float)	Vector similarity score component
matchedTerms	array of string	FTS matched terms
rank	integer	Result rank (1-based)
pinned	boolean	(v2.9.15+) Injected by a curation rule Default false.

PinnedDoc #

Type: object

Property	Type	Description
key (required)	string
lang	string
position (required)	integer	1-based; <=0 appends after organic results

CurationRule #

(v2.9.15+) Pinned + hidden document overrides for FTS/Hybrid search

Type: object

Property	Type	Description
id	string	Server-assigned. Omit on POST.
collection (required)	string
query (required)	string
matchMode	string	One of "exact", "contains". Default "exact".
pins	array of PinnedDoc
hides	array of string	Document keys to drop from results
enabled	boolean
createdAt	integer (int64)
updatedAt	integer (int64)

SearchRecommendation #

How to search a collection, measured rather than guessed (SRCH-010).

MDDB offers eight vector algorithms, four ranking algorithms, three fusion strategies and four retrieval modes. An agent connecting over MCP has no basis for choosing among them. This measures the collection — length, vocabulary, whether it is embedded, whether it is code — and recommends, with a reason for every choice.

It changes nothing. retrievalProfile is the advice encoded as a RAG-001 profile, ready to PUT to /v1/collection-config if you agree.

Type: object

Property	Type	Description
profile	CollectionProfile
searchType	string	One of "fts", "vector", "hybrid".
ftsAlgorithm	string	One of "tfidf", "bm25", "bm25f", "pmisparse".
vectorAlgorithm	string	One of "flat", "hnsw", "ivf", "pq", "opq", "sq", "sq4", "bq".
hybridStrategy	string	One of "alpha", "rrf", "weighted".
hybridAlpha	number
retrievalMode	string	One of "parent", "chunk", "window", "graph".
topK	integer
summaryMode	string	(v2.18.9+, RAG-009) blend when at least half the sampled documents carry a summary; absent otherwise. One of "blend".
signals	FusionSignals
reasons	array of string	One line per decision, in plain language. The part worth reading: a recommendation nobody can argue with is one nobody should follow.
warnings	array of string	What would stop the recommendation working — a half-embedded collection, a missing provider.
retrievalProfile	RetrievalProfile
measured	EvalResult

WhereRequest #

Type: object

Property	Type	Description
collection (required)	string
filter	MetaFilter
filterMeta	object
limit	integer	Default 1000. Maximum 10000.
cursor	string
dryRun	boolean
meta	object	updateWhere only; merged into each document's metadata
ttl	integer	setTTLWhere only; seconds from now, 0 removes the expiry

WhereResult #

Type: object

Property	Type	Description
matched	integer
affected	integer
sample	array of string
nextCursor	string
dryRun	boolean
errors	array of string

Alias #

Type: object

Property	Type	Description
alias	string
collection	string

GainCounters #

Type: object

Property	Type	Description
searches	object	Searches by type (fts, vector, hybrid, cross).
algorithms	object
fusion	object
tokensReturned	integer
tokensAvoided	integer
fragmentHits	integer
documentHits	integer

GainReport #

Type: object

Property	Type	Description
windowDays	integer
from	string (date)
to	string (date)
totals	GainCounters
totalSearches	integer
tokensWithoutRetrieval	integer	tokensReturned + tokensAvoided — the same hits as whole documents.
savedPercent	number
daily	array of allOf GainCounters & object

EvalQuery #

One evaluation query and the documents that should answer it (SRCH-019).

Type: object

Property	Type	Description
id	string
query (required)	string
expectedKeys (required)	array of string
grades	object	Key to relevance 0..3 for nDCG; an ungraded expected key counts 1.

EvalConfig #

Type: object

Property	Type	Description
name	string
searchType (required)	string	One of "fts", "vector", "hybrid".
algorithm	string	FTS algorithm (tfidf, bm25, bm25f, pmisparse)
vectorAlgorithm	string
alpha	number
strategy	string	Hybrid fusion, alpha or rrf
retrievalMode	string
bm25K1	number	BM25 parameters to try (SRCH-018)
bm25B	number
summaryMode	string	(v2.18.9+, RAG-009) Measure summaries; unset = the collection profile's. One of "off", "blend", "expand".
queryDecomposition	QueryDecompositionMode

EvalRequest #

Type: object

Property	Type	Description
collection (required)	string
k	integer	Default 10. Maximum 100.
configs	array of EvalConfig	Default fts/bm25, hybrid and vector.
queries	array of EvalQuery	Inline queries used instead of the stored set.
details	boolean	Add per-query results.

EvalResult #

Type: object

Property	Type	Description
collection	string
k	integer
queries	integer
results	array of object
results[].config	string
results[].recallAtK	number
results[].ndcgAtK	number
results[].mrr	number
results[].p50Ms	number
results[].p99Ms	number
results[].tokens	integer
results[].error	string
results[].perQuery	array of object
results[].perQuery[].id	string
results[].perQuery[].query	string
results[].perQuery[].recall	number
results[].perQuery[].ndcg	number
results[].perQuery[].reciprocalRank	number
results[].perQuery[].returned	array of string

CollectionProfile #

What the advisor measured, from a sample of up to 2000 documents.

Type: object

Property	Type	Description
collection	string
documents	integer
sampled	integer	How many were actually read. A recommendation from a sample should say so.
embeddedDocuments	integer
vectorDimensions	integer
medianWords	integer	Median, not mean — one long manual among ten thousand notes moves a mean and describes nothing.
longDocumentRatio	number	Share above 500 words, where returning whole documents starts wasting a prompt.
distinctTerms	integer
termsPerDocument	number	Vocabulary divided by documents sampled — how much new vocabulary each document contributes. This decides whether keyword search can discriminate. Type-token ratio would not: pooled over a corpus it falls towards zero as the corpus grows, so every large collection would look repetitive.
typeTokenRatio	number	Reported because it is familiar; not used for any decision.
codeDocuments	integer	How many carry extracted symbols, which is what makes the connection graph useful.
estimatedVectorBytes	integer (int64)
semantic	boolean	Whether the collection's vectors encode meaning (v2.18.9+); absent when nothing is embedded. False for the lexical provider, and the advisor then recommends keyword search unless the collection's own evaluation set measures hybrid better.
builtIndexes	array of string	(v2.18.9+, SRCH-013) Vector indexes that can answer for the collection now, without building. With more than one, the advisor puts vectorAlgorithm auto in the recommended profile.
summaryDocuments	integer	(v2.18.9+, RAG-009) Sampled documents that carry a client-written summary.
summaryRatio	number	(v2.18.9+, RAG-009) Their share of the sample, 0-1.
convertedDocuments	integer	(v2.18.9+, GO-046) Sampled documents converted from a file, carrying meta.conversionConfidence.
lowConfidenceDocuments	integer	(v2.18.9+, GO-046) Sampled documents whose conversionConfidence is below 0.5. When there are any, the advisor warns and names the filter that lists them.
lowConfidenceRatio	number	(v2.18.9+, GO-046) Their share of the sample, 0-1.

FusionSignals #

Ranking signals for the weighted hybrid strategy (SRCH-002).

A weight is a fraction of the result's own score: proximity: 0.1 means "up to 10% better", diversity: 0.8 means "up to 80% worse". That keeps the signals scale-free, and makes large weights genuinely powerful — at 1.0 a proximity bonus can carry a result past one scoring half again as much. Weights are clamped to [0, 1].

Every weight defaults to 0, so a weighted request with no signals behaves exactly like alpha.

Type: object

Property	Type	Description
diversity	number	Penalise a result that is a near-copy of a higher-ranked one, measured by text overlap. A vector score cannot do this: near-copies have near-identical embeddings, so similarity rewards the duplication. Suggested range 0.5-1.0. Minimum 0. Maximum 1.
diversityThreshold	number	Overlap below which two documents count as unrelated. Default 0.5. Minimum 0. Maximum 1.
proximity	number	Reward a result whose key shares a directory with a higher-ranked one. Suggested range 0.05-0.15. Minimum 0. Maximum 1.
freshness	number	Reward recently updated documents on an exponential decay. Off by default because it is wrong for reference material — an API specification does not become less true with age. Suggested range 0.05-0.2. Minimum 0. Maximum 1.
freshnessHalfLifeDays	number	How long the freshness bonus takes to halve. Default 180.

SignalBreakdown #

What each signal contributed to one result, in the same order as results. Returned by the weighted strategy, because a reranking nobody can explain is a reranking nobody trusts.

Type: object

Property	Type	Description
base	number	The score before any signal applied
diversity	number	Negative — the near-duplicate penalty
proximity	number
freshness	number
final	number

PersistenceStatus #

What the data directory can promise about durability (GO-032). Reported by /health so an operator sees whether acknowledged writes will survive, not only that the process is up.

Type: object

Property	Type	Description
path	string	The data directory the server writes to
filesystem	string	Detected filesystem type, when it could be determined
ephemeral	boolean	True when the directory lives on storage that does not survive a container restart (tmpfs, overlayfs upper layer).
writable	boolean
freeBytes	integer (int64)	Free space on the filesystem holding the data directory
warnings	array of object
warnings[].code	string
warnings[].detail	string

ErrorResponse #

What bad(), unprocessable(), the auth middleware and the access gate write: {"error": ""}. Some refusals add fields (a quota refusal is QuotaExceeded; a write refused while the freelist is rebuilt adds phase and progress).

Type: object

Property	Type	Description
error (required)	string	Error message

RateLimitError #

The API rate limiter's refusal (MDDB_RATE_LIMIT_ENABLED=true).

Type: object

Property	Type	Description
error (required)	string
retryAfter (required)	integer	Seconds until the client's window resets (also in Retry-After)

JSONRPCError #

A JSON-RPC 2.0 error, as the MCP listener's key auth, OAuth and rate limiter write it.

Type: object

Property	Type	Description
jsonrpc (required)	string	One of "2.0".
error (required)	object
error.code (required)	integer	-32001 (API key required or invalid, authorization required), -32429 (rate limit)
error.message (required)	string

GraphQLResponse #

A GraphQL response (gqlgen); a request it refuses carries errors and no data.

Type: object

Property	Type	Description
data	object | null
errors	array of object
errors[].message (required)	string
errors[].path	array of string
errors[].extensions	object

UploadResponse #

Type: object

Property	Type	Description
key	string	Document key
format	string	Detected file format (md, txt, html, pdf, docx, odt, rtf, xlsx, ods, csv, tsv, pptx, odp, epub, eml, mbox, yaml, tex, log, lex)
converted	boolean	Whether the file was converted to markdown
document	Document
conversionConfidence	number (double)	(v2.18.9+, GO-046) How well the file converted, by heuristics: the share of replacement and non-printable characters, PDF pages without text, the ratio of text to file size, empty sheets. A scan without a text layer scores 0. Absent for Markdown and text, which are not converted. Also stored as meta.conversionConfidence. Minimum 0. Maximum 1.
conversionWarnings	array of string	(v2.18.9+) What lowered the confidence. Also stored as meta.conversionWarnings.
parts	array of UploadResponse	(v2.18.9+) Further documents the file held: each message of a mailbox, each convertible attachment of an email. Keyed below the file's key (inbox/message-1, mail/attachments/q3.csv), with meta.parent naming the document that held them.

UploadBatchResponse #

Type: object

Property	Type	Description
added	integer
updated	integer
failed	integer
errors	array of string
results	array of UploadResponse

SynonymRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
term (required)	string	Base term for the synonym group
synonyms (required)	array of string	List of synonyms for the term

SynonymDeleteRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
term (required)	string	Term whose synonyms to delete

SynonymEntry #

Type: object

Property	Type	Description
term	string	Base term
synonyms	array of string	List of synonyms

SynonymListResponse #

Type: object

Property	Type	Description
collection	string	Collection name
entries	array of SynonymEntry
total	integer	Total number of synonym entries

EmbeddingConfig #

Type: object

Property	Type	Description
id (required)	string	Unique identifier
name (required)	string	Display name
provider (required)	string	Embedding provider. lexical (v2.18.9+) needs no key or URL; its vectors are hashed words and n-grams and do not encode meaning, model is ignored and dimensions is clamped to 256–2048. One of "openai", "ollama", "cohere", "voyage", "lexical".
model (required)	string	Model name
dimensions (required)	integer	Embedding vector dimensions
apiKey	string	API key (for OpenAI, Cohere, Voyage)
apiUrl	string	API URL (for Ollama or custom endpoints)
isDefault	boolean	Whether this is the default configuration
createdAt	integer (int64)	Creation timestamp (Unix seconds)

SystemInfoResponse #

Type: object

Property	Type	Description
hostname	string	Server hostname
os	string	Operating system
arch	string	CPU architecture
numCPU	integer	Number of logical CPUs
goVersion	string	Go runtime version
version	string	MDDB server version
uptimeSeconds	integer (int64)	Server uptime in seconds
memoryTotal	integer (uint64)	Total allocated memory in bytes (cumulative)
memoryUsed	integer (uint64)	Currently allocated memory in bytes
memorySystem	integer (uint64)	System memory obtained from OS in bytes
memoryHeap	integer (uint64)	Heap memory in use in bytes
numGoroutines	integer	Number of active goroutines
cpuUsagePercent	number (float)	CPU usage percentage (0-100)
network	array of NetworkInterface

NetworkInterface #

Type: object

Property	Type	Description
name	string	Interface name
addresses	array of string	IP addresses assigned to this interface
flags	string	Interface flags

ConfigResponse #

Type: object

Property	Type	Description
version	string	MDDB server version
databasePath	string	Path to the database file
mode	string	Server mode
panelMode	string	Panel mode (internal or external)
protocols	object
protocols.http	object
protocols.http.enabled	boolean
protocols.http.addr	string
protocols.grpc	object
protocols.grpc.enabled	boolean
protocols.grpc.addr	string
protocols.mcp	object
protocols.mcp.enabled	boolean
protocols.mcp.addr	string
protocols.mcp.stdio	boolean
protocols.mcp.revision	string	Newest MCP spec revision this server serves.
protocols.mcp.supportedRevisions	array of string	Every MCP spec revision this server serves, newest first.
protocols.mcp.revisionPinned	boolean	True when MDDB_MCP_PROTOCOL_VERSION fixes the revision and version negotiation is disabled.
protocols.mcp.handshakeRevision	string	Revision an initialize is answered with, absent when this server serves no handshake revision at all.
protocols.http3	object
protocols.http3.enabled	boolean
protocols.http3.addr	string
authEnabled	boolean	Whether authentication is enabled
metricsEnabled	boolean	Whether Prometheus metrics are enabled
searchStatsEnabled	boolean	Whether search statistics are included in search responses
esCompat	object	(v2.18.10) The Elasticsearch-compatible search subset (MDDB_ES_COMPAT)
esCompat.enabled	boolean
esCompat.prefix	string	Path the subset is served under
searchMaxLimit	integer	(v2.18.10) Most results one search returns (MDDB_SEARCH_MAX_LIMIT); a collection's maxTopK can only lower it
telemetry	object	(v2.18.10) OpenTelemetry trace export (MDDB_OTEL_ENDPOINT)
telemetry.enabled	boolean
telemetry.endpoint	string	The collector's scheme and host only: never a path, query or credentials. Omitted when off
clientAddressing	object	(v2.18.10) How the client address is found behind a proxy
clientAddressing.trustedProxies	integer	How many MDDB_TRUSTED_PROXIES entries are trusted; the addresses are never shown
clientAddressing.header	string	MDDB_CLIENT_IP_HEADER in canonical form
clientAddressing.proxyProtocol	boolean	MDDB_PROXY_PROTOCOL
replicationRole	string	Replication role of this node
vectorConfig	object	Vector search configuration (if enabled)
vectorConfig.enabled	boolean
vectorConfig.provider	string
vectorConfig.model	string
vectorConfig.dimensions	integer
vectorConfig.apiUrl	string
vectorConfig.semantic	boolean	Whether the vectors encode meaning (v2.18.9+). False only for the lexical provider, whose vectors are hashed words and character n-grams: vector search then matches shared spelling, not meaning.
vectorConfig.source	string	Where the configuration came from One of "environment", "stored", "autodetected".
chunkConfig	object	Document chunking configuration
chunkConfig.enabled	boolean
chunkConfig.chunkSize	integer

EndpointsResponse #

Type: object

Property	Type	Description
http	array of object
http[].method	string	HTTP method(s)
http[].path	string	URL path
http[].description	string	Endpoint description
http[].requiresAuth	boolean	Whether authentication is required
grpc	array of object
grpc[].name	string	gRPC method name
grpc[].description	string	Method description
mcp	array of object
mcp[].name	string	MCP tool name
mcp[].description	string	Tool description
mcp[].inputSchema	object	JSON Schema for the tool input

LoginRequest #

Type: object

Property	Type	Description
username (required)	string	Username
password (required)	string	Password

LoginResponse #

Type: object

Property	Type	Description
token	string	JWT token
expiresAt	integer (int64)	Token expiration timestamp (Unix seconds)

RegisterRequest #

Type: object

Property	Type	Description
username (required)	string	Username for the new user
password (required)	string	Password for the new user
tenant	string	Optional tenant namespace for the new user. A tenant user can only access collections named "/" and can never hold the global admin role. Omit for an unrestricted (global) user.

RegisterResponse #

Type: object

Property	Type	Description
username	string	Created username
tenant	string	Tenant namespace the user is confined to (empty for global users)
createdAt	integer (int64)	Account creation timestamp (Unix seconds)

CreateAPIKeyRequest #

Type: object

Property	Type	Description
description	string	Optional label for the API key
expiresAt	integer (int64)	Expiration timestamp (Unix seconds, 0 = never)

CreateAPIKeyResponse #

Type: object

Property	Type	Description
key	string	The API key value (shown only once)
description	string	API key description
expiresAt	integer (int64)	Expiration timestamp (Unix seconds, 0 = never)
createdAt	integer (int64)	Creation timestamp (Unix seconds)

ListAPIKeysResponse #

Type: object

Property	Type	Description
keys	array of object
keys[].keyHash	string	SHA256 hash of the API key (for deletion)
keys[].description	string	API key description
keys[].createdAt	integer (int64)	Creation timestamp (Unix seconds)
keys[].expiresAt	integer (int64)	Expiration timestamp (Unix seconds, 0 = never)

GetMeResponse #

Type: object

Property	Type	Description
username	string	Current user's username
admin	boolean	Whether the user has admin privileges
createdAt	integer (int64)	Account creation timestamp (Unix seconds)

Permission #

Type: object

Property	Type	Description
username	string	Username
collection	string	Collection name ("*" for all collections)
read	boolean	Read permission
write	boolean	Write permission
admin	boolean	Admin permission

SetPermissionRequest #

Type: object

Property	Type	Description
username (required)	string	Username
collection (required)	string	Collection name ("*" for all collections)
read	boolean	Read permission
write	boolean	Write permission
admin	boolean	Admin permission

SetPermissionResponse #

Type: object

Property	Type	Description
status	string

UsersListResponse #

Type: object

Property	Type	Description
users	array of object
users[].username	string	Username
users[].createdAt	integer (int64)	Account creation timestamp (Unix seconds)
users[].disabled	boolean	Whether the user is disabled
users[].admin	boolean	Whether the user has admin privileges
users[].groups	array of string	Groups the user belongs to

Group #

Type: object

Property	Type	Description
name	string	Group name
description	string	Group description
members	array of string	List of usernames in the group
createdAt	integer (int64)	Creation timestamp (Unix seconds)

CreateGroupRequest #

Type: object

Property	Type	Description
name (required)	string	Group name
description	string	Group description
members	array of string	Initial list of member usernames

UpdateGroupRequest #

Type: object

Property	Type	Description
description	string	Updated group description
members	array of string	Updated list of member usernames

GroupsListResponse #

Type: object

Property	Type	Description
groups	array of Group

GroupPermission #

Type: object

Property	Type	Description
groupName (required)	string	Group name
collection (required)	string	Collection name ("*" for all collections)
read	boolean	Read permission
write	boolean	Write permission
admin	boolean	Admin permission

AutomationRule #

Type: object

Property	Type	Description
id	string	Read-only.
type (required)	string	One of "webhook", "trigger", "cron".
name (required)	string
enabled	boolean	Default true.
createdAt	integer	Read-only.
updatedAt	integer	Read-only.
url	string	Webhook URL (type=webhook)
method	string	HTTP method (type=webhook) One of "POST", "GET", "PUT". Default "POST".
headers	object	Custom HTTP headers (type=webhook)
collection	string	Target collection (type=trigger)
searchType	string	Search type (type=trigger) One of "fts", "vector", "hybrid".
query	string	Search query (type=trigger)
threshold	number	Minimum score threshold 0-100 (type=trigger) Minimum 0. Maximum 100.
webhookId	string	Target webhook ID (type=trigger; type=cron unless backup or sync is set)
searchParams	object	Extra search parameters (type=trigger)
events	array of string	Events that fire the trigger (type=trigger, default ["insert","update"])
sentimentEnabled	boolean	Enable keyword-based sentiment condition (type=trigger)
sentimentMin	number	Minimum sentiment score -1.0 to 1.0 (type=trigger) Minimum -1. Maximum 1.
sentimentMax	number	Maximum sentiment score -1.0 to 1.0 (type=trigger) Minimum -1. Maximum 1.
conditionLogic	string	How to combine search + sentiment conditions (type=trigger) One of "and", "or". Default "and".
schedule	string	Cron expression, five fields or six with seconds first, e.g. "0 3 * * *" (type=cron). Refused if it does not parse.
triggerId	string	Target trigger ID (type=cron)
lastRun	integer	Last execution timestamp (type=cron) Read-only.
nextRun	integer	Next scheduled execution (type=cron) Read-only.
backup	BackupAction
sync	SyncAction
lastResult	AutomationRunResult

AutomationRunResult #

(2.18.11) What the latest run of a cron rule's sync or backup did — the newest automation log entry of the rule. Set on listings, never stored; absent before the first run.

Type: object

Read-only.

Property	Type	Description
at	integer	When the run started (unix seconds)
status	string	One of "success", "error", "skipped".
durationMs	integer
error	string
added	integer
updated	integer
unchanged	integer
deleted	integer
failed	integer

AutomationRun #

(2.18.11) A run POST /v1/automation/{id}/run started.

Type: object

Property	Type	Description
ruleId	string
action	string	One of "sync", "backup".
status	string	One of "started".
jobId	string	The run's id on the jobs SSE stream, e.g. sync--20261030T120000Z
startedAt	integer

SyncAction #

A cron rule's sync action (2.18.10), instead of webhookId or backup. Each run lists the source, fetches only what changed (ETag / Last-Modified, the object's ETag, else a sha256 of the content), converts it with the /v1/upload converters and writes it through the normal write path (schemas, quotas, read-only). Every HTTP request goes through the SSRF guard; robots.txt is honoured for a sitemap. Documents carry syncRule, syncSource, syncHash and, when sent, syncEtag / syncLastModified meta. A listing cut at maxDocuments or one that lists nothing prunes nothing. See docs/AUTOMATIONS.md#synced-sources.

Type: object

Property	Type	Description
source (required)	string	One of "sitemap", "urls", "s3".
collection (required)	string
lang (required)	string
url	string (uri)	sitemap — a sitemap or sitemap index, plain or gzipped
urls	array of string (uri)	urls — the pages
bucket	string	s3 — bucket (default storageConfig.bucket)
prefix	string	s3 — the objects under it are synced (default storageConfig.prefix)
storageConfig	StorageConfigDef
prune	boolean	Delete the documents whose source is gone (no longer listed, or answering 404/410) Default false.
maxDocuments	integer	Sources one run looks at; 0 takes the default Default 1000. Minimum 0. Maximum 50000.
maxBytes	integer (int64)	Bytes per fetched document; a larger one fails Default 10485760. Minimum 0. Maximum 1.048576e+08.

BackupAction #

A cron rule's backup action (2.18.9), instead of webhookId. Each run writes a verified backup, its .sha256 checksum file, stores it on the target and then deletes the oldest until keep remain. See docs/BACKUP.md#scheduled-backups.

Type: object

Property	Type	Description
target	string	One of "local", "s3". Default "local".
path	string	local — directory inside MDDB_BACKUP_DIR
bucket	string	s3 — bucket (default storageConfig.bucket)
prefix	string	Start of every backup's name or key; letters, digits, '.', '_', '-' and (s3 only) '/' Default "mddb-".
keep	integer	Backups kept on the target; 0 keeps all Default 0. Minimum 0.
collections	array of string	["*"] or the collections to back up (per-collection layout only) Default ["*"].
storageConfig	StorageConfigDef

TriggerMatch #

Type: object

Property	Type	Description
docId	string
collection	string
score	number

AutomationLogEntry #

Type: object

Property	Type	Description
id	string
timestamp	integer
ruleId	string
ruleName	string
ruleType	string	One of "trigger", "cron".
webhookId	string
webhookUrl	string
status	string	One of "success", "error", "skipped".
httpStatus	integer
durationMs	integer
error	string
attempt	integer
action	string	Set for a scheduled backup run (2.18.9) or a synced source's run (2.18.10) One of "backup", "sync".
target	string	Where the backup went — a path or s3://bucket/key; for a sync, its source (the sitemap, "N urls" or s3://bucket/prefix)
removed	array of string	Backups retention deleted after this one
sync	object	What a sync run did with its sources (2.18.10)
sync.added	integer
sync.updated	integer
sync.unchanged	integer
sync.deleted	integer
sync.failed	integer

SearchStats #

Statistics about a search execution

Type: object

Property	Type	Description
durationMs	integer	Search execution time in milliseconds
queryTerms	array of string	Tokenized query terms
indexSize	integer	Documents in search scope
totalTokens	integer	Number of tokens in query

RevisionEntry #

Type: object

Property	Type	Description
timestamp	integer (int64)	Unix timestamp of the revision
updatedAt	integer (int64)	Unix timestamp when the revision was saved
contentMd	string	Markdown content at this revision
meta	object	Metadata at this revision

RetrievalProfile #

(v2.12.0+) Per-collection retrieval defaults. Every field is optional; an unset field means "not configured". Precedence is fixed everywhere: an explicit request parameter wins, then this profile, then MDDB's own default for that endpoint — so a collection without a profile behaves exactly as it did before this existed.

Type: object

Property	Type	Description
format	string	passages returns path + lines + enclosing definition + text per hit instead of documents (AGT-002, v2.18.8); the response is a PassagesResponse. One of "results", "passages".
groupBy	GroupBy
vectorAlgorithm	string	(v2.18.9+, SRCH-013) The collection's default vector index for vector, hybrid and MCP searches that name none; auto lets the query planner choose per query. Unset = flat. One of "auto", "flat", "hnsw", "ivf", "pq", "opq", "sq", "sq4", "bq".
defaultSearchType	string	Which search this collection expects. Consumed by clients reading the config (mddb-chat, MCP agents); the server does not reroute a request to a different endpoint because of it. One of "fts", "vector", "hybrid".
topK	integer	Results per search. 0 = unset. Minimum 0. Maximum 1000.
retrievalMode	string	Granularity — whole document, matching passage, or passage with neighbours. One of "parent", "chunk", "window", "graph".
hybridStrategy	string	Hybrid fusion strategy. One of "alpha", "rrf", "weighted".
hybridAlpha	number	Keyword-to-semantic weight: 0 = keyword only, 1 = semantic only. Requires hybridAlphaSet, because 0.0 is a meaningful weight and cannot double as "unset". Minimum 0. Maximum 1.
hybridAlphaSet	boolean	Whether hybridAlpha was configured.
oversample	number	(SRCH-005) Default recall/latency knob for this collection: candidates fetched per requested result before deduplication, merging or rescoring. A request parameter overrides it. Minimum 1. Maximum 10.
maxTopK	integer	(v2.18.10, #368) Most results one search of this collection returns, whatever the request asks for. Lowers MDDB_SEARCH_MAX_LIMIT for this collection and never raises it; topK must not exceed it. 0 = unset. Minimum 0. Maximum 1e+06.
contextTokenBudget	integer	Cap on the total context a search returns, so a RAG caller cannot be handed more than its model holds. Results are dropped from the tail, never truncated mid-document — half a document still costs tokens and no longer says anything reliable. Approximated as bytes/4 rather than tokenised: a real tokeniser would tie the budget to one model family. Responses set contextTruncated when this applied. 0 = no cap. Minimum 0. Maximum 1e+06.
bm25K1	number	(v2.18.8, SRCH-018) The collection's BM25 k1; unset = 1.2. Minimum 0. Maximum 3.
bm25B	number	(v2.18.8, SRCH-018) The collection's BM25 b; unset = 0.75. Minimum 0. Maximum 1.
summaryMode	string	(v2.18.9+, RAG-009) What the documents' client-written summaries (metadata key summary; MDDB never writes one) do on vector and hybrid search, and on cross-collection search, where each target applies its own. off (default) ignores them; results are what they were before. blend scores a document by the better of its best chunk and its summary. expand blends and adds a summary hit's best chunks (up to 3, fewer under contextTokenBudget), one passage each with format passages. One of "off", "blend", "expand".
summaryWeight	number	(v2.18.9+, RAG-009) BM25F weight of the meta.summary field while summaryMode is not off. Unset = 2.0. Minimum 0. Maximum 10.

CodeConfig #

(v2.18.0+) Settings for collections of source code (#319).

Type: object

Property	Type	Description
includePaths	array of string	Collection-relative directories that C #include <...> resolves against, as a compiler's -I does. ["src"] makes <net/conn.h> in any file the document src/net/conn.h, which gives code_graph its include edges. Applied when a document is written.
role	string	(v2.18.8, AGT-003) "" for the project's own code, "reference" for code kept to learn from. Cross-search target "role:reference" selects every reference collection. One of "", "reference".

CollectionFTS #

(v2.18.2+) Full-text indexing for the collection (#335). With enabled=false no postings are written; fts-reindex removes existing ones and reports status "removed". The block is replaced as a whole.

Type: object

Property	Type	Description
enabled	boolean	Unset means on.
excludeMetaKeys	array of string	(v2.18.10+, #367) Meta keys kept out of full-text search: they get no meta. field postings, so changing them costs no full-text work. filterMeta and facets still work on them; they read the metadata index. Applies to documents written afterwards; after changing the list, run fts-reindex to apply it to documents already indexed.

EmbeddingChunking #

(v2.18.1+) This collection's chunking for embeddings (#325), overriding MDDB_EMBEDDING_CHUNK_SIZE and MDDB_EMBEDDING_CHUNK_MODE. Applies to documents embedded afterwards and to the passages search returns for them; existing vectors keep their chunks until a forced vector-reindex.

Type: object

Property	Type	Description
chunkSize	integer	Target chunk length in characters, 100-100000. 0 = the server's size. Minimum 0. Maximum 100000.
chunkMode	string	code splits at function and declaration boundaries, prose at paragraphs. Empty decides per document from its kind. One of "", "code", "prose".

CollectionConfig #

Type: object

Property	Type	Description
type	string	Collection type (e.g., default, website, images, audio, documents)
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
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 (defaults to query language)
encrypted	boolean	Encrypt documents and revisions of this collection at rest (AES-256-GCM; requires MDDB_ENCRYPTION_KEY on the server)
storageBackend	string	(Honoured from v2.12.0; accepted and ignored before that.) Where this collection's document bodies are stored. The metadata index, revisions, search indexes and replication binlog stay in the server's own database in every configuration — they are written in one transaction that a remote object store cannot join. A backend that cannot be reached is refused at configuration time, and writes to a collection whose backend fails later error rather than falling back to local disk. One of "boltdb", "memory", "s3".
storageConfig	StorageConfigDef
quantization	string	Vector quantization level. int8 = 4x compression, int4 = 8x compression. Default: float32. One of "float32", "int8", "int4".
maxRevisions	integer	(v2.9.15+) Revision retention cap per document. 0 (default) = unlimited. When > 0, older revisions are trimmed synchronously on every write so history stays capped even under high write-churn. Default 0.
retrieval	RetrievalProfile
responsePrompt	string	(v2.12.0+) How answers drawn from this collection should be formatted — numbered steps for runbooks, code blocks for API docs. Applied automatically by mddb-chat and returned alongside MCP search results, so the instruction travels with the data instead of living in every client. Supports and placeholders. Plain text for a model; never rendered as markup. Capped at 4 KiB because it is prepended to prompts automatically and would otherwise eat the context the answer needs. At most 4096 characters.
code	CodeConfig
embedding	EmbeddingChunking
fts	CollectionFTS
wordpress	WordPressTargetConfig
quota	CollectionQuota
evalSet	array of EvalQuery	Evaluation queries (SRCH-019). Changed only through /v1/eval-queries; a PUT keeps the stored set. Read-only.
readOnly	boolean	The collection refuses every write (AGT-005): REST answers 403 with code READ_ONLY, gRPC PERMISSION_DENIED. Set only by installing a corpus pack; a PUT keeps it. Read-only.
corpus	CorpusInfo

CorpusInfo #

The corpus pack a collection was installed from (AGT-005). See docs/CORPUS-PACKS.md.

Type: object

Read-only.

Property	Type	Description
name	string
version	string
license	string
mddbVersion	string
docCount	integer
sha256	string	sha256 of the pack's collection.db
installedAt	string (date-time)
vectorsDisabled	boolean	The pack's vectors were made by another embedding model than the server's: they are not loaded, and hybrid search on the collection answers from full text only.
embedding	CorpusEmbedding

CorpusEmbedding #

How a pack's vectors were made; null for a full-text-only pack.

Type: object \| null

Property	Type	Description
provider	string
model	string
dims	integer

CorpusSource #

Type: object

Property	Type	Description
repo (required)	string
commit	string
license (required)	string

CorpusBuildRequest #

Type: object

Property	Type	Description
collection (required)	string	The collection to pack; the pack installs under this name.
version	string
description	string
license (required)	string	Licence of the pack as a whole. Mandatory — pack only what may be redistributed.
sources	array of CorpusSource	Where the documents came from; each source needs a licence.

CorpusInstallResult #

Type: object

Property	Type	Description
name	string
version	string
license	string
docCount	integer
vectorsDisabled	boolean
warnings	array of string

WordPressTargetConfig #

(v2.11.0+) WordPress remote-publishing target used by the wordpress_publish / wordpress_set_status MCP tools. Points at a site running the mddb-sync plugin with "Remote publishing" enabled.

Type: object

Property	Type	Description
url (required)	string	Site base URL. Must be https:// (http only for localhost).
apiKey	string	mddb-sync publish key (Settings → MDDB Sync), sent as Authorization Bearer. (v2.12.0+) Write-only. Reads never return it — see apiKeySet. On write, an empty value keeps the stored key; remove the whole wordpress block to clear it. Write-only.
apiKeySet	boolean	(v2.12.0+) Read-only. true when a publish key is stored. Read-only.

StorageConfigDef #

Backend-specific configuration for non-default storage backends (required when storageBackend is 's3').

Type: object

Property	Type	Description
endpoint	string	S3-compatible endpoint URL
bucket	string	S3 bucket name
region	string	AWS region
accessKey	string	Access key for authentication
secretKey	string	(v2.12.0+) Write-only. Reads never return it — see secretKeySet. Reading a collection's configuration requires read permission on that collection, which is permission to read its documents, not to collect the credentials for the bucket underneath them. On write, an empty value keeps the stored secret, so the usual read-modify-write loop does not erase it. Send a new value to replace it; remove the whole storageConfig block to clear it. Write-only.
secretKeySet	boolean	(v2.12.0+) Read-only. true when a secret key is stored — so a blank secretKey field can be told apart from no credential at all. Read-only.
prefix	string	Key prefix within the bucket
useTLS	boolean	Use HTTPS for S3 connections

AggregateRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection name
filterMeta	object	Optional metadata pre-filter (AND over keys, OR over values)
filter	MetaFilter
facets	array of object
facets[].field (required)	string	Metadata key to aggregate
facets[].orderBy	string	Sort order for facet buckets (default count descending) One of "count", "value".
histograms	array of object
histograms[].field (required)	string	Time field to histogram (addedAt or updatedAt)
histograms[].interval	string	Histogram bucket interval (default month) One of "day", "week", "month", "year".
maxFacetSize	integer	Maximum number of values per facet (default 50)

AggregateResponse #

Type: object

Property	Type	Description
collection	string
totalDocs	integer	Total documents matching the filter (or all docs if no filter)
facets	object	Facet results keyed by metadata field name
histograms	object	Histogram results keyed by field name
durationMs	integer	Query execution time in milliseconds

CrossSearchRequest #

Type: object

Property	Type	Description
includeImages	boolean	(v2.18.9, RAG-010) Attach each hit's image documents — those whose meta.parent is the hit's key — as images, with alt text, caption and page. Without it nothing is looked up and the response is unchanged.
searchType	string	(v2.18.8, AGT-003) fts and hybrid run the single-collection search in each target and fuse the lists by reciprocal rank; they need a query. A target "role:reference" stands for every collection whose code.role is reference. One of "vector", "fts", "hybrid". Default "vector".
format	string	passages returns path + lines + enclosing definition + text per hit instead of documents (AGT-002, v2.18.8); the response is a PassagesResponse. One of "results", "passages".
passageLines	integer	Lines of context on each side of a hit (default 10); a hit inside a shorter definition returns the definition. Minimum 0. Maximum 200.
waitForIndex	integer	Wait up to this many ms for queued embeddings before searching; running out of time is not an error (indexing.timedOut). Minimum 0. Maximum 30000.
waitForKeys	array of string	With waitForIndex, wait only for these document keys.
groupBy	GroupBy
oversample	number	(v2.12.0+) Recall/latency knob: candidates fetched per requested result before deduplication, merging or rescoring trims them. Omitted, uses the collection's retrieval profile then MDDB's default of 3.0. Out of range returns 422 rather than clamping. See SEARCH.md#oversampling-v2120 for measured effect. Minimum 1. Maximum 10.
sourceCollection	string	Collection containing the source document (for document-as-query)
sourceDocID	string	ID of the source document whose embedding to use as query
query	string	Text query (alternative to sourceCollection/sourceDocID)
queryVector	array of number	Pre-computed query vector (alternative to query or source document)
targetCollections	array of string	Collections to search in
topK	integer	Number of results to return Default 10.
threshold	number	Minimum similarity score Default 0.
algorithm	string	Vector search algorithm. auto (v2.18.9+) plans each target collection on its own; the response then reports auto and, with explain, one plan per target under plan.collections. One of "flat", "auto", "hnsw", "ivf", "pq", "opq", "sq", "sq4", "bq". Default "flat".
explain	PlanExplain
latencyTargetMs	PlanLatencyTarget
positive	FeedbackExamples
negative	FeedbackExamples
feedbackMode	FeedbackMode
feedbackWeight	FeedbackWeight
rocchio	RocchioWeights
distanceMetric	string	Distance metric for similarity computation One of "cosine", "dot_product", "euclidean". Default "cosine".
filterMeta	object	Metadata filters applied to target documents
filter	MetaFilter
includeContent	boolean	Include document content in results Default false.

CrossSearchResponse #

Type: object

Property	Type	Description
limit	LimitUsed
limitCapped	LimitCapped
plan	SearchPlan
indexing	IndexWaitResult
results	array of CrossSearchResultItem
total	integer	Total number of results
sourceCollection	string	Source collection (if document-as-query was used)
sourceDocID	string	Source document ID (if document-as-query was used)
targetCollections	array of string	Collections that were searched
algorithm	string	Vector search algorithm used
distanceMetric	string	Distance metric used
searchStats	SearchStats

CrossSearchResultItem #

Type: object

Property	Type	Description
images	array of ImageRef	(v2.18.9, RAG-010) The document's images, with includeImages.
group	string	Group this result counted against (only with groupBy, SRCH-016).
groupRank	integer	1-based place of this result within its group (only with groupBy).
collection	string	Collection the result came from
document	Document
score	number (float)	Similarity score
rank	integer	Result rank (1-based)

FindDuplicatesRequest #

Type: object

Property	Type	Description
collection (required)	string	Collection to scan
mode	string	Detection mode. - exact: identical content hashes - similar: close embeddings — finds documents on the same topic, and needs an embedding provider configured - minhash: overlapping text (SRCH-002) — finds a page that was forked and lightly edited, which exact misses and similar cannot distinguish from two independent pages on one subject. Needs no embeddings. - both: exact and similar. Deliberately excludes minhash, which reads every document body. One of "exact", "similar", "minhash", "both". Default "both".
threshold	number	Similarity threshold for similar mode Default 0.9. Minimum 0. Maximum 1.
maxDocs	integer	Maximum documents to process (safety bound) Default 5000.
distanceMetric	string	One of "cosine", "dot_product", "euclidean". Default "cosine".
includeContent	boolean	Default false.

FindDuplicatesResponse #

Type: object

Property	Type	Description
collection	string
mode	string
threshold	number
distanceMetric	string
totalDocuments	integer
totalEmbedded	integer
exactGroups	array of DuplicateGroup
similarGroups	array of DuplicateGroup
exactDuplicates	integer
similarPairs	integer
searchStats	SearchStats

DuplicateGroup #

Type: object

Property	Type	Description
groupId	integer
type	string	One of "exact", "similar", "minhash".
documents	array of DuplicateDocInfo
score	number	Average similarity score for the group

DuplicateDocInfo #

Type: object

Property	Type	Description
docId	string
key	string
contentHash	string
contentMd	string
score	number	Max similarity to another document in the group