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

<Frame>
  <img src="https://mintcdn.com/mixpeek/pDBzbsnRaRIThJZv/assets/mixpeek-operations.svg?fit=max&auto=format&n=pDBzbsnRaRIThJZv&q=85&s=31d24799fc6308a1ff120fc4b3f2bf88" alt="Operations: authentication with API keys and namespaces, document ACL for row-level security, webhooks for event subscriptions, manifests for config-as-code" width="900" height="280" data-path="assets/mixpeek-operations.svg" />
</Frame>

## 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](/operations/api-keys) 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

<CodeGroup>
  ```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"
  ```
</CodeGroup>

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

<Steps>
  <Step title="Store your key in the secrets vault">
    <CodeGroup>
      ```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..."
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Set it as the org-wide default for that provider">
    <CodeGroup>
      ```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"
          }
      )
      ```
    </CodeGroup>
  </Step>
</Steps>

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.
</Tip>

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

## 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](/operations/document-acl)**. For external policy engines, see [Permissions (OpenFGA)](/platform/permissions). Broader auth/tenancy: [Security & Tenancy](/operations/security).

## Webhooks

Subscribe to events like `batch.completed`, `document.created`, or `alert.triggered`:

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/webhooks" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_name": "batch-notify",
    "url": "https://example.com/webhook",
    "events": ["batch.completed", "batch.failed"]
  }'
```

[Webhook API →](/api-reference/webhooks/create-webhook) · [Full webhooks guide →](/operations/webhooks)

## 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 →](/api-reference/manifest/apply-manifest)

## 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 →](/api-reference/document-lineage/get-document-lineage)

### 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 →](/api-reference/retrievers/get-execution) · [Explain API →](/api-reference/retrievers/explain-retriever-execution-plan)

## 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 →](/api-reference/namespace-clone/clone-namespace)