Skip to main content
POST
/
v1
/
namespaces
Create Namespace
curl --request POST \
  --url https://api.mixpeek.com/v1/namespaces \
  --header 'Content-Type: application/json' \
  --data '
{
  "namespace_name": "spotify_playlists_dev",
  "feature_extractors": [
    {
      "feature_extractor_id": "multimodal_extractor_v1",
      "feature_extractor_name": "multimodal_extractor",
      "version": "v1"
    },
    {
      "feature_extractor_id": "image_extractor_v1",
      "feature_extractor_name": "image_extractor",
      "params": {
        "model": "siglip_base"
      },
      "version": "v1"
    }
  ],
  "description": "This namespace contains playlists from Spotify",
  "payload_indexes": [
    {
      "field_name": "metadata.title",
      "field_schema": {
        "lowercase": true,
        "max_token_len": 15,
        "min_token_len": 2,
        "tokenizer": "word",
        "type": "text"
      },
      "is_protected": false,
      "type": "text"
    },
    {
      "field_name": "metadata.description",
      "field_schema": {
        "is_tenant": true,
        "type": "keyword"
      },
      "is_protected": false,
      "type": "keyword"
    }
  ],
  "auto_create_indexes": true
}
'
{
  "namespace_name": "spotify_playlists_dev",
  "namespace_id": "<string>",
  "infrastructure": {
    "autoscaling_enabled": false,
    "compute_tier": "shared",
    "description": "Shared development namespace",
    "max_concurrent_jobs": 10,
    "qdrant_collection": "ns_dev",
    "ray_head_node_url": "ray://shared-cluster:10001"
  },
  "cluster_id": "iclstr_abc123xyz",
  "description": "<string>",
  "feature_extractors": [
    {
      "feature_extractor_name": "<string>",
      "version": "<string>",
      "feature_extractor_id": "<string>",
      "params": {}
    }
  ],
  "payload_indexes": [
    {
      "field_name": "<string>",
      "type": "keyword",
      "field_schema": {
        "type": "text",
        "tokenizer": "word",
        "min_token_len": 2,
        "max_token_len": 15,
        "lowercase": true
      },
      "is_protected": false
    }
  ],
  "document_count": 123,
  "bucket_count": 123,
  "collection_count": 123,
  "object_count": 123,
  "auto_create_indexes": false,
  "vector_inference_map": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

Body

application/json

Request schema for creating a new namespace.

​
namespace_name
string
required

Name of the namespace to create

Example:

"spotify_playlists_dev"

​
feature_extractors
BaseFeatureExtractorModel · object[]
required

List of feature extractors to use. At least one feature extractor must be provided. Optional 'params' can be specified for extractors with configurable settings (e.g., model selection) that affect vector dimensions. These params are locked at namespace creation time.

Minimum array length: 1
Example:
[
  {
    "feature_extractor_id": "multimodal_extractor_v1",
    "feature_extractor_name": "multimodal_extractor",
    "version": "v1"
  },
  {
    "feature_extractor_id": "image_extractor_v1",
    "feature_extractor_name": "image_extractor",
    "params": { "model": "siglip_base" },
    "version": "v1"
  }
]
​
description
string | null

Description of the namespace

Example:

"This namespace contains playlists from Spotify"

​
payload_indexes
PayloadIndexConfig · object[] | null

Optional list of custom payload index configurations. Indexes required by selected feature extractors will be added automatically.

Example:
[
  {
    "field_name": "metadata.title",
    "field_schema": {
      "lowercase": true,
      "max_token_len": 15,
      "min_token_len": 2,
      "tokenizer": "word",
      "type": "text"
    },
    "is_protected": false,
    "type": "text"
  },
  {
    "field_name": "metadata.description",
    "field_schema": { "is_tenant": true, "type": "keyword" },
    "is_protected": false,
    "type": "keyword"
  }
]
​
auto_create_indexes
boolean | null
default:false

Enable automatic creation of Qdrant payload indexes based on filter usage patterns. When enabled, the system tracks which fields are most frequently filtered (>100 queries/24h) and automatically creates indexes to improve query performance. Background task runs every 6 hours. Expected performance improvement: 50-90% latency reduction for filtered queries.

Example:

true

Response

Successful Response

Namespace model.

​
namespace_name
string
required

Name of the namespace

Example:

"spotify_playlists_dev"

​
namespace_id
string

Unique identifier for the namespace

​
infrastructure
NamespaceInfrastructure · object

Infrastructure configuration for the namespace (Ray, Qdrant).

Example:
{
  "autoscaling_enabled": false,
  "compute_tier": "shared",
  "description": "Shared development namespace",
  "max_concurrent_jobs": 10,
  "qdrant_collection": "ns_dev",
  "ray_head_node_url": "ray://shared-cluster:10001"
}
​
cluster_id
string | null

Infrastructure cluster ID for this namespace (Enterprise only). When set, this namespace uses dedicated Anyscale/Ray + Qdrant cluster. If None, uses shared infrastructure or organization-level infrastructure. Format: iclstr_xxx

Example:

"iclstr_abc123xyz"

​
description
string | null

Description of the namespace

​
feature_extractors
BaseFeatureExtractorModel · object[]

List of feature extractors configured for this namespace

​
payload_indexes
PayloadIndexConfig · object[] | null

Custom payload indexes configured for this namespace

​
document_count
integer | null

Total number of documents in this namespace (from Qdrant collection)

​
bucket_count
integer | null

Total number of buckets in this namespace

​
collection_count
integer | null

Total number of collections in this namespace

​
object_count
integer | null

Total number of objects across all buckets in this namespace

​
auto_create_indexes
boolean
default:false

Enable automatic creation of Qdrant payload indexes based on filter usage patterns. When enabled, the system tracks which fields are most frequently filtered (>100 queries/24h) and automatically creates indexes to improve query performance. Background task runs every 6 hours. Expected performance improvement: 50-90% latency reduction for filtered queries.

​
vector_inference_map
Vector Inference Map · object

Mapping of vector index names to inference service names. Built at namespace creation based on extractor configurations. Used by feature search to determine correct inference service for queries. Example: {'image_extractor_v1_embedding': 'google_siglip_base_v1'}

​
created_at
string<date-time> | null

When the namespace was created

​
updated_at
string<date-time> | null

When the namespace was last updated