Skip to main content
POST
/
v1
/
namespaces
Create Namespace
curl --request POST \
  --url https://api.mixpeek.com/v1/namespaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "namespace_name": "spotify_playlists_dev",
  "description": "This namespace contains playlists from Spotify",
  "feature_extractors": [
    {
      "feature_extractor_id": "video_extractor_1.0.0",
      "feature_extractor_name": "video_extractor",
      "version": "1.0.0"
    }
  ],
  "payload_indexes": [
    {
      "field_name": "metadata.title",
      "field_schema": {
        "lowercase": true,
        "max_token_len": 15,
        "min_token_len": 2,
        "tokenizer": "word",
        "type": "text"
      },
      "type": "text"
    },
    {
      "field_name": "metadata.description",
      "field_schema": {
        "is_tenant": true,
        "type": "keyword"
      },
      "type": "keyword"
    }
  ]
}'
{
  "namespace_id": "<string>",
  "namespace_name": "spotify_playlists_dev",
  "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"
  },
  "description": "<string>",
  "feature_extractors": [
    {
      "feature_extractor_name": "<string>",
      "version": "<string>",
      "feature_extractor_id": "<string>"
    }
  ],
  "payload_indexes": [
    {
      "field_name": "<string>",
      "type": "keyword",
      "field_schema": {
        "type": "text",
        "tokenizer": "word",
        "min_token_len": 2,
        "max_token_len": 15,
        "lowercase": true
      }
    }
  ],
  "document_count": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

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

"Bearer sk_test_xyz789"

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.

Minimum length: 1
Example:
[
  {
    "feature_extractor_id": "video_extractor_1.0.0",
    "feature_extractor_name": "video_extractor",
    "version": "1.0.0"
  }
]
​
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"
    },
    "type": "text"
  },
  {
    "field_name": "metadata.description",
    "field_schema": { "is_tenant": true, "type": "keyword" },
    "type": "keyword"
  }
]

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

Infrastructure configuration for the namespace (Ray, Qdrant). Infrastructure configuration associated with a namespace.

Defines infrastructure resources for a specific namespace. This configuration can override organization-level defaults, enabling flexible deployment patterns where different namespaces use different infrastructure.

Resolution Priority: When a namespace has infrastructure configured with DEDICATED tier, it takes precedence over organization-level infrastructure. This allows: - ENTERPRISE org with SHARED namespace (cost savings for dev/test) - ENTERPRISE org with dedicated GPU namespace (ML workloads) - Mixed infrastructure within a single organization

Tier Behaviors: SHARED: - Namespace uses organization infrastructure (if configured) - Falls back to Mixpeek's shared infrastructure - All infrastructure URLs should be None - Lowest cost, multi-tenant

DEDICATED_CPU:
    - Namespace uses its own dedicated CPU infrastructure
    - Requires qdrant_url, qdrant_api_key, ray_head_node_url
    - Single-tenant CPU compute
    - Medium cost

DEDICATED_GPU:
    - Namespace uses its own dedicated GPU infrastructure
    - Requires qdrant_url, qdrant_api_key, ray_head_node_url
    - Requires gpu_type and gpus_per_worker configuration
    - Single-tenant GPU compute
    - Highest cost

Use Cases: - Development namespace: Set compute_tier=SHARED to use organization's infrastructure - Production namespace: Inherit organization's DEDICATED infrastructure (don't override) - ML namespace: Override with DEDICATED_GPU and GPU configuration - Cost optimization: Override ENTERPRISE org to SHARED for dev/test namespaces

Examples: Inherits organization infrastructure (no override): NamespaceInfrastructure( qdrant_collection="ns_production", compute_tier=ComputeTier.SHARED # Uses org or shared infrastructure )

Override to dedicated CPU:
    NamespaceInfrastructure(
        qdrant_url="http://qdrant-ns-prod:6333",
        qdrant_api_key="qdrant_key_ns_123",
        qdrant_collection="ns_production",
        ray_head_node_url="ray://ray-ns-prod:10001",
        ray_dashboard_url="http://ray-ns-dashboard:8265",
        compute_tier=ComputeTier.DEDICATED_CPU,
        max_concurrent_jobs=50
    )

Override to dedicated GPU:
    NamespaceInfrastructure(
        qdrant_url="http://qdrant-gpu:6333",
        qdrant_api_key="qdrant_key_gpu",
        qdrant_collection="ns_ml",
        ray_head_node_url="ray://ray-gpu:10001",
        compute_tier=ComputeTier.DEDICATED_GPU,
        gpu_type="A100",
        gpus_per_worker=2
    )
Examples:
{
  "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"
}
{
  "autoscaling_enabled": true,
  "compute_tier": "dedicated_cpu",
  "description": "Dedicated production CPU cluster",
  "max_concurrent_jobs": 50,
  "max_workers": 20,
  "min_workers": 3,
  "qdrant_collection": "ns_production",
  "ray_cluster_id": "ray_prod_cluster",
  "ray_dashboard_url": "http://prod-dashboard:8265",
  "ray_head_node_url": "ray://prod-head:10001"
}
​
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)

​
created_at
string<date-time> | null

When the namespace was created

​
updated_at
string<date-time> | null

When the namespace was last updated