Skip to main content
POST
Clone 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

Source namespace ID or name to clone from

Body

application/json

Keys this body does not declare are ignored, and the response's warnings name them, until 2026-11-02; from 2026-11-02 they are refused with 422 extra_forbidden naming the accepted keys.

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 a config-only copy (no data): export the namespace with POST /v1/manifest/export and apply the manifest with POST /v1/manifest/apply.

namespace_name
string
required

Name for the cloned namespace (must be unique)

Minimum string length: 1
Examples:

"production_staging"

"backup_2024_01"

include_resources
CloneNamespaceResourcesConfig · object | null

Which resources to include. Defaults to collections + retrievers.

description
string | null

Override description. If omitted, copies from source.

Example:

"Staging clone from production"

source_organization_id
string | null

Source org ID for cross-org cloning (admin only).

Example:

"org_abc123"

mode
enum<string>
default:copy

'copy' writes every vector into the new namespace. 'branch' will make a copy-on-write fork that shares the source's storage until either side writes; it is not available yet and is refused, naming what it waits on.

Available options:
copy,
branch
Example:

"copy"

ttl_seconds
integer | null

Time-to-live in seconds for the new namespace, as on namespace create: it is deleted automatically after this duration. Omit for no expiry.

Required range: x >= 60
Example:

86400

Response

Successful Response

Response after initiating namespace clone.

namespace
NamespaceModel · object
required

Cloned namespace with new namespace_id

source_namespace_id
string
required

Source namespace that was cloned

status
string
default:cloning

Clone status: 'cloning', 'ready', or 'failed'

task_id
string | null

Task ID for tracking clone progress

cloned_resources
ClonedResourceSummary · object | null

Summary of cloned resources (present when ready)

primary_retriever_id
string | null

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.