Operate - Mixpeek

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

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..."
  }'

# Returns secret names only — values are never exposed
curl "https://api.mixpeek.com/v1/organizations/secrets" \
  -H "Authorization: Bearer YOUR_API_KEY"

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..." }'

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.

Store your key in the secrets vault

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..."
  }'

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..."
)

Set it as the org-wide default for that provider

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"
    }
  }'

mx.organizations.update(
    default_llm_credentials={
        "openai": "openai_api_key"
    }
)

Configure defaults for multiple providers at once:

{
  "default_llm_credentials": {
    "openai": "my_openai_key",
    "anthropic": "my_anthropic_key",
    "google": "my_gemini_key"
  }
}

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:

{
  "parameters": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": "{{secrets.openai_api_key}}"
  }
}

Credential Resolution Order

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

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. For external policy engines, see Permissions (OpenFGA). Broader auth/tenancy: Security & Tenancy.

Webhooks

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

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 → · Full webhooks guide →

Manifests

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

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

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:

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.

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

Retriever Execution Traces

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

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 → · Explain API →

Environment Branching

Clone namespaces to create isolated environments for testing:

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 →

​Authentication

​Secrets & LLM Keys

​Manage Secrets

​Bring Your Own Key (BYOK)

​Apply a Key to All LLM Operations

​Override a Key on a Specific Stage

​Credential Resolution Order

​Document Access Control

​Webhooks

​Manifests

​Lineage & Audit Traces

​Document Lineage

​Retriever Execution Traces

​Environment Branching

Authentication

Secrets & LLM Keys

Manage Secrets

Bring Your Own Key (BYOK)

Apply a Key to All LLM Operations

Override a Key on a Specific Stage

Credential Resolution Order

Document Access Control

Webhooks

Manifests

Lineage & Audit Traces

Document Lineage

Retriever Execution Traces

Environment Branching