Namespaces are isolation boundaries. They scope buckets, objects, collections, documents, and searches so organizations can separate environments and tenants. Most API calls accept the X-Namespace header to operate within a namespace.

​
Overview

  • Isolation: Buckets, Objects, Collections, Documents, Tasks live within a namespace.
  • Required header: Pass X-Namespace on most resource calls (see API reference pages for specifics).
  • Indexes: Selected feature extractors add required vector/payload index definitions; you may also add custom payload indexes.
  • Immutability: Feature extractor choices set capabilities; payload indexes are mutable.

​
Namespace model

Minimum fields when creating a namespace. See Create Namespace. 
{
  "namespace_name": "spotify_playlists_dev",
  "description": "This namespace contains playlists from Spotify",
  "feature_extractors": [
    {"feature_extractor_name": "video_extractor", "version": "1.0.0"}
  ],
  "payload_indexes": [
    {
      "field_name": "metadata.title",
      "type": "text",
      "field_schema": {"type": "text", "tokenizer": "word", "min_token_len": 2, "max_token_len": 15, "lowercase": true}
    }
  ]
}
  • feature_extractors (required): Enables associated features; required indexes are added automatically.
  • payload_indexes (optional): Additional payload indexes for common filters/sorts.

​
Create a namespace

  • API: Create Namespace
  • Method: POST
  • Path: /v1/namespaces
  • Reference: API Reference
curl -X POST https://api.mixpeek.com/v1/namespaces \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_name": "spotify_playlists_dev",
    "description": "This namespace contains playlists from Spotify",
    "feature_extractors": [
      {"feature_extractor_name": "video_extractor", "version": "1.0.0"}
    ],
    "payload_indexes": [
      {"field_name": "metadata.title", "type": "text"}
    ]
  }'

​
Manage namespaces

​
Behavior & validation

  • Header usage: Pass X-Namespace on most routes after creation to scope reads/writes.
  • Feature availability: Selected feature_extractors constrain what can be used in collections within this namespace.
  • Payload indexes: Mutable; tune over time as query patterns evolve.
  • Tenant filter: All writes/read filters include tenant scoping automatically.

​
See also

Buckets

Define schemas and register objects in a namespace

Collections

Store processed documents for retrieval

Feature Extractors

Configure available features and model outputs

Retrievers

Query one or more collections within a namespace