Classification — MDDB API

Zero-shot document classification #

POST /v1/classify

Classify a document or text against candidate labels using embedding similarity. Provide either a document reference (collection + key + lang) or raw text, plus an array of candidate labels. Returns labels ranked by cosine similarity to the document/text embedding. Requires an embedding provider to be configured.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
collection	string	Collection name (for document reference)
key	string	Document key (for document reference)
lang	string	Language code (for document reference, defaults to "en")
text	string	Raw text to classify (alternative to document reference)
labels (required)	array of string	Candidate labels to rank by similarity (max 100)
topK	integer	Return top K labels (0 = all, default is all)
multi	boolean	If true, return all labels above threshold
threshold	number	Minimum similarity score (default 0.0)

{
  "labels": [
    "programming",
    "cooking",
    "sports",
    "music"
  ],
  "text": "Go is a statically typed, compiled language designed at Google"
}

Responses #

Status	Description	Body
200	Classification results	object (application/json)
400	Missing labels, invalid request, or no embedding provider
404	Referenced document not found

200 example (application/json)

{
  "dimensions": 1536,
  "model": "text-embedding-3-small",
  "results": [
    {
      "label": "programming",
      "score": 0.87
    },
    {
      "label": "music",
      "score": 0.21
    },
    {
      "label": "sports",
      "score": 0.18
    },
    {
      "label": "cooking",
      "score": 0.12
    }
  ]
}