API overview

Every endpoint in this reference follows the rules on this page. Read it once before the endpoint pages, or hand it to an agent with the OpenAPI spec.

Base URL and authentication

All calls go to https://api.mixpeek.com and carry an API key as a bearer token:

curl "https://api.mixpeek.com/v1/namespaces/list" -X POST \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json"

Create a key in Studio under Settings > API Keys. A missing, unknown, revoked or expired key returns 401. A key without the permission an operation needs returns 403; see API keys for permissions and scopes.

The `X-Namespace` header

Buckets, collections, retrievers, taxonomies, clusters and documents live inside a namespace. Calls on them need the namespace id in X-Namespace:

-H "X-Namespace: ns_abc123"

The header takes the id (ns_...) that POST /v1/namespaces returned, not the namespace name. Organization-level calls, such as storage connections, webhooks and API keys, take no X-Namespace. Each endpoint page lists the headers it needs.

Response envelopes

Call	The list is in	Also read
Retriever execution (`POST /v1/retrievers/{retriever_id}/execute`) and feature search	`documents`	`status` and `warnings`
List and search of resources (`POST /v1/collections/list`, `POST /v1/buckets/list` and so on)	`results`	`next_cursor`

A retriever run that times out or skips a stage still answers 200, with status: "degraded" and an entry in warnings. Check status before you treat a short documents list as “no matches”. A clean run returns status: "completed".

Errors

Every error has the same body:

{
  "success": false,
  "status": 404,
  "error": {
    "type": "NotFoundError",
    "message": "Namespace not found",
    "code": null,
    "details": { "resource": "namespace", "id": "ns_123" }
  }
}

Branch on error.type, and on error.code where an endpoint sets one, such as namespace_name_taken. message is for people and can change. A 429 carries Retry-After in seconds; see Rate limits and quotas.

Pagination

List endpoints return next_cursor. Send it back as cursor and stop when the response omits it. next_page and previous_page are always null. See Pagination.

Machine-readable docs

OpenAPI spec: https://api.mixpeek.com/docs/openapi.json, the spec the API serves now.
Docs index for agents: https://mixpeek.com/docs/llms.txt, and the full text at /docs/llms-full.txt.
Any docs page as Markdown: add .md to its URL, for example /docs/overview/quickstart.md.
MCP: connect an agent to the API directly with the MCP server.

Overview

Namespaces

Buckets

Collections

Feature Extractors

Documents

Retrievers

Enrich & Improve

Automate

Administer

Advanced

Base URL and authentication

The `X-Namespace` header

Response envelopes

Errors

Machine-readable docs

​Base URL and authentication

​The X-Namespace header

​Response envelopes

​Errors

​Pagination

​Machine-readable docs

Base URL and authentication

The `X-Namespace` header

Response envelopes

Errors

Pagination

Machine-readable docs