MDDB API

MDDB (Markdown Database) is a high-performance, version-controlled markdown database with triple protocol support.

Features #

  • Store and manage markdown documents with metadata
  • Full revision history for all documents
  • Multi-language support
  • Fast metadata-based search
  • Vector search with embedding providers (OpenAI, Cohere, Voyage AI, Ollama)
  • Full-text search with TF-IDF, BM25, BM25F, PMISparse scoring, 7 search modes (simple, boolean, phrase, wildcard, proximity, range, fuzzy), and multi-language stemming (18 languages)
  • Hybrid search combining FTS + vector search with alpha blending or RRF fusion
  • Webhooks for real-time event notifications
  • TTL (time-to-live) support for automatic document expiration
  • JSON Schema validation for document metadata
  • URL import with YAML frontmatter parsing
  • Authentication - JWT tokens and API keys
  • Authorization - Collection-level RBAC (Read/Write/Admin)
  • Memory RAG - Conversational memory system with session management, message storage, semantic/hybrid recall, and summarization
  • User Management - Multi-user with admin roles
  • Group Permissions - Organize users into groups
  • Template variable substitution
  • Export capabilities (NDJSON, ZIP)
  • Backup and restore operations
  • Replication - Leader-follower replication with binlog streaming
  • Automation - Webhooks, triggers (FTS/vector/hybrid + sentiment), crons
  • Automation Logs - Execution history with configurable TTL retention

Protocols #

  • HTTP/JSON - Port 11023 (documented here)
  • gRPC/Protobuf - Port 11024 (see gRPC documentation)
  • GraphQL - Port 11023/graphql (enable with MDDB_GRAPHQL_ENABLED=true)
  • MCP - Port 9000 (Streamable HTTP at /mcp, legacy SSE at /sse)
  • HTTP/3 + QUIC - Port 11443 (extreme mode only)

Per-Protocol Access Modes #

Each protocol can have its own read/write mode: MDDB_API_MODE, MDDB_GRPC_MODE, MDDB_MCP_MODE, MDDB_HTTP3_MODE. Values: read, write, wr. Default: inherits from MDDB_MODE. Set MDDB_MCP_BUILTIN_TOOLS=false to hide built-in MCP tools, or MDDB_MCP_TOOLSETS=search,code to expose only some groups of them.

Authentication #

MDDB supports JWT tokens and API keys for authentication with collection-level RBAC authorization.

JWT Authentication #

# Login to get JWT token
curl -X POST http://localhost:11023/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}'

# Use token in requests
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:11023/v1/stats

API Key Authentication #

# Create API key (requires JWT first)
curl -X POST http://localhost:11023/v1/auth/api-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"My API key"}'

# Use API key in requests
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:11023/v1/stats

See authentication endpoints below for user management, groups, and permissions.

Version 2.18.11 · OpenAPI 3.0.3

Servers #

  • {scheme}://{host}:{port} — MDDB HTTP API listener (default http://localhost:11023)
    • {host} default localhost — The server's host name or address
    • {port} default 11023 — The HTTP listener's port (http.addr, MDDB_ADDR)
    • {scheme} default http (one of http, https)

Authentication #

  • BearerAuth — HTTP bearer token — JWT. JWT token obtained from POST /v1/auth/login
  • APIKeyAuth — API key in the header X-API-Key. API key obtained from POST /v1/auth/api-key

Endpoints #

Health — Health check and monitoring endpoints

Method Path Summary
GET /health Health check
GET /v1/health Health check (versioned)
GET /v1/storage (v2.18.2+) Bytes per bucket and per collection, and free space
GET /v1/stats Server statistics

Authentication — User authentication with JWT tokens and API keys

Method Path Summary
POST /v1/auth/login Login
POST /v1/auth/api-key Create API key
GET /v1/auth/api-keys List API keys
DELETE /v1/auth/api-keys/{keyHash} Delete API key
POST /v1/auth/me Get current user info

Users — User management (admin only)

Method Path Summary
POST /v1/auth/register Register new user
GET /v1/auth/permissions Get user permissions
POST /v1/auth/permissions Set user permissions
GET /v1/auth/users List all users
DELETE /v1/auth/users/{username} Delete user

Groups — Group management and permissions (admin only)

Method Path Summary
GET /v1/auth/groups List all groups
POST /v1/auth/groups Create group
GET /v1/auth/groups/{name} Get group details
PUT /v1/auth/groups/{name} Update group
DELETE /v1/auth/groups/{name} Delete group
GET /v1/auth/group-permissions Get group permissions
POST /v1/auth/group-permissions Set group permission

Embedding Config — Embedding provider configuration management

Method Path Summary
GET /v1/embedding-configs List embedding configurations
POST /v1/embedding-configs Create embedding configuration
GET /v1/embedding-configs/{id} Get embedding configuration
PUT /v1/embedding-configs/{id} Update embedding configuration
DELETE /v1/embedding-configs/{id} Delete embedding configuration
POST /v1/embedding-configs/set-default Set default embedding configuration

Documents — Document management operations

Method Path Summary
POST /v1/add Add or update document
POST /v1/add-batch Batch add documents
POST /v1/bulk-ingest-job Submit async bulk ingest job
GET /v1/bulk-ingest-job/{id} Get bulk ingest job status
DELETE /v1/bulk-ingest-job/{id} Cancel pending bulk ingest job
GET /v1/bulk-ingest-jobs List bulk ingest jobs
POST /v1/ingest Bulk ingest documents
POST /v1/upload Upload files with auto-conversion to Markdown
POST /v1/get Get document
POST /v1/delete Delete document
POST /v1/delete-batch Batch delete documents
POST /v1/delete-collection Delete collection
PATCH /v1/update Partial document update
GET /v1/doc-meta Get document metadata only
GET /v1/image An image document's bytes
POST /v1/documents:deleteWhere Delete every document a metadata filter matches
POST /v1/documents:updateWhere Merge metadata into every document a filter matches
POST /v1/documents:setTTLWhere Set the time to live of every document a filter matches

Search — Search and query operations

Method Path Summary
POST /v1/search Search documents
GET /v1/code-languages Extension to language table for source files
GET /v1/symbol Where a symbol is defined, used, called and tested
POST /v1/symbol Symbol lookup (JSON body)
GET /v1/code-graph Code connection graph for one document
POST /v1/code-graph Code connection graph for one document (JSON body)
GET /v1/meta-keys List metadata keys and values for a collection
GET /v1/indexing-status Is what was just written searchable yet?
GET /v1/gain What retrieval saved over a window of days
POST /v1/eval Measure retrieval on an evaluation set
GET /v1/eval-queries List a collection's evaluation set
POST /v1/eval-queries Add a query to the evaluation set
DELETE /v1/eval-queries Remove a query from the evaluation set
GET /v1/search-advisor How should I search this collection?
POST /v1/search-advisor How should I search this collection? (body form)

Vector Search — Semantic/vector search operations

Method Path Summary
POST /v1/vector-search Semantic vector search
POST /v1/vector-projection Project embeddings to 2D (PCA)
POST /v1/vector-reindex Reindex collection embeddings
GET /v1/vector-reindex/jobs (v2.18.4+) Recent reindex jobs, newest first
GET /v1/vector-reindex/jobs/{id} (v2.18.4+) A reindex job's progress and result
GET /v1/vector-stats Vector search statistics

Full-Text Search — Keyword-based full-text search

Method Path Summary
POST /v1/fts Full-text search
POST /v1/fts-reindex Reindex FTS for a collection
GET /v1/autocomplete Prefix autocomplete
GET /v1/fts-languages List supported FTS languages

Hybrid Search — Combined sparse (FTS) + dense (vector) search with fusion strategies

Method Path Summary
POST /v1/hybrid-search Hybrid sparse+dense search

Import — Document import from URLs

Method Path Summary
POST /v1/import-url Import document from URL
POST /v1/import-wiki Import Wikipedia XML dump

TTL — Document time-to-live management

Method Path Summary
POST /v1/set-ttl Set document TTL

Webhooks — Webhook registration and management

Method Path Summary
GET /v1/webhooks List webhooks
POST /v1/webhooks Register webhook
POST /v1/webhooks/delete Delete webhook

Schema Validation — JSON Schema validation for metadata

Method Path Summary
POST /v1/schema/set Set collection schema
POST /v1/schema/get Get collection schema
POST /v1/schema/delete Delete collection schema
POST /v1/schema/list List all schemas
POST /v1/validate Validate metadata against schema

Export — Export and backup operations

Method Path Summary
POST /v1/export Export documents
GET /v1/backup Create backup
POST /v1/restore Restore from backup

Maintenance — Database maintenance operations

Method Path Summary
POST /v1/truncate Truncate revision history

Telemetry — Prometheus-compatible metrics endpoint

Method Path Summary
GET /metrics Prometheus metrics
GET /v1/admin/diagnose Diagnose bundle without user data (admin-only)

Replication — Leader-follower replication status and monitoring

Method Path Summary
GET /v1/replication/status Replication status

Synonyms — FTS synonym dictionary management

Method Path Summary
GET /v1/synonyms List synonyms
POST /v1/synonyms Add or update synonym group
DELETE /v1/synonyms Delete synonym group

Curation — (v2.9.15+) Editorial overrides for FTS + Hybrid search — pin documents to fixed positions, hide others for specific queries

Method Path Summary
GET /v1/curation List or fetch curation rules (v2.9.15+)
PUT /v1/curation Replace an existing curation rule (v2.9.15+)
POST /v1/curation Create a curation rule (v2.9.15+)
DELETE /v1/curation Delete a curation rule (v2.9.15+)

System — System information and endpoint discovery

Method Path Summary
GET /v1/system/info System information
GET /v1/endpoints List all endpoints

MCP — Model Context Protocol 2026-07-28 and 2025-11-25 served side by side — Streamable HTTP transport, tools, resources, prompts, completion, logging, discovery

Method Path Summary
GET /v1/mcp/keys List MCP API keys
POST /v1/mcp/keys Create MCP API key
DELETE /v1/mcp/keys Delete MCP API key
POST /v1/mcp/keys/disable Disable MCP API key
GET /.well-known/oauth-protected-resource (v2.18.1+) OAuth protected-resource metadata, RFC 9728 (MCP listener)
GET /.well-known/oauth-authorization-server (v2.18.1+) OAuth authorization-server metadata, RFC 8414 (MCP listener)
POST /oauth/register (v2.18.1+) Dynamic client registration, RFC 7591 (MCP listener)
GET /oauth/authorize (v2.18.1+) Authorization endpoint — consent page (MCP listener)
POST /oauth/token (v2.18.1+) Token endpoint (MCP listener)
GET /mcp MCP SSE stream for server-initiated messages (handshake clients)
POST /mcp MCP Streamable HTTP endpoint (2026-07-28 + 2025-11-25)
DELETE /mcp Terminate MCP session

Memory RAG — Conversational memory system for RAG — session management, message storage, semantic/hybrid recall, summarization

Method Path Summary
POST /v1/memory/session Create a new memory session
POST /v1/memory/message Add a message to a session
POST /v1/memory/recall Recall relevant messages
POST /v1/memory/summarize Summarize a session
POST /v1/memory/sessions List memory sessions
POST /v1/memory/history Get session message history

Configuration — Server and MCP configuration

Method Path Summary
GET /v1/config Server configuration
GET /v1/mcp/config MCP YAML configuration

GraphQL — GraphQL API and interactive playground

Method Path Summary
POST /graphql GraphQL API endpoint
GET /playground GraphQL Playground

Automation — Triggers, crons, and webhook targets for automated workflows

Method Path Summary
GET /v1/automation List automation rules
POST /v1/automation Create automation rule
GET /v1/automation/{id} Get automation rule
PUT /v1/automation/{id} Update automation rule
DELETE /v1/automation/{id} Delete automation rule
POST /v1/automation/{id}/run Run a sync or backup rule now
POST /v1/automation/{id}/test Test trigger (dry run)
GET /v1/automation-logs List automation execution logs

Revisions — Document revision history and restore operations

Method Path Summary
POST /v1/revisions List document revision history
POST /v1/revisions/restore Restore a document to a previous revision

Collection Config — Per-collection type, description, icon, color, and custom metadata

Method Path Summary
GET /v1/aliases List collection aliases
PUT /v1/aliases/{alias} Create an alias or move it to another collection
DELETE /v1/aliases/{alias} Remove an alias (the collection stays)
GET /v1/collection-config Get collection configuration
PUT /v1/collection-config Set collection configuration
DELETE /v1/collection-config Delete collection configuration
GET /v1/collection-configs List all collection configurations
GET /v1/corpus List installed corpus packs
POST /v1/corpus/build Build a corpus pack of a collection
POST /v1/corpus/install Install a corpus pack
POST /v1/corpus/remove Remove an installed corpus pack

Cross-Collection Search — Search across multiple collections using embeddings or text queries

Method Path Summary
POST /v1/cross-search Cross-collection vector search

Temporal Tracking — Document event history, hot-docs leaderboard and activity histograms (requires MDDB_TEMPORAL=true)

Method Path Summary
POST /v1/temporal/query Query document event history
POST /v1/temporal/hot Hot documents leaderboard
POST /v1/temporal/histogram Event frequency histogram

Spell Correction — SymSpell-based FTS spell suggestions, text cleanup, and per-collection custom dictionaries (requires MDDB_SPELL=true)

Method Path Summary
POST /v1/spell-suggest Spell correction suggestions
POST /v1/spell-cleanup Apply spell corrections to text
GET /v1/spell-dictionary List custom dictionary words
PUT /v1/spell-dictionary Add words to custom dictionary
DELETE /v1/spell-dictionary Remove words from custom dictionary

Elasticsearch Compatibility — A subset of the Elasticsearch REST API under /es, translated onto MDDB's own search and write paths (requires MDDB_ES_COMPAT=true; v2.18.10+). See ELASTICSEARCH-COMPAT.md.

Method Path Summary
GET /es Cluster info (client version negotiation)
HEAD /es Ping
PUT /es/_bulk Bulk (PUT, as elasticsearch-py sends it)
POST /es/_bulk Bulk index, create and delete (NDJSON)
HEAD /es/{index} Does the collection exist
GET /es/{index}/_search Search (GET with a body)
POST /es/{index}/_search Search (Query DSL subset)
GET /es/{index}/_count Count every document
POST /es/{index}/_count Count the documents a query matches
POST /es/{index}/_refresh Wait until recent writes are searchable
POST /es/{index}/_bulk Bulk with a default collection
POST /es/{index}/_doc Index a document under a generated _id
GET /es/{index}/_doc/{id} Get a document
PUT /es/{index}/_doc/{id} Index (create or replace) a document
POST /es/{index}/_doc/{id} Index a document (POST)
DELETE /es/{index}/_doc/{id} Delete a document
HEAD /es/{index}/_doc/{id} Does the document exist
PUT /es/{index}/_create/{id} Create a document, 409 if it exists
POST /es/{index}/_create/{id} Create a document (POST)

Geo Search

Method Path Summary
POST /v1/geo-search Radius search (R-tree or geohash)
POST /v1/geo-within Bounding-box search
POST /v1/geo-polygon Find documents inside a GeoJSON polygon or multi-polygon
POST /v1/geo-reindex Force-rebuild geo indexes
GET /v1/geo-stats Geo index statistics
POST /v1/geo-encode Encode (lat, lng) → geohash string
POST /v1/geo-decode Decode geohash → centroid + bbox

Stop Words

Method Path Summary
GET /v1/stopwords List stop words
POST /v1/stopwords Add custom stop words
DELETE /v1/stopwords Delete custom stop words

Collections

Method Path Summary
GET /v1/checksum Get collection checksum

Classification

Method Path Summary
POST /v1/classify Zero-shot document classification

Real-Time

Method Path Summary
GET /v1/events Server-Sent Events stream

Audit

Method Path Summary
GET /v1/audit Query audit-log events (admin-only)
GET /v1/audit/exporters Per-sink audit export delivery counters (2.9.16+)

Encryption

Method Path Summary
GET /v1/encryption/status At-rest encryption posture (2.9.16+)
POST /v1/encryption/rotate Start a re-encryption job (2.9.16+)
GET /v1/encryption/jobs List rotation jobs (2.9.16+)
GET /v1/encryption/jobs/{id} Get a single key-rotation job

Compliance

Method Path Summary
GET /v1/compliance-status Report the live state of the ISO 27001 / SOC 2 production guard

Aggregations

Method Path Summary
POST /v1/aggregate Aggregate metadata facets and date histograms

Duplicate Detection

Method Path Summary
POST /v1/find-duplicates Find duplicate and similar documents

Data types: Schemas.