Vector Search — MDDB API

Semantic/vector search operations

Semantic vector search #

POST /v1/vector-search

Search documents by semantic similarity using vector embeddings.

Provide either a query string (which will be embedded automatically using the configured provider) or a raw queryVector array of floats.

Results are ranked by cosine similarity score. Use threshold to filter out low-relevance results. Use filterMeta to narrow results by metadata before ranking.

Use algorithm to select the search strategy: flat (exact), hnsw (fast approximate), ivf (clustered), or one of the quantized indexes pq/opq/sq/sq4/bq (compressed, smallest first). See Search Algorithms for details.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: VectorSearchRequest

{
  "algorithm": "flat",
  "collection": "blog",
  "distanceMetric": "cosine",
  "explain": false,
  "feedbackMode": "query",
  "feedbackWeight": 0.5,
  "filter": {
    "kind": {
      "not": [
        "test"
      ]
    },
    "modified": {
      "gte": "2026-09-01"
    },
    "path": {
      "prefix": "internal/"
    },
    "size": {
      "lt": 10000
    },
    "summary": {
      "exists": true
    },
    "title": {
      "contains": "hnsw"
    }
  },
  "filterMeta": {
    "category": [
      "devops",
      "tutorial"
    ]
  },
  "format": "results",
  "graphExpand": {
    "graphDecay": 0.5,
    "graphDepth": 1,
    "graphDirection": "both",
    "graphKinds": [
      "callers"
    ],
    "graphMaxNeighbours": 10
  },
  "groupBy": {
    "key": "path",
    "perGroup": 1
  },
  "includeContent": false,
  "includeImages": false,
  "latencyTargetMs": 0,
  "mmr": true,
  "mmrLambda": 0.5,
  "negative": [
    "string"
  ],
  "oversample": 0,
  "passageLines": 0,
  "positive": [
    "string"
  ],
  "query": "How to set up a CI/CD pipeline?",
  "queryDecomposition": "off",
  "queryImage": "string",
  "queryVector": [
    0
  ],
  "readLevel": "indexed",
  "retrievalMode": "chunk",
  "rocchio": {
    "alpha": 1,
    "beta": 0.75,
    "gamma": 0.25
  },
  "threshold": 0.7,
  "topK": 5,
  "waitForIndex": 0,
  "waitForKeys": [
    "string"
  ],
  "windowSize": 1
}

Responses #

Status	Description	Body
200	Vector search results	oneOf VectorSearchResponse | PassagesResponse (application/json)
400	Invalid request	ErrorResponse (application/json)
503	Vector index is still loading	ErrorResponse (application/json)

Project embeddings to 2D (PCA) #

POST /v1/vector-projection

Server-side PCA projection of a collection's embedding vectors to 2D for visual exploration (cluster structure, outliers, query diagnostics). Large collections are sampled deterministically; a text query or raw vector can be projected alongside the points.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
collection (required)	string	Collection to project
sample	integer	Maximum points to project (default 1000, capped at 2000) Default 1000.
query	string	Optional text query to embed and overlay on the projection
queryVector	array of number (float)	Optional pre-computed query vector to overlay

{
  "collection": "kb",
  "query": "string",
  "queryVector": [
    0
  ],
  "sample": 1000
}

Responses #

Status	Description	Body
200	Projected points	object (application/json)
400	Invalid request	ErrorResponse (application/json)

Reindex collection embeddings #

POST /v1/vector-reindex

Trigger re-embedding of all documents in a collection. This is a write-protected endpoint.

Use force: true to re-embed all documents even if their content has not changed since the last embedding.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: VectorReindexRequest

{
  "async": false,
  "collection": "blog",
  "force": false
}

Responses #

Status	Description	Body
200	Reindex completed	VectorReindexResponse (application/json)
429	(v2.18.9+) The collection has spent today's embedding budget; retry after Retry-After seconds (GO-043)	QuotaExceeded (application/json)
400	Invalid request	ErrorResponse (application/json)
202	(v2.18.4+) With async true, the job started; Location points at it
409	(v2.18.4+) A reindex of this collection is already running; the body holds it
403	Read-only mode	ErrorResponse (application/json)

(v2.18.4+) Recent reindex jobs, newest first #

GET /v1/vector-reindex/jobs

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	Jobs
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

(v2.18.4+) A reindex job's progress and result #

GET /v1/vector-reindex/jobs/{id}

status is running, completed or failed; done, percent and etaSeconds give the progress; result holds total, embedded, skipped, failed, totalChunks and errors. Jobs are kept in memory, the last 50.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string

Responses #

Status	Description	Body
200	The job
404	No such job (a restart forgets jobs)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Vector search statistics #

GET /v1/vector-stats

Get the current status of the vector search subsystem, including provider info, index readiness, and per-collection embedding counts. A tenant user sees only the tenant's collections (v2.18.6+).

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	Vector stats retrieved successfully	VectorStatsResponse (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}