Namespaces

Create Namespace

Changed on

Creates a new namespace with specified feature extractors and payload indexes.

post/v1/namespaces

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/namespaces
  • Auth: HTTP bearer

Request body

namespace_idstring nullable

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.

namespace_namestring required

Name of the namespace to create

modestring nullable

Namespace mode. 'managed' (default) uses Mixpeek feature extractors. 'standalone' allows BYO vectors without extractors. If omitted and ONLY vector_configs is provided (no features/feature_extractors), standalone is inferred.

namespace_type'standard' | 'marketplace'

Type of namespace defining its access control and billing model.

scope'org' | 'system'

Ownership scope for a namespace.

ORG: owned by a single organization (default). Internal_id-scoped. SYSTEM: owned by Mixpeek, visible read-only to every authenticated user. Used for curated sample corpora that power the onboarding experience. Mutations require MIXPEEK_PRIVATE_TOKEN admin auth.

descriptionstring nullable

Description of the namespace

featuresstring[] nullable

Modality+features config (contract v2 §6.2, D9): feature keys from GET /v1/collections/features (e.g. ['image_search', 'faces'] or ['custom:<plugin>']). Resolved server-side to the UNION of feature extractors the namespace needs — the preferred alternative to feature_extractors (extractor names are internal implementation). A namespace hosts many collections, so multiple features spanning multiple extractors are fine here. May be combined with feature_extractors (the two merge as a union). If neither is provided, the namespace gets the standard baseline (same as the scaffolded default namespace). Managed mode only.

auto_create_indexesboolean nullable

Enable automatic creation of vector store 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).

adaptive_indexingboolean nullable

Let the vector index re-tune its own partition size and flush threshold from observed search latency. Off by default. When on, every change it makes is recorded in the namespace's mxp_platform_events collection (event_type index_adaptation) with the parameter, its old and new value, the search count that triggered it, and p95 search latency before and after.

ttl_secondsinteger nullable

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

Example request

{
  "features": [
    "image_search",
    "text_search",
    "faces"
  ],
  "namespace_name": "media_library"
}

Response

Successful Response

objectstring

Resource type identifier, always 'namespace'.

namespace_idstring

Unique identifier for the namespace. Format: ns_<random>.

namespace_namestring required

Name of the namespace

namespace_type'standard' | 'marketplace'

Type of namespace defining its access control and billing model.

scope'org' | 'system'

Ownership scope for a namespace.

ORG: owned by a single organization (default). Internal_id-scoped. SYSTEM: owned by Mixpeek, visible read-only to every authenticated user. Used for curated sample corpora that power the onboarding experience. Mutations require MIXPEEK_PRIVATE_TOKEN admin auth.

spend_budgetobject nullable

This namespace's own spend budget as stored: daily_usd, monthly_usd and the change history. Absent until someone sets it; the organization's namespace default applies until then.

budgetobject nullable

Read-only. The namespace's effective daily and monthly budget, where each number comes from, spend to date, and the headroom left under the organization's budget. Computed on GET; never stored.

cluster_idstring nullable

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

descriptionstring nullable

Description of the namespace

payload_index_countinteger nullable

Number of USER (non-protected) payload indexes on this namespace — the same count the Studio Namespaces table shows per row. Populated even in the summary LIST view, which omits the heavy payload_indexes array itself (the array is ~75% of the list payload, but its count is a single integer). Without it the table can only show '—'.

document_countinteger nullable

Total number of documents in this namespace

document_count_completeboolean nullable

False when the live vector-store count above did not finish in time (e.g. a shard still replaying its WAL after a restart) and document_count is therefore null rather than a real count, including a genuine zero. True (the default) covers every non-degraded response, including an empty namespace, whose document_count is 0 with this true.

bucket_countinteger nullable

Total number of buckets in this namespace

collection_countinteger nullable

Total number of collections in this namespace

object_countinteger nullable

Total number of objects across all buckets in this namespace

auto_create_indexesboolean

Enable automatic creation of vector store 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.

adaptive_indexingboolean

Let the vector index re-tune its own partition size and flush threshold from observed search latency. Off by default. When on, every change it makes is recorded in the namespace's mxp_platform_events collection (event_type index_adaptation) with the parameter, its old and new value, the search count that triggered it, and p95 search latency before and after.

vector_inference_mapobject nullable

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

dynamic_vector_indexesboolean nullable

Creation-time marker for BYO vector-name handling. False = the namespace was created with EXPLICIT vector_configs, so upserting a vector name outside those configs is rejected (422) instead of silently auto-indexed under a name nothing searches. True = fully dynamic BYO namespace (created without vector_configs): new vector names keep being inferred on first upsert. Null (namespaces that predate the marker) behaves as True so existing flows are unchanged.

modestring nullable

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_configsobject[] nullable

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.

clone_statusstring nullable

Deep-clone / scaffold sample-data progress: 'cloning' (in flight), 'ready' (completed), 'failed' (see clone_error). Null for namespaces that were never cloned. Poll this after a scaffold instantiate with include_sample_data=true.

clone_errorstring nullable

Error detail when clone_status='failed'; null otherwise.

clone_phasestring nullable

Fine-grained clone progress: 'queued' (dispatched, waiting for a worker — a clone can wait many minutes behind tenant heavy-queue backlogs), 'copying' (the clone task is actively running), null once terminal (see clone_status) or for namespaces never cloned. Distinguishes a queue-starved clone from a dead one.

clone_task_idstring nullable

Work id of the in-flight or last deep clone, for diagnosing a stalled clone from the namespace record alone.

clone_dispatched_atstring date-time nullable

When the deep-clone task was dispatched; with clone_phase='queued' this measures time spent waiting for a worker.

source_namespace_idstring nullable

For a cloned namespace, the source (golden/sample) namespace id it was cloned from.

namespace_readyboolean

ALWAYS PRESENT. True only after the server CONFIRMED this namespace is usable: its vector collection exists and is reachable (a served live count, the readiness signal) and no clone is in flight. Never a prediction or timestamp. A wizard-created namespace mid-provision reads false (poll the namespace GET; it flips true on the first confirming read and the flip is persisted). Namespaces created before the feature shipped emit true; post-ship namespaces with no stored value emit false (fail toward not-ready).

created_atstring date-time nullable

When the namespace was created

updated_atstring date-time nullable

When the namespace was last updated

expires_atstring date-time nullable

UTC timestamp after which the namespace is deleted automatically. Set at create time from ttl_seconds, and changed or cleared with PATCH (expires_at or ttl_seconds). An hourly sweep records a namespace_expiring event in the namespace's mxp_platform_events collection about an hour before, and deletes the namespace once the expiry has passed and that warning is an hour old. Null means the namespace never expires.

Example response

{
  "namespace_name": "product-search",
  "infrastructure": {
    "autoscaling_enabled": false,
    "description": "Shared development namespace",
    "max_concurrent_jobs": 10
  },
  "trusted_issuers": [
    {
      "jwks": {
        "keys": [
          {
            "alg": "ES256",
            "crv": "P-256",
            "kid": "key-1",
            "kty": "EC",
            "x": "<base64url>",
            "y": "<base64url>"
          }
        ]
      },
      "claim_filters": [
        {
          "claim": "brands",
          "field": "brand_id"
        }
      ],
      "group_claims": [
        {
          "claim": "app_metadata.brands",
          "prefix": "brand:"
        }
      ],
      "admin_claim": {
        "claim": "app_metadata.internal",
        "values": [
          "true"
        ]
      }
    }
  ],
  "cost_cap_override": {
    "daily_usd": 250,
    "reason": "Nightly re-index of the full catalog, about $180/day, approved by finance",
    "owner": "data-platform@example.com"
  },
  "cluster_id": "iclstr_abc123xyz",
  "payload_indexes": [
    {
      "description": "User-created text index for full-text search",
      "field_name": "metadata.description",
      "is_protected": false,
      "type": "text"
    }
  ]
}

Changes

  • 790bc16455f6Revision changes
    • breaking

      the response property /// became optional for the status

    • breaking

      response property trusted_issuers/anyOf[subschema #1]/items/jwks_url list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      the /// response property's minLength was decreased from 1 to 0 for the response status

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      the request property /// became optional

    • info

      request property /// list-of-types was widened by adding types null to media type application/json

    • info

      the /// request property's minLength was decreased from 1 to 0

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

  • d4b5fad18960Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status