> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Namespaces > List all namespaces for a user ## OpenAPI ````yaml post /v1/namespaces/list openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/namespaces/list: post: tags: - Namespaces summary: List Namespaces description: List all namespaces for a user operationId: list_namespaces_v1_namespaces_list_post parameters: - name: include_system in: query required: false schema: type: boolean description: Include read-only system namespaces (e.g. sample-data) default: false title: Include System description: Include read-only system namespaces (e.g. sample-data) - name: view in: query required: false schema: enum: - full - summary type: string description: >- Response detail level. 'full' (default) returns complete namespace objects. 'summary' omits heavy per-namespace config (payload_indexes, feature_extractors, vector_inference_map, vector_configs) — ~93% smaller — for high-frequency list/switcher views. Fetch full config via GET /v1/namespaces/{namespace_identifier}. default: full title: View description: >- Response detail level. 'full' (default) returns complete namespace objects. 'summary' omits heavy per-namespace config (payload_indexes, feature_extractors, vector_inference_map, vector_configs) — ~93% smaller — for high-frequency list/switcher views. Fetch full config via GET /v1/namespaces/{namespace_identifier}. - name: limit in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Limit - name: page_size in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Page Size - name: offset in: query required: false schema: anyOf: - type: integer maximum: 10000 minimum: 0 - type: 'null' title: Offset - name: page in: query required: false schema: anyOf: - type: integer minimum: 1 - type: 'null' title: Page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor - name: next_cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Next Cursor - name: after in: query required: false schema: anyOf: - type: string - type: 'null' title: After - name: include_total in: query required: false schema: type: boolean default: false title: Include Total requestBody: content: application/json: schema: $ref: '#/components/schemas/ListNamespacesRequest' default: case_sensitive: false description: >- Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02). x-unknown-keys: until: '2026-11-02' then: 422 extra_forbidden responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListNamespacesResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: ListNamespacesRequest: properties: limit: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Limit description: Page size. A body value wins over the `limit` query param. page_size: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Page Size description: Alias for `limit` (page size). If both are given, `limit` wins. offset: anyOf: - type: integer maximum: 10000 minimum: 0 - type: 'null' title: Offset description: >- Number of results to skip (legacy, use cursor instead). A body value wins over the `offset` query param. page: anyOf: - type: integer minimum: 1 - type: 'null' title: Page description: >- 1-indexed page number. Folds to offset = (page-1) * limit. If both `page` and `offset` are given, `offset` wins. filters: anyOf: - additionalProperties: true type: object - type: 'null' title: Filters description: >- Optional filters to apply to the namespace list. Supports filtering by namespace_id or namespace_name. example: namespace_id: ns_abc123 namespace_name: $regex: ^my_namespace sort: anyOf: - additionalProperties: true type: object - type: 'null' title: Sort description: >- Optional sort criteria for the namespace list (single-column, legacy). With no sort at all, starred namespaces come first. A sort on any other field is applied exactly as given, so starred namespaces get no special place in it. example: direction: asc field: namespace_name sorts: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Sorts description: >- Sort criteria as a list of {field, direction} — the shape Studio datatables and the retriever list send. The first entry is the primary sort. Takes precedence over the singular `sort`. To keep starred namespaces on top of another order, name starred first: the second entry then orders the namespaces inside each group. Any other second entry is ignored. example: - direction: desc field: starred - direction: desc field: created_at search: anyOf: - type: string - type: 'null' title: Search description: >- Search term for wildcard search across namespace_id, namespace_name, description, and other text fields. example: ns_abc123 case_sensitive: type: boolean title: Case Sensitive description: If True, filters and search will be case-sensitive default: false type: object title: ListNamespacesRequest description: |- Request schema for listing namespaces. Inherits body-level limit/page_size/offset/page — body values win over query pagination via merge_body_pagination. examples: - filters: namespace_id: ns_abc123 sort: direction: asc field: namespace_name - search: ns_abc123 ListNamespacesResponse: properties: results: items: $ref: '#/components/schemas/NamespaceModel' type: array title: Results description: List of namespaces matching the query pagination: $ref: '#/components/schemas/PaginationResponse' description: Pagination information for the current result window total_count: type: integer title: Total Count description: Total number of namespaces that match the query stats: anyOf: - $ref: '#/components/schemas/NamespaceListStats' - type: 'null' description: Aggregate statistics across all namespaces in the result type: object required: - results - pagination - total_count title: ListNamespacesResponse description: Response schema for listing namespaces. examples: - pagination: has_more: false limit: 10 skip: 0 results: - created_at: '2024-01-15T10:30:00Z' 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 namespace_id: ns_ab12cd34ef namespace_name: spotify_playlists_dev payload_indexes: - field_name: metadata.title type: text updated_at: '2024-01-15T10:30:00Z' total_count: 1 ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false NamespaceModel: properties: object: type: string title: Object description: Resource type identifier, always 'namespace'. default: namespace readOnly: true namespace_id: type: string title: Namespace Id description: 'Unique identifier for the namespace. Format: ns_.' namespace_name: type: string maxLength: 64 title: Namespace Name description: Name of the namespace example: product-search namespace_type: $ref: '#/components/schemas/NamespaceType' description: >- Type of namespace. STANDARD for regular namespaces, MARKETPLACE for curated datasets that can be subscribed to. default: standard scope: $ref: '#/components/schemas/NamespaceScope' description: >- 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. default: org infrastructure: anyOf: - $ref: '#/components/schemas/NamespaceInfrastructure' - type: 'null' description: Infrastructure configuration for the namespace. trusted_issuers: anyOf: - items: $ref: '#/components/schemas/NamespaceTrustedIssuer' type: array maxItems: 5 - type: 'null' title: Trusted Issuers description: >- 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. cost_cap_override: anyOf: - $ref: '#/components/schemas/NamespaceCostCapOverride' - type: 'null' description: >- Deprecated: use spend_budget. Explicit daily inference cost cap for this namespace, kept working for existing callers. tiering: anyOf: - $ref: '#/components/schemas/TieringOverride' - type: 'null' description: >- 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: anyOf: - $ref: '#/components/schemas/NamespacePin' - type: 'null' description: >- 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: type: boolean title: Starred description: >- 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. default: false spend_budget: anyOf: - additionalProperties: true type: object - type: 'null' title: Spend Budget description: >- 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: anyOf: - additionalProperties: true type: object - type: 'null' title: Budget description: >- 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: anyOf: - type: string - type: 'null' title: Cluster Id description: >- 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 examples: - iclstr_abc123xyz - null description: anyOf: - type: string - type: 'null' title: Description description: Description of the namespace feature_extractors: items: $ref: '#/components/schemas/BaseFeatureExtractorModel-Output' type: array title: Feature Extractors description: List of feature extractors configured for this namespace payload_indexes: anyOf: - items: $ref: '#/components/schemas/PayloadIndexConfig-Output' type: array - type: 'null' title: Payload Indexes description: Custom payload indexes configured for this namespace payload_index_count: anyOf: - type: integer - type: 'null' title: Payload Index Count description: >- 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: anyOf: - type: integer - type: 'null' title: Document Count description: Total number of documents in this namespace document_count_complete: anyOf: - type: boolean - type: 'null' title: Document Count Complete description: >- 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. default: true bucket_count: anyOf: - type: integer - type: 'null' title: Bucket Count description: Total number of buckets in this namespace collection_count: anyOf: - type: integer - type: 'null' title: Collection Count description: Total number of collections in this namespace object_count: anyOf: - type: integer - type: 'null' title: Object Count description: Total number of objects across all buckets in this namespace auto_create_indexes: type: boolean title: Auto Create Indexes description: >- 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 adaptive_indexing: type: boolean title: Adaptive Indexing description: >- 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. default: false vector_inference_map: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Vector Inference Map description: >- 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: anyOf: - type: boolean - type: 'null' title: Dynamic Vector Indexes description: >- 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: anyOf: - type: string - type: 'null' title: Mode description: >- 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: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Vector Configs description: >- 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: anyOf: - type: string - type: 'null' title: Clone Status description: >- 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: anyOf: - type: string - type: 'null' title: Clone Error description: Error detail when clone_status='failed'; null otherwise. clone_phase: anyOf: - type: string - type: 'null' title: Clone Phase description: >- 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: anyOf: - type: string - type: 'null' title: Clone Task Id description: >- Work id of the in-flight or last deep clone, for diagnosing a stalled clone from the namespace record alone. clone_dispatched_at: anyOf: - type: string format: date-time - type: 'null' title: Clone Dispatched At description: >- When the deep-clone task was dispatched; with clone_phase='queued' this measures time spent waiting for a worker. source_namespace_id: anyOf: - type: string - type: 'null' title: Source Namespace Id description: >- For a cloned namespace, the source (golden/sample) namespace id it was cloned from. namespace_ready: type: boolean title: Namespace Ready description: >- 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). default: false created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: When the namespace was created updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: When the namespace was last updated expires_at: anyOf: - type: string format: date-time - type: 'null' title: Expires At description: >- 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. type: object required: - namespace_name title: NamespaceModel description: Namespace model. PaginationResponse: properties: total: anyOf: - type: integer - type: 'null' title: Total description: >- Number of items matching the request across all pages, filters included. null unless the request set include_total=true (in the body or as ?include_total=true). A counted request that matches nothing returns 0. page: anyOf: - type: integer - type: 'null' title: Page page_size: anyOf: - type: integer - type: 'null' title: Page Size total_pages: anyOf: - type: integer - type: 'null' title: Total Pages description: Number of pages at page_size. null unless include_total=true. next_page: anyOf: - type: string - type: 'null' title: Next Page previous_page: anyOf: - type: string - type: 'null' title: Previous Page next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor type: object title: PaginationResponse description: |- PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true NamespaceListStats: properties: total_feature_extractors: type: integer title: Total Feature Extractors description: Total number of feature extractors across all namespaces default: 0 total_payload_indexes: type: integer title: Total Payload Indexes description: Total number of payload indexes across all namespaces default: 0 total_documents: type: integer title: Total Documents description: Total number of documents across all namespaces default: 0 total_documents_complete: type: boolean title: Total Documents Complete description: >- Whether every namespace's document count in this list finished. False when any namespace has document_count_complete false, so total_documents is a lower bound. default: true total_buckets: type: integer title: Total Buckets description: Total number of buckets across all namespaces default: 0 total_collections: type: integer title: Total Collections description: Total number of collections across all namespaces default: 0 total_objects: type: integer title: Total Objects description: Total number of objects across all namespaces default: 0 avg_feature_extractors_per_namespace: type: number title: Avg Feature Extractors Per Namespace description: Average number of feature extractors per namespace default: 0 avg_payload_indexes_per_namespace: type: number title: Avg Payload Indexes Per Namespace description: Average number of payload indexes per namespace default: 0 avg_documents_per_namespace: type: number title: Avg Documents Per Namespace description: Average number of documents per namespace default: 0 avg_buckets_per_namespace: type: number title: Avg Buckets Per Namespace description: Average number of buckets per namespace default: 0 avg_collections_per_namespace: type: number title: Avg Collections Per Namespace description: Average number of collections per namespace default: 0 avg_objects_per_namespace: type: number title: Avg Objects Per Namespace description: Average number of objects per namespace default: 0 type: object title: NamespaceListStats description: Aggregate statistics for a list of namespaces. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. NamespaceType: type: string enum: - standard - marketplace title: NamespaceType description: Type of namespace defining its access control and billing model. NamespaceScope: type: string enum: - org - system title: NamespaceScope description: |- 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. NamespaceInfrastructure: properties: ray_cluster_id: anyOf: - type: string pattern: ^ray_[a-zA-Z0-9_]{3,64}$ - type: 'null' title: Ray Cluster Id description: Dedicated Ray cluster identifier for this namespace. examples: - ray_shared - ray_prod_gpu_cluster - null ray_dashboard_url: anyOf: - type: string - type: 'null' title: Ray Dashboard Url description: Ray dashboard URL for monitoring (http://host:8265). examples: - http://ray-dashboard-prod:8265 s3_vector_bucket: anyOf: - type: string - type: 'null' title: S3 Vector Bucket description: >- S3 Vectors bucket name for vector tiering. When set, vectors are durably stored in S3. max_concurrent_jobs: type: integer maximum: 1000 minimum: 1 title: Max Concurrent Jobs description: Maximum concurrent Ray jobs allowed for the namespace. default: 10 examples: - 10 - 50 - 20 autoscaling_enabled: type: boolean title: Autoscaling Enabled description: Toggle autoscaling for dedicated clusters (ignored for shared tier). default: true min_workers: type: integer maximum: 100 minimum: 0 title: Min Workers description: Lower bound for Ray workers when autoscaling is enabled. default: 1 max_workers: type: integer maximum: 100 minimum: 1 title: Max Workers description: Upper bound for Ray workers when autoscaling is enabled. default: 10 gpu_type: anyOf: - type: string - type: 'null' title: Gpu Type description: GPU type for dedicated GPU clusters (e.g. A100, T4). examples: - A100 - T4 - null gpus_per_worker: type: integer maximum: 8 minimum: 0 title: Gpus Per Worker description: Number of GPUs allocated to each Ray worker when using GPUs. default: 1 compute_profiles: additionalProperties: additionalProperties: true type: object type: object title: Compute Profiles description: >- Per-extractor compute profile overrides keyed by feature_extractor_id (e.g. 'text_extractor_v1'). Values are partial ComputeProfile dicts merged on top of the extractor's built-in profile at batch build time. examples: - text_extractor_v1: batch_size: 64 resource_type: gpu s3_plugin_bucket: type: string title: S3 Plugin Bucket description: S3 bucket for storing custom plugins and model weights. default: mixpeek-plugins s3_plugin_prefix: anyOf: - type: string - type: 'null' title: S3 Plugin Prefix description: >- S3 prefix for namespace-scoped plugin storage. Format: {namespace_id}/ when custom plugins are enabled. examples: - ns_abc123/ max_custom_plugins: type: integer maximum: 100 minimum: 0 title: Max Custom Plugins description: >- Maximum number of custom plugins allowed for this namespace. 0 = custom plugins disabled (shared tier). Set to >0 for dedicated tiers to enable custom plugins. default: 0 max_custom_models: type: integer maximum: 50 minimum: 0 title: Max Custom Models description: >- Maximum number of custom model weights allowed for this namespace. 0 = custom models disabled (shared tier). Set to >0 for dedicated tiers to enable custom model uploads. default: 0 authorization: anyOf: - $ref: '#/components/schemas/NamespaceAuthorizationConfig' - type: 'null' description: >- Opt-in document-level authorization (external auth provider) for authorized retrieval. None or enabled=False (default) means the namespace is unchanged: no _acl enforcement and no authz calls. type: object title: NamespaceInfrastructure description: >- 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. ray_head_node_url and compute_tier were removed (2026-09-10): both were write-only on this model -- customer-settable via PATCH, published in the OpenAPI schema and both SDKs, and read by nothing. Advertising dedicated-Ray routing that does not exist is worse than advertising none, and wiring ray_head_node_url as a batch target would have let any write-scoped API key point Mixpeek's background workers at a URL the caller controls -- SSRF from the control plane, with credentials in what gets sent. ray_dashboard_url stays: it is genuinely wired as the namespace-level batch target (engine/jobs/services.py:_get_ray_dashboard_url), which is not the same surface and was audited separately. The per-namespace vector-store connection fields (the URL, the API key, its "provided" flag and the required collection name) were removed on 2026-09-26, when MVS became the only vector store. It addresses a namespace's vectors by namespace_id, so nothing read them. A stored document that still carries a removed key is accepted and ignored (see the deprecation validator below), never rejected. Examples: Namespace-level Ray dashboard override: NamespaceInfrastructure( ray_dashboard_url="http://ray-ns-dashboard:8265", max_concurrent_jobs=50 ) examples: - autoscaling_enabled: false description: Shared development namespace max_concurrent_jobs: 10 - autoscaling_enabled: true description: Dedicated production CPU cluster max_concurrent_jobs: 50 max_workers: 20 min_workers: 3 ray_cluster_id: ray_prod_cluster ray_dashboard_url: http://prod-dashboard:8265 NamespaceTrustedIssuer: properties: issuer: type: string minLength: 1 title: Issuer description: >- Exact value of the token's 'iss' claim, e.g. 'https://.supabase.co/auth/v1'. jwks_url: anyOf: - type: string minLength: 1 - type: 'null' title: Jwks Url description: >- URL of the provider's JSON Web Key Set, e.g. 'https://.supabase.co/auth/v1/.well-known/jwks.json'. Must be https outside local deployments. Set exactly one of jwks_url or jwks. jwks: anyOf: - additionalProperties: true type: object - type: 'null' title: Jwks description: >- The provider's public signing keys inline, as a JSON Web Key Set: {"keys": [...]}. Use it when the provider publishes no JWKS URL the API can reach. Tokens are verified against these keys with no network fetch, by 'kid' and the accepted algorithms. At most 10 keys; each needs a 'kid' and must be a public RSA or EC key. Private key members and symmetric ('oct') keys are refused. Keys are public and are returned in GET responses. Set exactly one of jwks_url or jwks. examples: - keys: - alg: ES256 crv: P-256 kid: key-1 kty: EC x: 'y': audience: anyOf: - items: type: string type: array - type: 'null' title: Audience description: >- Accepted values of the token's 'aud' claim (Supabase: ['authenticated']). When set, a token for another audience is refused. algorithms: items: type: string enum: - RS256 - RS384 - RS512 - ES256 - ES384 - PS256 type: array minItems: 1 title: Algorithms description: >- Signature algorithms accepted. Only asymmetric algorithms are supported, so a shared secret never leaves the provider. principal_claim: type: string minLength: 1 title: Principal Claim description: Claim that identifies the end user (the document owner). default: sub principal_prefix: type: string maxLength: 64 title: Principal Prefix description: >- Prefix added to the principal claim to form the principal stored as a document's owner, so users of different issuers cannot collide. default: 'jwt:' claim_filters: items: $ref: '#/components/schemas/NamespaceClaimFilter' type: array title: Claim Filters description: >- Claims applied as filters on every read. A token without one of these claims is refused. retrievers: items: type: string type: array title: Retrievers description: >- Retrievers (names or ids) these tokens may execute. Results are limited by claim_filters. Any other retriever is refused. collections: items: type: string type: array title: Collections description: >- Collections (names or ids) these tokens may read documents from, limited by claim_filters. Read-only. owner_writable_collections: items: type: string type: array title: Owner Writable Collections description: >- Collections (names or ids) where these tokens may create documents. A created document is owned by the token's principal; reads return the documents the principal owns or was granted, and only a principal with write access can change or delete a document. create_principals: additionalProperties: items: type: string type: array type: object title: Create Principals description: >- Optional create rule per owner-writable collection: collection (name or id) to the principals that may create documents in it, for example {'warnings': ['internal:true']}. A token holding none of the listed principals (its own principal or a group from group_claims) may not create or upsert documents there. Changes to existing documents still follow the document ACL. Collections not listed are unchanged. allowed_origins: items: type: string type: array title: Allowed Origins description: >- Browser origins allowed to send these tokens (fnmatch patterns such as 'https://*.example.com'). Empty allows any origin. group_claims: items: $ref: '#/components/schemas/NamespaceGroupClaim' type: array maxItems: 8 title: Group Claims description: >- Claims whose values become group principals of the token (e.g. 'brand:' from a brand claim). Documents in owner-writable collections whose ACL names a group are readable (read list) or writable (write list) by every token holding it, and the owner of a document may add groups to its ACL. admin_claim: anyOf: - $ref: '#/components/schemas/NamespaceAdminClaim' - type: 'null' description: >- A claim value (an internal or admin role) whose tokens are not held to claim_filters. Unset: every token is held to them. enabled: type: boolean title: Enabled description: False keeps the entry stored but refuses its tokens. default: true additionalProperties: false type: object required: - issuer title: NamespaceTrustedIssuer description: >- An identity provider whose end-user tokens this namespace accepts. A browser sends ``Authorization: Bearer `` with ``X-Namespace: ``. Mixpeek verifies the token's signature against ``jwks_url`` (or the inline ``jwks``) and its issuer, audience and expiry, then serves the request as a scoped principal: read-only by default, limited to the named retrievers and collections, with ``claim_filters`` applied to every read. NamespaceCostCapOverride: properties: daily_usd: anyOf: - type: number minimum: 0 - type: 'null' title: Daily Usd description: >- Cap in USD per UTC day of inference cost for this namespace. Required. null removes the cap, which needs Mixpeek support. examples: - 250 reason: type: string maxLength: 500 minLength: 10 title: Reason description: Why this namespace needs a cap other than its tier default. examples: - >- Nightly re-index of the full catalog, about $180/day, approved by finance owner: type: string maxLength: 200 minLength: 3 title: Owner description: >- Who is accountable for spend in this namespace, for example an email address. examples: - data-platform@example.com expires_at: anyOf: - type: string format: date-time - type: 'null' title: Expires At description: >- When the override lapses and the tier default applies again. Omit for no expiry. set_by: anyOf: - type: string - type: 'null' title: Set By description: 'Set by the server: the authenticated user who applied the override.' set_at: anyOf: - type: string format: date-time - type: 'null' title: Set At description: 'Set by the server: when the override was applied.' type: object required: - daily_usd - reason - owner title: NamespaceCostCapOverride description: >- An explicit daily inference cost cap for one namespace. Every namespace already has a cap from its organization's tier. An override replaces it and must say why and who is accountable. Setting one above the tier's self-serve maximum, or removing the cap with null, needs Mixpeek support. TieringOverride: properties: enabled: anyOf: - type: boolean - type: 'null' title: Enabled description: Turn tiering on or off here; unset inherits from above. idle_days: anyOf: - $ref: '#/components/schemas/TieringIdleDays' - type: 'null' description: Idle windows here; unset parts inherit from above. exempt: anyOf: - type: string - type: 'null' title: Exempt description: >- Opt out of tiering, with the reason (for example a legal hold). An exempt namespace or collection is never demoted. additionalProperties: false type: object title: TieringOverride description: A namespace's or collection's override of its data class's tiering. NamespacePin: properties: enabled: type: boolean title: Enabled description: Pin the namespace. false unpins it. default: true warm_query_encoder: type: boolean title: Warm Query Encoder description: >- While pinned, keep one replica of each query encoder this namespace's searches call running, so a search never waits for the encoder to start. Billed per replica-hour to this namespace as its own invoice line. Without it, encoders scale to zero when idle. default: false set_at: anyOf: - type: string format: date-time - type: 'null' title: Set At description: Read-only. When the pin was last changed. set_by: anyOf: - type: string - type: 'null' title: Set By description: Read-only. Who last changed the pin. additionalProperties: false type: object title: NamespacePin description: '``pinned`` on a namespace: the customer''s opt-in, stamped by the server.' BaseFeatureExtractorModel-Output: properties: feature_extractor_name: type: string title: Feature Extractor Name description: Name of the feature extractor version: type: string title: Version description: Version of the feature extractor (e.g., 'v1', 'v2') params: anyOf: - additionalProperties: true type: object - type: 'null' title: Params description: >- Optional extractor parameters that affect vector index configuration. Parameters set here are locked at namespace creation and determine vector dimensions in the vector store. Collections using this extractor must use compatible params. Example: {'model': 'siglip_base'} feature_extractor_id: type: string title: Feature Extractor Id description: >- Construct unique identifier for the feature extractor instance (name + version). readOnly: true type: object required: - feature_extractor_name - version - feature_extractor_id title: BaseFeatureExtractorModel description: Minimum feature extractor definition. PayloadIndexConfig-Output: properties: field_name: type: string maxLength: 255 minLength: 1 title: Field Name description: >- Name of the payload field to index. Must be unique within the namespace. Use dot notation for nested fields (e.g., 'metadata.title'). Cannot use protected system field names when is_protected=False. examples: - metadata.title - user_id - tags type: $ref: '#/components/schemas/PayloadSchemaType' description: >- Data type of the indexed field. Determines query capabilities and storage optimization. TEXT: Full-text search. KEYWORD: Exact matching, filtering. INTEGER/FLOAT: Range queries, sorting. DATETIME: Temporal queries. GEO: geospatial filtering — the geo_radius, geo_bounding_box and geo_polygon operators. Store the point as {lat, lon} or as a [lon, lat] GeoJSON array; a field holding a list of points matches if ANY point matches. NOTE: geo conditions are evaluated by a payload SCAN, not by this index — declaring GEO does not yet accelerate them, so AND a geo condition with a selective non-geo condition on a large collection. BOOL: Boolean filtering. UUID: Unique identifier matching. field_schema: anyOf: - $ref: '#/components/schemas/TextIndexParams' - $ref: '#/components/schemas/IntegerIndexParams' - $ref: '#/components/schemas/KeywordIndexParams' - $ref: '#/components/schemas/FloatIndexParams' - $ref: '#/components/schemas/GeoIndexParams' - $ref: '#/components/schemas/DatetimeIndexParams' - $ref: '#/components/schemas/UuidIndexParams' - $ref: '#/components/schemas/BoolIndexParams' - type: 'null' title: Field Schema description: >- Optional schema configuration for the index. If not provided, uses default parameters for the specified type. Different types support different parameters (e.g., KeywordIndexParams.is_tenant). is_protected: type: boolean title: Is Protected description: >- Whether this index is system-managed and cannot be modified by users. Protected indexes (is_protected=True) are created automatically by Mixpeek and are essential for internal operations like tenant isolation, lineage tracking, and document management. Users cannot create, modify, or delete protected indexes. User-created indexes always have is_protected=False. default: false type: object required: - field_name - type title: PayloadIndexConfig description: >- Configuration for a payload index. Defines the structure and behavior of a payload field index in vector store collections. Payload indexes enable efficient filtering and searching on document metadata. Protected Indexes: System-managed indexes (is_protected=True) cannot be modified or deleted by users. These are essential for Mixpeek's internal operations: - internal_id: Tenant isolation - namespace_id: Namespace scoping - collection_id, document_id: Document lineage - bucket_id, object_id, root_object_id, root_bucket_id, source_object_id: Object lineage - created_at, updated_at: Timestamps Use Cases: - Create custom metadata indexes for efficient filtering - Configure full-text search on text fields - Set up geospatial queries on location data - Enable range queries on numeric fields Requirements: - field_name: REQUIRED - Must be unique within the namespace - type: REQUIRED - Must match PayloadSchemaType enum - field_schema: OPTIONAL - Auto-generated from type if not provided - is_protected: OPTIONAL - Defaults to False (user-managed index) examples: - description: User-created text index for full-text search field_name: metadata.description is_protected: false type: text - description: User-created keyword index for exact filtering field_name: user_id is_protected: false type: keyword - description: System-managed protected index (created automatically) field_name: internal_id field_schema: is_tenant: true is_protected: true type: keyword NamespaceAuthorizationConfig: properties: enabled: type: boolean title: Enabled description: >- Master switch. False (default) = no authorization enforcement, namespace unchanged. True = document-level authorized retrieval is active for this namespace. default: false provider: type: string const: openfga title: Provider description: External authorization provider. Only OpenFGA is supported. default: openfga api_url: anyOf: - type: string - type: 'null' title: Api Url description: Base URL of the customer's OpenFGA HTTP API. examples: - https://openfga.customer.example.com - http://localhost:8080 store_id: anyOf: - type: string - type: 'null' title: Store Id description: OpenFGA store id holding the customer's relationship tuples. model_id: anyOf: - type: string - type: 'null' title: Model Id description: >- OpenFGA authorization-model id. When None, the store's latest model is used. api_token_secret_ref: anyOf: - type: string - type: 'null' title: Api Token Secret Ref description: >- Name of an organization-vault secret (OrganizationSecretsService) holding the OpenFGA bearer token. PREFERRED: the token is resolved from the encrypted org vault at call time and never stored in this config. Required for any non-local (https) OpenFGA deployment. api_token: anyOf: - type: string - type: 'null' title: Api Token description: >- DEPRECATED / dev-only plaintext bearer token. Rejected when enabled=True against a non-local OpenFGA URL — use api_token_secret_ref (org vault) instead. Allowed only for local dev (http:// or localhost), where the e2e OpenFGA runs without auth. object_type: type: string title: Object Type description: FGA object type that represents a Mixpeek document. default: document relation: type: string title: Relation description: OpenFGA relation that grants read/retrieve access. default: viewer user_type: type: string title: User Type description: FGA subject type for the acting principal (user:). default: user mode: type: string enum: - push - pull_list_objects - pull_batch_check - auto title: Mode description: >- push = filter on the synced _acl payload field (fast, eventually consistent). pull_list_objects = ListObjects->document_id pre-filter (strongly consistent, bounded sets). pull_batch_check = unfiltered search then BatchCheck post-filter (strongly consistent, any size). auto = ListObjects when the result is under list_objects_max, else fall back to BatchCheck post-filter. default: auto list_objects_max: type: integer maximum: 100000 minimum: 1 title: List Objects Max description: >- Max objects ListObjects may return before auto mode falls back to BatchCheck post-filter (avoids the ListObjects explosion). default: 1000 over_fetch_factor: type: integer maximum: 10 minimum: 1 title: Over Fetch Factor description: >- Post-filter (BatchCheck) over-fetch multiplier. Standard authorized-search guidance: over-fetch >=2x from the vector DB so that after dropping inaccessible documents the requested page is still full. Only applies in post-filter / auto-capped mode. default: 2 cache_ttl_seconds: type: integer maximum: 3600 minimum: 0 title: Cache Ttl Seconds description: TTL for cached authorization decisions (subject->allowed set). default: 30 type: object title: NamespaceAuthorizationConfig description: |- Opt-in external authorization config for document-level authorized retrieval. When ``enabled`` is False (the default) the namespace behaves EXACTLY as before: no ``_acl`` enforcement at retrieval, no ``_acl`` write at ingestion, no FGA calls. The whole feature is gated on this flag so a namespace that does not opt in is byte-for-byte unchanged. The customer runs their OWN OpenFGA; Mixpeek is a relying party. The document object id in OpenFGA must equal the Mixpeek ``document_id`` (e.g. ``document:doc_abc123``). At retrieval we enforce the configured ``relation`` for the acting subject. Enforcement is fail-closed: a document with no resolvable grant is excluded, never leaked. examples: - api_token_secret_ref: openfga_bearer_token api_url: https://openfga.customer.example.com enabled: true mode: auto object_type: document provider: openfga relation: viewer store_id: 01J0X... NamespaceClaimFilter: properties: claim: type: string minLength: 1 title: Claim description: >- Dotted path of the claim in the verified token, e.g. 'brands' or 'app_metadata.brands'. Its value (a string or a list of strings) is the set of allowed values. examples: - brands field: type: string minLength: 1 title: Field description: >- Document field the claim values must match, e.g. 'brand_id'. A document is visible only when this field holds one of the values. examples: - brand_id collections: items: type: string type: array title: Collections description: >- Collections (names or ids) this filter applies to. Empty applies it to every read. A retriever run reading any listed collection is held to it for all its results, and so is a run whose collection is templated. The scope narrows which documents the filter hides, not which calls need the claim: a token without the claim is refused on every call, including writes to collections this filter does not list. examples: - - scenes type: object required: - claim - field title: NamespaceClaimFilter description: One token claim applied as a document filter for end-user tokens. NamespaceGroupClaim: properties: claim: type: string minLength: 1 title: Claim description: >- Dotted path of the claim in the verified token, e.g. 'app_metadata.brands'. Each value (a string, number or boolean, or a list of them) becomes the group principal prefix + value. examples: - app_metadata.brands prefix: type: string maxLength: 64 minLength: 1 title: Prefix description: >- Prefix of the group principals, e.g. 'brand:' gives 'brand:'. A document whose ACL read or write list holds a group principal grants that access to every token holding it. examples: - 'brand:' additionalProperties: false type: object required: - claim - prefix title: NamespaceGroupClaim description: A token claim whose values become group principals for end-user tokens. NamespaceAdminClaim: properties: claim: type: string minLength: 1 title: Claim description: >- Dotted path of the claim in the verified token, e.g. 'app_metadata.internal' or 'app_metadata.roles'. examples: - app_metadata.internal values: items: type: string type: array minItems: 1 title: Values description: >- Claim values that mark an admin (booleans compare as 'true' and 'false'). A token whose claim holds one of them is not held to claim_filters: it reads and writes across every value of the namespace. Document ACLs still apply. examples: - - 'true' additionalProperties: false type: object required: - claim - values title: NamespaceAdminClaim description: A claim value that gives an end-user token reach across claim filters. TieringIdleDays: properties: cold: anyOf: - type: integer minimum: 1 - type: 'null' title: Cold description: Days without a use before the cold tier. frozen: anyOf: - type: integer minimum: 1 - type: 'null' title: Frozen description: Days without a use before the frozen tier. additionalProperties: false type: object title: TieringIdleDays PayloadSchemaType: type: string enum: - keyword - integer - float - bool - geo - datetime - text - uuid title: PayloadSchemaType description: Payload schema type. TextIndexParams: properties: type: type: string title: Type default: text tokenizer: $ref: '#/components/schemas/TokenizerType' default: word min_token_len: type: integer title: Min Token Len default: 2 max_token_len: type: integer title: Max Token Len default: 15 lowercase: type: boolean title: Lowercase default: true analyzer: anyOf: - type: string enum: - default - english - type: 'null' title: Analyzer description: >- How the BM25 keyword index splits and normalises the field's text, applied to the stored text and to the query alike. 'default': split on non-alphanumeric characters and lowercase. 'english': the same, then common English stopwords dropped and each word reduced to its Snowball English stem, so 'running' matches 'runs'. Unset keeps the field's current analyzer ('default' for a new field). Changing it reindexes the field. Used by lexical searches (feature_search `lexical`, `lexical_field`). type: object title: TextIndexParams description: Configuration for text index. IntegerIndexParams: properties: type: type: string title: Type default: integer lookup: type: boolean title: Lookup default: true range: type: boolean title: Range default: true type: object title: IntegerIndexParams description: Configuration for integer index. KeywordIndexParams: properties: type: type: string title: Type default: keyword is_tenant: type: boolean title: Is Tenant default: false type: object title: KeywordIndexParams description: Configuration for keyword index. FloatIndexParams: properties: type: type: string title: Type default: float type: object title: FloatIndexParams description: Configuration for float index. GeoIndexParams: properties: type: type: string title: Type default: geo type: object title: GeoIndexParams description: Configuration for geo index. DatetimeIndexParams: properties: type: type: string title: Type default: datetime type: object title: DatetimeIndexParams description: Configuration for datetime index. UuidIndexParams: properties: type: type: string title: Type default: uuid is_tenant: type: boolean title: Is Tenant default: false type: object title: UuidIndexParams description: Configuration for UUID index. BoolIndexParams: properties: type: type: string title: Type default: bool type: object title: BoolIndexParams description: Configuration for boolean index. TokenizerType: type: string enum: - word - whitespace - prefix - multilingual title: TokenizerType description: Tokenizer type. securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.