--- title: "Clone Namespace" method: POST path: "/v1/namespaces/{namespace_identifier}/clone" tags: ["Namespace Clone"] --- # Clone Namespace `POST /v1/namespaces/{namespace_identifier}/clone` Clone a namespace with all its data. **What gets cloned:** - Namespace configuration (extractors, payload indexes) - Buckets (metadata, references same S3 files) - Collections (full copy of all vectors/embeddings) - Retrievers (pipeline configuration) **Use Cases:** - Create staging environment from production - Backup namespace with all data - Fork namespace for experimentation **For config-only copy (no data), use templates instead:** - POST /templates/namespaces/from-namespace/{id} - POST /templates/namespaces/{template_id}/instantiate ## Path parameters - `namespace_identifier` string, required — Source namespace ID or name to clone from ## Request body - CloneNamespaceRequest — Request to clone a namespace with all its data. Clone creates a full copy of a namespace including: - Namespace configuration (extractors, indexes) - Buckets (metadata, references same S3 files) - Collections (full copy of all vectors/embeddings) - Retrievers (pipeline configuration) **Use Cases:** - Create staging environment from production - Backup namespace with all data - Fork namespace for experimentation **For config-only copy (no data), use templates instead:** - POST /templates/namespaces/from-namespace/{id} - POST /templates/namespaces/{template_id}/instantiate - `namespace_name` string, required — Name for the cloned namespace (must be unique) - `include_resources` CloneNamespaceResourcesConfig — Configuration for which resources to include in clone. - `collections` boolean — Include collections (with all embeddings/vectors) - `retrievers` boolean — Include retrievers - `taxonomies` boolean — Include taxonomies - `description` string, nullable — Override description. If omitted, copies from source. - `source_organization_id` string, nullable — Source org ID for cross-org cloning (admin only). ## Response `200` Successful Response - CloneNamespaceResponse — Response after initiating namespace clone. - `namespace` NamespaceModel, required — Namespace model. - `object` string — Resource type identifier, always 'namespace'. - `namespace_id` string — Unique identifier for the namespace. Format: ns_. - `namespace_name` string, 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. - `infrastructure` NamespaceInfrastructureOutput — 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 ) - `ray_cluster_id` string, nullable — Dedicated Ray cluster identifier for this namespace. - `ray_head_node_url` string, nullable — Ray head node address for job submission (ray://host:port). - `ray_dashboard_url` string, nullable — Ray dashboard URL for monitoring (http://host:8265). - `qdrant_url` string, nullable — Dedicated vector store URL for this namespace. When set, this namespace uses its own vector store instance instead of organization or shared infrastructure. Format: http://hostname:port or https://hostname:port. REQUIRED when compute_tier is DEDICATED_CPU or DEDICATED_GPU. NOT REQUIRED for SHARED tier (inherits from organization or uses shared). - `qdrant_api_key_provided` boolean, nullable — Indicates whether a vector store API key has been configured. The key itself is never returned. - `qdrant_collection` string, required — Vector collection backing this namespace's vector data. - `s3_vector_bucket` string, nullable — S3 Vectors bucket name for vector tiering. When set, vectors are durably stored in S3. - `compute_tier` 'shared' | 'dedicated_cpu' | 'dedicated_gpu' — Available compute tiers for namespace workloads. Compute tiers determine the infrastructure resources allocated to a namespace for ingestion pipelines, clustering, and other data processing operations. Tiers: SHARED: Multi-tenant infrastructure with dynamic resource allocation. - Best for: Development, testing, low-volume production workloads - Resources: Shared CPU and memory pool - Cost: Lowest cost option, pay-per-use credits - SLA: Best-effort availability DEDICATED_CPU: Single-tenant CPU compute nodes. - Best for: Production workloads requiring consistent performance - Resources: Reserved CPU cores and memory - Cost: Fixed monthly cost plus usage credits - SLA: 99.9% uptime guarantee DEDICATED_GPU: Single-tenant GPU-accelerated compute nodes. - Best for: Video processing, embedding generation, ML inference - Resources: Reserved GPU(s), CPU cores, and memory - Cost: Premium pricing, fixed monthly cost plus usage credits - SLA: 99.9% uptime guarantee Examples: - Use SHARED for development and staging environments - Use DEDICATED_CPU for production document processing pipelines - Use DEDICATED_GPU for large-scale video ingestion and analysis - `max_concurrent_jobs` integer — Maximum concurrent Ray jobs allowed for the namespace. - `autoscaling_enabled` boolean — Toggle autoscaling for dedicated clusters (ignored for shared tier). - `min_workers` integer — Lower bound for Ray workers when autoscaling is enabled. - `max_workers` integer — Upper bound for Ray workers when autoscaling is enabled. - `gpu_type` string, nullable — GPU type for dedicated GPU clusters (e.g. A100, T4). - `gpus_per_worker` integer — Number of GPUs allocated to each Ray worker when using GPUs. - `compute_profiles` object — 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. - `s3_plugin_bucket` string — S3 bucket for storing custom plugins and model weights. - `s3_plugin_prefix` string, nullable — S3 prefix for namespace-scoped plugin storage. Format: {namespace_id}/ when custom plugins are enabled. - `max_custom_plugins` integer — 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. - `max_custom_models` integer — 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. - `authorization` NamespaceAuthorizationConfig — 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. - `enabled` boolean — Master switch. False (default) = no authorization enforcement, namespace unchanged. True = document-level authorized retrieval is active for this namespace. - `provider` 'openfga' — External authorization provider. Only OpenFGA is supported. - `api_url` string, nullable — Base URL of the customer's OpenFGA HTTP API. - `store_id` string, nullable — OpenFGA store id holding the customer's relationship tuples. - `model_id` string, nullable — OpenFGA authorization-model id. When None, the store's latest model is used. - `api_token_secret_ref` string, nullable — 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` string, nullable — 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` string — FGA object type that represents a Mixpeek document. - `relation` string — OpenFGA relation that grants read/retrieve access. - `user_type` string — FGA subject type for the acting principal (user:). - `mode` 'push' | 'pull_list_objects' | 'pull_batch_check' | 'auto' — 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. - `list_objects_max` integer — Max objects ListObjects may return before auto mode falls back to BatchCheck post-filter (avoids the ListObjects explosion). - `over_fetch_factor` integer — 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. - `cache_ttl_seconds` integer — TTL for cached authorization decisions (subject->allowed set). - `cluster_id` string, 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 - `description` string, nullable — Description of the namespace - `feature_extractors` BaseFeatureExtractorModelOutput[] — List of feature extractors configured for this namespace - `feature_extractor_name` string, required — Name of the feature extractor - `version` string, required — Version of the feature extractor (e.g., 'v1', 'v2') - `params` object, nullable — Optional extractor parameters that affect vector index configuration. Parameters set here are locked at namespace creation and determine vector dimensions in Qdrant. Collections using this extractor must use compatible params. Example: {'model': 'siglip_base'} - `feature_extractor_id` string, required — Construct unique identifier for the feature extractor instance (name + version). - `payload_indexes` PayloadIndexConfigOutput[], nullable — Custom payload indexes configured for this namespace - `field_name` string, required — 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. - `type` 'keyword' | 'integer' | 'float' | 'bool' | 'geo' | 'datetime' | 'text' | 'uuid', required — Payload schema type. - `field_schema` union — 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). - TextIndexParams — Configuration for text index. - `type` string - `tokenizer` 'word' | 'whitespace' | 'prefix' | 'multilingual' — Tokenizer type. - `min_token_len` integer - `max_token_len` integer - `lowercase` boolean - IntegerIndexParams — Configuration for integer index. - `type` string - `lookup` boolean - `range` boolean - KeywordIndexParams — Configuration for keyword index. - `type` string - `is_tenant` boolean - FloatIndexParams — Configuration for float index. - `type` string - GeoIndexParams — Configuration for geo index. - `type` string - DatetimeIndexParams — Configuration for datetime index. - `type` string - UuidIndexParams — Configuration for UUID index. - `type` string - `is_tenant` boolean - BoolIndexParams — Configuration for boolean index. - `type` string - `is_protected` boolean — 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. - `payload_index_count` integer, 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 (MS-833: 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, nullable — Total number of documents in this namespace - `bucket_count` integer, nullable — Total number of buckets in this namespace - `collection_count` integer, nullable — Total number of collections in this namespace - `object_count` integer, nullable — Total number of objects across all buckets in this namespace - `auto_create_indexes` boolean — 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. - `vector_inference_map` object, 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_indexes` boolean, nullable — Creation-time marker for BYO vector-name handling (SP-263). 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, 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_configs` object[], 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. - `qdrant_status` object, nullable — 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. - `clone_status` string, 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_error` string, nullable — Error detail when clone_status='failed'; null otherwise. - `source_namespace_id` string, nullable — For a cloned namespace, the source (golden/sample) namespace id it was cloned from. - `namespace_ready` boolean — ALWAYS PRESENT (BACKE-3008). True only after the server CONFIRMED this namespace is usable: its vector collection exists and is reachable (a served live count, the MI-2947 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, nullable — When the namespace was created - `updated_at` string, date-time, nullable — When the namespace was last updated - `expires_at` string, date-time, nullable — 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. - `source_namespace_id` string, required — Source namespace that was cloned - `status` string — Clone status: 'cloning', 'ready', or 'failed' - `task_id` string, nullable — Task ID for tracking clone progress - `cloned_resources` ClonedResourceSummary — Summary of cloned resources. - `collections` integer — Collections cloned - `retrievers` integer — Retrievers cloned - `taxonomies` integer — Taxonomies cloned - `buckets` integer — Buckets cloned - `objects` integer — Objects cloned - `points` integer — Vector points cloned - `primary_retriever_id` string, nullable — Pre-allocated retriever ID for the primary cloned retriever. Present immediately so callers can navigate to the retriever detail page while the background task hydrates the rest of the data. None if source namespace has no retrievers. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error --- [API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/220a3b263fda/schema)