Skip to main content
Namespaces are Mixpeek’s primary isolation boundary. Every request runs inside a namespace, ensuring that objects, collections, retrievers, taxonomies, caches, and Ray jobs cannot bleed into other tenants or environments.

​
Dual ID System

  • Organization / API Key – Authentication boundary; API responses surface organization_id.
  • Namespace (namespace_id) – Authorization boundary; passed through the X-Namespace header.
  • Internally, MongoDB documents also reference internal_id (organization key) for indexing.
Authorization: Bearer sk_live_...
X-Namespace: ns_production

​
Create a Namespace

curl -sS -X POST "$MP_API_URL/v1/namespaces" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_name": "production",
    "description": "Live tenant data",
    "feature_extractors": [
      { "feature_extractor_name": "text_extractor", "version": "v1" },
      { "feature_extractor_name": "clip_vit_l_14", "version": "v1" }
    ],
    "payload_indexes": [
      { "field_name": "metadata.category", "type": "keyword" },
      { "field_name": "metadata.published_at", "type": "datetime" }
    ]
  }'
Response fields include:
  • namespace_id and namespace_name
  • feature_extractors registered for this namespace
  • payload_indexes applied to Qdrant collections
  • document_count (if collections already exist)
List namespaces with filtering, search, and pagination: POST /v1/namespaces/list.

​
Isolation Guarantees

  • All MongoDB collections include a namespace_id index (e.g., collections, retrievers, taxonomies).
  • Qdrant creates a single HNSW-backed collection per namespace (ns_<namespace_id>); payload filters keep collection boundaries intact.
  • Redis cache keys are prefixed with namespace_id.
  • Ray jobs, tasks, and webhook events embed the namespace so pollers never cross boundaries.
  • API requests missing X-Namespace are rejected once multitenancy is enabled.

​
Namespace Templates

Bootstrapping a namespace can be automated with templates: 
POST /v1/namespaces
{
  "name": "Video Search Demo",
  "template": "video_search",
  "template_config": {
    "scene_detection": true,
    "include_taxonomy": "faces_v1"
  }
}
Templates provision buckets, collections, retrievers, feature extractors, taxonomies, and sample data in a single request. Explore available templates in api/namespaces/templates/.

​
Migrations

Namespaces carry a schema_version. The API upgrades namespaces automatically on startup or via explicit migration requests: 
curl -sS -X POST "$MP_API_URL/v1/namespaces/<namespace_id>/migrate" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_version": "v3", "dry_run": false }'
  • Migration scripts live in api/namespaces/migrations/.
  • Rollback scripts are optional but recommended for major changes.

​
Best Practices

  1. One namespace per environment (dev, staging, prod). Use templates to keep them aligned.
  2. Pass X-Namespace everywhere including webhooks and retriever requests.
  3. Grant least-privilege access by issuing API keys scoped to specific namespaces when possible.
  4. Segment analytics by namespace using the Analytics endpoints (/v1/analytics/...) to understand tenant-specific performance.
  5. Monitor document counts with GET /v1/namespaces/{id} to track growth and adjust Qdrant shard planning.
Namespaces give you cloud-scale tenancy without rewriting your queries—just add X-Namespace and Mixpeek handles the isolation across storage, cache, and compute.