GraphQL — MDDB API

GraphQL API and interactive playground

GraphQL API endpoint #

POST /graphql

Execute GraphQL queries and mutations against the MDDB API. Requires MDDB_GRAPHQL_ENABLED=true environment variable.

Supports queries for documents, search, vector search, full-text search, and hybrid search. Supports mutations for adding, deleting, and managing documents.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
query (required)	string	GraphQL query or mutation string
variables	object	GraphQL variables
operationName	string	Name of the operation to execute (if query contains multiple)

{
  "operationName": "string",
  "query": "{ stats { totalDocuments } }"
}

Responses #

Status	Description	Body
200	GraphQL response	object (application/json)
400	The body is not JSON (gqlgen); the reason is in errors[0].message	GraphQLResponse (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)
413	The body is over MDDB_MAX_BODY_BYTES (32 MiB by default).	ErrorResponse (application/json)
422	The query does not parse or validate against the schema; errors name where	GraphQLResponse (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"
}

413 example (application/json)

{
  "error": "request body too large"
}

GraphQL Playground #

GET /playground

Interactive GraphQL Playground UI for exploring and testing the MDDB GraphQL API. Requires MDDB_GRAPHQL_ENABLED=true environment variable.

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	GraphQL Playground HTML page	string (text/html)
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"
}