Create Namespace

curl --request POST \
  --url https://api.mixpeek.com/v1/namespaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "namespace_name": "product-search",
  "namespace_id": "<string>",
  "mode": "managed",
  "namespace_type": "standard",
  "scope": "org",
  "description": "This namespace contains playlists from Spotify",
  "feature_extractors": [
    {
      "feature_extractor_name": "multimodal_extractor",
      "version": "v1"
    },
    {
      "feature_extractor_name": "image_extractor",
      "params": {
        "model": "siglip_base"
      },
      "version": "v1"
    }
  ],
  "vector_configs": [
    {
      "dimension": 768,
      "metric": "cosine",
      "name": "clip"
    }
  ],
  "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,
  "ttl_seconds": 61,
  "infrastructure": {
    "autoscaling_enabled": false,
    "compute_tier": "shared",
    "max_concurrent_jobs": 10,
    "qdrant_collection": "ns_dev",
    "ray_head_node_url": "ray://shared-cluster:10001"
  }
}
'

{
  "namespace_name": "product-search",
  "object": "namespace",
  "namespace_id": "<string>",
  "namespace_type": "standard",
  "scope": "org",
  "infrastructure": {
    "autoscaling_enabled": false,
    "compute_tier": "shared",
    "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>",
      "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": {},
  "mode": "<string>",
  "vector_configs": [
    {}
  ],
  "qdrant_status": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z"
}

POST

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": "product-search",
  "namespace_id": "<string>",
  "mode": "managed",
  "namespace_type": "standard",
  "scope": "org",
  "description": "This namespace contains playlists from Spotify",
  "feature_extractors": [
    {
      "feature_extractor_name": "multimodal_extractor",
      "version": "v1"
    },
    {
      "feature_extractor_name": "image_extractor",
      "params": {
        "model": "siglip_base"
      },
      "version": "v1"
    }
  ],
  "vector_configs": [
    {
      "dimension": 768,
      "metric": "cosine",
      "name": "clip"
    }
  ],
  "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,
  "ttl_seconds": 61,
  "infrastructure": {
    "autoscaling_enabled": false,
    "compute_tier": "shared",
    "max_concurrent_jobs": 10,
    "qdrant_collection": "ns_dev",
    "ray_head_node_url": "ray://shared-cluster:10001"
  }
}
'

{
  "namespace_name": "product-search",
  "object": "namespace",
  "namespace_id": "<string>",
  "namespace_type": "standard",
  "scope": "org",
  "infrastructure": {
    "autoscaling_enabled": false,
    "compute_tier": "shared",
    "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>",
      "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": {},
  "mode": "<string>",
  "vector_configs": [
    {}
  ],
  "qdrant_status": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request schema for creating a new namespace.

namespace_name

string

required

Name of the namespace to create

Required string length: 3 - 64

Example:

"product-search"

namespace_id

string | null

Optional namespace ID override. Used for recovery/migration when recreating a namespace with a known ID. If not provided, a new ID is auto-generated.

mode

string | null

default:managed

Namespace mode. 'managed' (default) uses Mixpeek feature extractors. 'standalone' allows BYO vectors without extractors.

namespace_type

enum<string> | null

default:standard

Type of namespace. STANDARD for regular namespaces, MARKETPLACE for curated datasets.

Available options:

standard,

marketplace

scope

enum<string> | null

default:org

Ownership scope. ORG (default) creates an org-scoped namespace. SYSTEM requires Mixpeek admin privileges and creates a namespace visible read-only to every org — used for curated sample corpora.

Available options:

org,

system

description

string | null

Description of the namespace

Example:

"This namespace contains playlists from Spotify"

feature_extractors

BaseFeatureExtractorModel · object[] | null

List of feature extractors to configure for this namespace. Required for managed mode (at least one). Not used for standalone mode. Each extractor requires 'feature_extractor_name' and 'version'. 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. Example: [{"feature_extractor_name": "multimodal_extractor", "version": "v1"}]

Show child attributes

Example:

[
  {
    "feature_extractor_name": "multimodal_extractor",
    "version": "v1"
  },
  {
    "feature_extractor_name": "image_extractor",
    "params": { "model": "siglip_base" },
    "version": "v1"
  }
]

vector_configs

VectorConfigSpec · object[] | null

Optional vector index configurations for standalone mode. Each entry defines a named vector index with dimension and distance metric. If omitted, indexes are auto-created on first upsert (schema-on-write).

Show child attributes

Example:

[
  {
    "dimension": 768,
    "metric": "cosine",
    "name": "clip"
  }
]

payload_indexes

PayloadIndexConfig · object[] | null

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

Show child attributes

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

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. Defaults: managed namespaces off, standalone namespaces on. Set explicitly to false to opt out (including for standalone, so an agent can manage indexes itself).

Example:

true

ttl_seconds

integer | null

Time-to-live in seconds. Namespace will be auto-deleted after this duration.

Required range: x >= 60

infrastructure

NamespaceInfrastructure · object | null

Optional dedicated infrastructure configuration for this namespace. Required for custom plugins and custom models (Enterprise tier). If None, uses shared infrastructure or organization-level infrastructure.

Show child attributes

Example:

{
  "autoscaling_enabled": false,
  "compute_tier": "shared",
  "max_concurrent_jobs": 10,
  "qdrant_collection": "ns_dev",
  "ray_head_node_url": "ray://shared-cluster:10001"
}

Response

Successful Response

Namespace model.

namespace_name

string

required

Name of the namespace

Maximum string length: 64

Example:

"product-search"

object

string

default:namespace

read-only

Resource type identifier, always 'namespace'.

namespace_id

string

Unique identifier for the namespace. Format: ns_.

namespace_type

enum<string>

default:standard

Type of namespace. STANDARD for regular namespaces, MARKETPLACE for curated datasets that can be subscribed to.

Available options:

standard,

marketplace

scope

enum<string>

default:org

Ownership scope. ORG (default) is org-scoped — only visible to members of the owning organization. SYSTEM is Mixpeek-owned and visible read-only to every authenticated org; used for curated sample corpora. Mutations on SYSTEM namespaces require admin auth.

Available options:

org,

system

infrastructure

NamespaceInfrastructure · object | null

Infrastructure configuration for the namespace.

Show child attributes

Example:

{
  "autoscaling_enabled": false,
  "compute_tier": "shared",
  "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 a dedicated compute and vector 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

Show child attributes

payload_indexes

PayloadIndexConfig · object[] | null

Custom payload indexes configured for this namespace

Show child attributes

document_count

integer | null

Total number of documents in this namespace

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

vector_inference_map

Vector Inference Map · object | null

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

Show child attributes

mode

string | null

Namespace mode: 'managed' (Mixpeek manages vector schemas and inference) or 'standalone' (bring-your-own vectors). Populated from the stored mvs_mode; null for namespaces that predate BYOV.

vector_configs

Vector Configs · object[] | null

For standalone / promoted (BYO-vector) namespaces, the per-vector configs: name, dimension, metric. Populated from the stored mvs_vector_configs; null for managed namespaces with no BYO vectors.

qdrant_status

Qdrant Status · object | null

Live vector collection status. Populated when retrieving a namespace. Includes: status (green/yellow/red), points_count, indexed_vectors_count, segments_count. None if vector collection does not exist or is unreachable.

created_at

string<date-time> | null

When the namespace was created

updated_at

string<date-time> | null

When the namespace was last updated

expires_at

string<date-time> | null

UTC timestamp after which the namespace is auto-deleted by the hourly cleanup_expired_namespaces reaper. Computed at create time from CreateNamespaceRequest.ttl_seconds; null means the namespace never expires.

List Dsar Requests Get Namespace