Health — MDDB API

Health check and monitoring endpoints

Health check #

GET /health

Simple health check endpoint that verifies database connectivity

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	Service is healthy	object (application/json)
503	Not serving yet, or not healthy. warming_up: the server is still starting; phase names the step, elapsedSeconds how long it has run, and progress (when the step can measure it) has the same fields as above. stalled (v2.18.5+): a read transaction has waited at least MDDB_HEALTH_STALL_LIMIT; the body is the 200 body with this status. unhealthy: the database could not be read; error says why.	object (application/json)

Health check (versioned) #

GET /v1/health

Alias for /health endpoint

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	Service is healthy	object (application/json)
503	Service is unhealthy	ErrorResponse (application/json)

(v2.18.2+) Bytes per bucket and per collection, and free space #

GET /v1/storage

Attributes every key and value to its bucket and collection (#335). Without collection it reads the whole file, in read transactions of at most 10,000 keys or 50 ms each (v2.18.5+, #350), so writes are not held back; on a large database the call still takes minutes. With it, only that collection's keys are read and buckets is omitted. A tenant user sees only the tenant's collections, and collection naming another tenant's collection answers 403 (v2.18.6+).

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
collection	query	string

Responses #

Status	Description	Body
200	Storage breakdown	object (application/json)
403	collection belongs to another tenant (v2.18.6+)	ErrorResponse (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"
}

Server statistics #

GET /v1/stats

Get detailed server and database statistics

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	Statistics retrieved successfully	Stats (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"
}