Skip to main content
PATCH
Partially Update Namespace

Authorizations

​
Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

Path Parameters

​
namespace_identifier
string
required

Either the namespace name or namespace ID

Examples:

"my_namespace"

"ns_1234567890"

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request schema for partially updating a namespace (PATCH operation).

​
namespace_name
string | null

Updated name for the namespace

Required string length: 3 - 64
Example:

"product-search"

​
description
string | null

Updated description for the namespace

​
feature_extractors
BaseFeatureExtractorModel · object[] | null

Feature extractors to add to this namespace. Existing extractors are preserved; only new ones are appended. Each extractor must be a registered builtin plugin.

​
payload_indexes
PayloadIndexConfig · object[] | null

Updated list of custom payload indexes for this namespace.

​
auto_create_indexes
boolean | null

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. Default: False.

Example:

true

​
adaptive_indexing
boolean | null

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.

Example:

false

​
repair_vectors
boolean | null

When True, verify all registered feature extractors have their corresponding vector indexes in the vector store and add any missing ones. Use this to fix namespaces where vector schema is out of sync with registered extractors.

​
infrastructure
NamespaceInfrastructure · object | null

Infrastructure configuration for this namespace.

Example:
​
trusted_issuers
NamespaceTrustedIssuer · object[] | null

Identity providers whose end-user tokens (OIDC/JWT, verified against a JWKS) may call this namespace directly from a browser, each with the retrievers and collections it may use and the claims applied as filters. Replaces the stored list; send [] to stop accepting end-user tokens.

Maximum array length: 5
​
spend_budget
NamespaceSpendBudgetUpdate · object | null

Set this namespace's daily and monthly spend budget in USD. It must fit inside the organization's budget. A null field returns to the organization's namespace default. Each change is recorded with who made it, when, and the prior value.

​
pinned
NamespacePin · object | null

Pin or unpin this namespace. true (or {"enabled": true}) pins it; false unpins it. Add "warm_query_encoder": true to keep one replica of each query encoder its searches call running while it is pinned, billed per replica-hour to this namespace as its own invoice line. Refused for a free organization, and past the plane's pin cap with the cap named. Unpinning releases the encoder within its idle window.

​
starred
boolean | null

true shows this namespace at the top of the organization's namespace list; false returns it to its usual place. Free, with no limit on how many, and no effect on capacity or billing.

​
tiering
TieringOverride · object | null

Replace this namespace's tiering override: enabled, idle_days {cold, frozen} and exempt (a reason). Send {} to inherit every field from the platform default again.

​
expires_at
string<date-time> | null

When the namespace is deleted automatically (UTC). Set it, move it, or send null to remove the expiry. About an hour before deletion a namespace_expiring event is recorded in the namespace's mxp_platform_events collection, and the namespace is deleted only after that warning is an hour old. Send expires_at or ttl_seconds, not both.

​
ttl_seconds
integer | null

Set expires_at to now plus this many seconds. Send null to remove the expiry. Send expires_at or ttl_seconds, not both.

Required range: x >= 60
​
cost_cap_override
NamespaceCostCapOverride · object | null

Replace this namespace's daily inference cost cap. Requires daily_usd, reason and owner. Send null to remove the override and return to the tier default.

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.

Example:
​
trusted_issuers
NamespaceTrustedIssuer · object[] | null

Identity providers whose end-user tokens (OIDC/JWT, verified against a JWKS) may call this namespace directly from a browser, each with the retrievers and collections it may use and the claims applied as filters. None or empty accepts no end-user tokens.

Maximum array length: 5
​
cost_cap_override
NamespaceCostCapOverride · object | null

Deprecated: use spend_budget. Explicit daily inference cost cap for this namespace, kept working for existing callers.

​
tiering
TieringOverride · object | null

This namespace's tiering override: enabled, idle_days and exempt (a reason). Each field left unset inherits the platform's data-class default, and each collection inherits from here. An exempt namespace is never demoted.

​
pinned
NamespacePin · object | null

This namespace's pin: enabled, warm_query_encoder, and who set it when. A pinned namespace with warm_query_encoder keeps one replica of each query encoder its searches call running, billed per replica-hour as its own invoice line. Absent means not pinned.

​
starred
boolean
default:false

Shows this namespace at the top of the organization's namespace list. A display preference shared by everyone in the organization: free, with no limit on how many, and no effect on capacity or billing. Separate from pinned, which keeps capacity warm.

​
spend_budget
Spend Budget · object | null

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.

​
budget
Budget · object | null

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_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

​
payload_indexes
PayloadIndexConfig · object[] | null

Custom payload indexes configured for this namespace

​
payload_index_count
integer | null

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_count
integer | null

Total number of documents in this namespace

​
document_count_complete
boolean | null
default:true

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_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 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_indexing
boolean
default:false

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

​
dynamic_vector_indexes
boolean | null

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.

​
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.

​
clone_status
string | null

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_error
string | null

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

​
clone_phase
string | null

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_id
string | null

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

​
clone_dispatched_at
string<date-time> | null

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

​
source_namespace_id
string | null

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

​
namespace_ready
boolean
default:false

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_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 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.