Elasticsearch Compatibility — MDDB API
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.
Cluster info (client version negotiation) #
GET /es
What Elasticsearch.info() reads. version.number is the API level the
subset follows (8.19.0); tagline says it is MDDB. v2.18.10+, needs
MDDB_ES_COMPAT=true.
Authorization: BearerAuth or APIKeyAuth or none
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Cluster info | ESInfo (application/json) |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
429 |
The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body. | RateLimitError (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
Ping #
HEAD /es
Authorization: BearerAuth or APIKeyAuth or none
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The server is up | |
401 |
Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key. | ErrorResponse (application/json) |
429 |
The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body. | RateLimitError (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
Bulk (PUT, as elasticsearch-py sends it) #
PUT /es/_bulk
Authorization: BearerAuth or APIKeyAuth or none
Request body #
Required.
Content type application/x-ndjson: string
"string"
Responses #
| Status | Description | Body |
|---|---|---|
200 |
One item per operation, in order | ESBulkResponse (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
Bulk index, create and delete (NDJSON) #
POST /es/_bulk
Action lines index, create and delete with _index and _id;
any other action or action option refuses the whole request (400)
before anything is written. At most 10 000 operations, and the body is
bounded by MDDB_MAX_BODY_BYTES. Runs of writes go through the batch
path of /v1/add-batch. ?refresh=true|wait_for waits for the
written collections' embeddings.
Authorization: BearerAuth or APIKeyAuth or none
Request body #
Required.
Content type application/x-ndjson: string
"string"
Responses #
| Status | Description | Body |
|---|---|---|
200 |
One item per operation, in order | ESBulkResponse (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
Does the collection exist #
HEAD /es/{index}
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The collection has a configuration or a document | |
404 |
No such collection |
Search (GET with a body) #
GET /es/{index}/_search
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Hits, totals and aggregations | ESSearchResponse (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
Search (Query DSL subset) #
POST /es/{index}/_search
query (match, match_phrase, multi_match, term, terms, range, bool,
match_all), top-level knn, size, from, sort, _source,
highlight and aggs (terms) are translated onto /v1/fts,
/v1/vector-search (algorithm auto), /v1/hybrid-search (rrf) or the
metadata listing. Anything else is a 400 naming the clause. from+size
is capped by MDDB_SEARCH_MAX_LIMIT / retrieval.maxTopK: a capped page
carries X-Limit-Capped, X-Limit, a Warning header and
limitCapped/limit in the body.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Request body #
Content type application/json: ESSearchRequest
{
"from": 0,
"knn": {
"field": "string",
"k": 0,
"num_candidates": 0,
"query_vector": [
0
],
"query_vector_builder": {
"text_embedding": {
"model_text": "string"
}
}
},
"size": 10
}
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Hits, totals and aggregations | ESSearchResponse (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
Count every document #
GET /es/{index}/_count
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The count | object (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (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) |
503 |
Not now: the search concurrency limit is reached, the subsystem is disabled, or a write meets the database while its freelist is rebuilt (#333; the body then adds phase and progress). Retry after Retry-After seconds. | ErrorResponse (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
403 example (application/json)
{
"error": "forbidden"
}
Count the documents a query matches #
POST /es/{index}/_count
The body may hold query only.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
The count | object (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
Wait until recent writes are searchable #
POST /es/{index}/_refresh
Waits up to 30 s for the collection's queued embeddings; _shards.successful is 0 when the wait ran out.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Refreshed | |
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"
}
Bulk with a default collection #
POST /es/{index}/_bulk
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Request body #
Required.
Content type application/x-ndjson: string
"string"
Responses #
| Status | Description | Body |
|---|---|---|
200 |
One item per operation, in order | ESBulkResponse (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
403 |
No write permission on the collection in the URL |
Index a document under a generated _id #
POST /es/{index}/_doc
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
Request body #
Required.
_source: content (body), lang, and metadata fields (strings, numbers, booleans or lists of them).
Content type application/json: object
Responses #
| Status | Description | Body |
|---|---|---|
201 |
Created | ESWriteResult (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
Get a document #
GET /es/{index}/_doc/{id}
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
id (required) |
path | string |
The document key. |
lang |
query | string |
The document language when _source has none (default en). Default "en". |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
found: true and _source | |
404 |
found: false |
Index (create or replace) a document #
PUT /es/{index}/_doc/{id}
content is the body, lang the language, every other top-level field
metadata. Goes through the single write path: schemas (400), quotas
(507/429), read-only collections (403 cluster_block_exception).
?op_type=create refuses an existing document (409).
if_seq_no, if_primary_term, version, version_type, pipeline
and routing are refused.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
id (required) |
path | string |
The document key. |
lang |
query | string |
The document language when _source has none (default en). Default "en". |
Request body #
Required.
_source: content (body), lang, and metadata fields (strings, numbers, booleans or lists of them).
Content type application/json: object
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Updated | ESWriteResult (application/json) |
201 |
Created | ESWriteResult (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (application/json) |
403 |
No write permission, or a read-only collection | |
507 |
Collection quota reached |
Index a document (POST) #
POST /es/{index}/_doc/{id}
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
id (required) |
path | string |
The document key. |
lang |
query | string |
The document language when _source has none (default en). Default "en". |
Request body #
Required.
_source: content (body), lang, and metadata fields (strings, numbers, booleans or lists of them).
Content type application/json: object
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Updated | ESWriteResult (application/json) |
201 |
Created | ESWriteResult (application/json) |
400 |
An unsupported or malformed clause, named in error.reason | ESError (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 |
No write permission ({"error":"forbidden"}), read-only mode, or a read-only collection (an Elasticsearch-shaped cluster_block_exception) | |
409 |
op_type=create and the document exists (version_conflict_engine_exception) | ESError (application/json) |
413 |
The body is over MDDB_MAX_BODY_BYTES (32 MiB by default). | 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) |
507 |
Collection quota reached (quota_exceeded_exception) | ESError (application/json) |
401 example (application/json)
{
"error": "missing authentication"
}
413 example (application/json)
{
"error": "request body too large"
}
Delete a document #
DELETE /es/{index}/_doc/{id}
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
id (required) |
path | string |
The document key. |
lang |
query | string |
The document language when _source has none (default en). Default "en". |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Deleted | ESWriteResult (application/json) |
404 |
result: not_found |
Does the document exist #
HEAD /es/{index}/_doc/{id}
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
id (required) |
path | string |
The document key. |
lang |
query | string |
The document language when _source has none (default en). Default "en". |
Responses #
| Status | Description | Body |
|---|---|---|
200 |
Exists | |
404 |
Does not exist |
Create a document, 409 if it exists #
PUT /es/{index}/_create/{id}
The existence check runs before the write, not inside its transaction.
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
id (required) |
path | string |
The document key. |
lang |
query | string |
The document language when _source has none (default en). Default "en". |
Request body #
Required.
_source: content (body), lang, and metadata fields (strings, numbers, booleans or lists of them).
Content type application/json: object
Responses #
| Status | Description | Body |
|---|---|---|
201 |
Created | ESWriteResult (application/json) |
409 |
The document exists |
Create a document (POST) #
POST /es/{index}/_create/{id}
Authorization: BearerAuth or APIKeyAuth or none
Parameters #
| Name | In | Type | Description |
|---|---|---|---|
index (required) |
path | string |
The collection (an alias resolves to its collection). |
id (required) |
path | string |
The document key. |
lang |
query | string |
The document language when _source has none (default en). Default "en". |
Request body #
Required.
_source: content (body), lang, and metadata fields (strings, numbers, booleans or lists of them).
Content type application/json: object
Responses #
| Status | Description | Body |
|---|---|---|
201 |
Created | ESWriteResult (application/json) |
409 |
The document exists |