> ## 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.

# Operate

> Run Mixpeek in production — security, webhooks, manifests, and infrastructure

![Operations: authentication with API keys and namespaces, document ACL for row-level security, webhooks for event subscriptions, manifests for config-as-code](https://mintcdn.com/mixpeek/pDBzbsnRaRIThJZv/assets/mixpeek-operations.svg?fit=max\&auto=format\&n=pDBzbsnRaRIThJZv\&q=85\&s=31d24799fc6308a1ff120fc4b3f2bf88)

## Authentication

Every request requires a Bearer token and namespace header:

```
Authorization: Bearer mxp_sk_...
X-Namespace: ns_production
```

API keys are scoped to an organization. Namespaces provide the authorization boundary — use separate namespaces for dev, staging, and production.

See [API Keys](https://docs.mixpeek.com/docs/operations/api-keys.md) to create scoped keys, set permissions, rotate and revoke them, and monitor per-key usage.

## Secrets & LLM Keys

Store third-party API keys in an encrypted secrets vault. Secrets are encrypted at rest using Fernet symmetric encryption and are never exposed in API responses.

### Manage Secrets

```bash Create a Secret theme={null}
curl -X POST "https://api.mixpeek.com/v1/organizations/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_name": "openai_api_key",
    "secret_value": "sk-proj-abc123..."
  }'
```

```bash List Secrets theme={null}
# Returns secret names only — values are never exposed
curl "https://api.mixpeek.com/v1/organizations/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash Update a Secret theme={null}
curl -X PUT "https://api.mixpeek.com/v1/organizations/secrets/openai_api_key" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "secret_value": "sk-proj-new-key..." }'
```

```bash Delete a Secret theme={null}
curl -X DELETE "https://api.mixpeek.com/v1/organizations/secrets/openai_api_key" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Bring Your Own Key (BYOK)

Use your own LLM API keys instead of Mixpeek's default keys for cost control, higher rate limits, compliance, and independent key rotation.

**Supported providers:** OpenAI, Anthropic, Google

#### Apply a Key to All LLM Operations

Set a key as the **organization-wide default** and it automatically applies to every LLM operation — extractors, retrievers, clustering, taxonomy inference, and manifest generation — with no per-stage configuration.

**1. Store your key in the secrets vault**

```bash cURL theme={null}
curl -X POST "https://api.mixpeek.com/v1/organizations/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_name": "openai_api_key",
    "secret_value": "sk-proj-abc123..."
  }'
```

```python Python theme={null}
from mixpeek import Mixpeek

mx = Mixpeek(api_key="YOUR_API_KEY")
mx.organizations.secrets.create(
    secret_name="openai_api_key",
    secret_value="sk-proj-abc123..."
)
```

**2. Set it as the org-wide default for that provider**

```bash cURL theme={null}
curl -X PATCH "https://api.mixpeek.com/v1/organizations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_llm_credentials": {
      "openai": "openai_api_key"
    }
  }'
```

```python Python theme={null}
mx.organizations.update(
    default_llm_credentials={
        "openai": "openai_api_key"
    }
)
```

Configure defaults for multiple providers at once:

```json theme={null}
{
  "default_llm_credentials": {
    "openai": "my_openai_key",
    "anthropic": "my_anthropic_key",
    "google": "my_gemini_key"
  }
}
```

> [!TIP]
>
> In Studio, toggle **"Use as default LLM key"** when creating a secret to automatically apply it org-wide for the detected provider.

#### Override a Key on a Specific Stage

Set `api_key` directly on a retriever stage, extractor, or cluster config using `{{secrets.name}}` template syntax to override the org-wide default for that operation only:

```json theme={null}
{
  "parameters": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": "{{secrets.openai_api_key}}"
  }
}
```

#### Credential Resolution Order

1. **Per-resource** `api_key` / `{{secrets.name}}` — explicit key on a specific stage or extractor
2. **Organization default** — set once via `default_llm_credentials`, applied everywhere
3. **Mixpeek platform keys** — used when no custom key is configured (usage charged to your Mixpeek account)

> [!NOTE]
>
> Values in `default_llm_credentials` are **secret names**, not raw API keys. Keys are encrypted at rest, never returned in API responses, decrypted on-demand per LLM call, and isolated per organization with no cross-tenant leakage.

## Document Access Control

Apply row-level security to documents with ACL rules. Filter results by user roles or attributes at query time without changing retriever logic. User-scoped keys (`usr_sk_`) transparently filter every read so each end-user sees only their documents — no app-side filtering.

For the full model (the `_acl` object, key types, public documents, sharing), see **[Document-Level ACL](https://docs.mixpeek.com/docs/operations/document-acl.md)**. For external policy engines, see [Permissions (OpenFGA)](https://docs.mixpeek.com/docs/platform/permissions.md). Broader auth/tenancy: [Security & Tenancy](https://docs.mixpeek.com/docs/operations/security.md).

## Webhooks

Subscribe to events like `collection.documents.written`, `document.created`, or `alert.triggered`:

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/organizations/webhooks" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_name": "ingest-notify",
    "event_types": ["collection.documents.written", "documents.updated.batch"],
    "channels": [
      { "channel": "webhook", "configs": { "url": "https://example.com/webhook" } }
    ]
  }'
```

Webhooks are organization-scoped, so this route takes no `X-Namespace` header.

[Webhook API →](https://docs.mixpeek.com/docs/api-reference/webhooks/create-webhook.md) · [Full webhooks guide →](https://docs.mixpeek.com/docs/operations/webhooks.md)

## Manifests

Declare your entire namespace configuration as code — buckets, collections, retrievers, taxonomies — and apply it in one request:

```bash theme={null}
# Export current state
curl "https://api.mixpeek.com/v1/manifest/export" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID"

# Apply a manifest
curl -X POST "https://api.mixpeek.com/v1/manifest/apply" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d @manifest.json
```

Use `POST /v1/manifest/diff` to preview changes before applying.

[Manifest API →](https://docs.mixpeek.com/docs/api-reference/manifest/apply-manifest.md)

## Lineage & Audit Traces

Every document links back to its source, and every retriever execution produces an auditable trace.

### Document Lineage

Track how a document was created — which object it came from, which collection processed it, and what features were extracted:

```bash theme={null}
curl "https://api.mixpeek.com/v1/documents/$DOCUMENT_ID/lineage" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID"
```

Returns the full decomposition tree: source object → batch → extracted documents. Use this to trace any search result back to the original file.

```bash theme={null}
# Get all documents derived from a source object
curl "https://api.mixpeek.com/v1/objects/$OBJECT_ID/derived" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID"
```

[Lineage API →](https://docs.mixpeek.com/docs/api-reference/document-lineage/get-document-lineage.md)

### Retriever Execution Traces

Every retriever execution captures a full trace — which stages ran, what scores were produced, which documents were dropped and why:

```bash theme={null}
curl "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID"
```

A trace includes:

* Which retriever version and config were used
* Each stage's input parameters, output set, scores, and latency
* Which feature URIs and collections were consulted
* Which filters matched and which documents were eliminated
* The final result set with per-document provenance

Traces are replayable — if a model version or taxonomy changes, you can compare results against historical executions.

[Execution API →](https://docs.mixpeek.com/docs/api-reference/retrievers/get-execution.md) · [Explain API →](https://docs.mixpeek.com/docs/api-reference/retrievers/explain-retriever-execution-plan.md)

## Environment Branching

Clone namespaces to create isolated environments for testing:

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/namespaces/$NS_ID/clone" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "namespace_name": "staging-branch" }'
```

Branched namespaces share no state with the source — safe for experimentation.

[Clone API →](https://docs.mixpeek.com/docs/api-reference/namespace-clone/clone-namespace.md)


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