> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Base URL, authentication, the X-Namespace header, response envelopes, errors and pagination: what every Mixpeek API call has in common.

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](#machine-readable-docs).

## Base URL and authentication

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

```bash theme={null}
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](https://docs.mixpeek.com/docs/operations/api-keys.md) 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`:

```bash theme={null}
-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:

```json theme={null}
{
  "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](https://docs.mixpeek.com/docs/operations/rate-limits-quotas.md).

## 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](https://docs.mixpeek.com/docs/platform/pagination.md).

## Machine-readable docs

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.