Clone Taxonomy

Clone a taxonomy with optional modifications.

Purpose: Creates a NEW taxonomy (with new ID) based on an existing one. This is the recommended way to iterate on taxonomy designs when you need to modify core logic that PATCH doesn’t allow (config, retriever_id, input_mappings).

Clone vs PATCH vs Template:

• PATCH: Update metadata only (name, description, metadata)
• Clone: Copy and modify core logic (config, retriever, collections)
• Template: Start from a pre-configured pattern (for new projects)

Common Use Cases:

• Fix configuration errors without losing join history
• Change retriever or input mappings
• Modify enrichment fields or collection configuration
• Test modifications before replacing production taxonomy
• Create variants for different datasets

How it works:

1. Source taxonomy is copied
2. You provide a new name (REQUIRED)
3. Optionally override any other fields (description, config)
4. A new taxonomy is created with a new ID
5. Original taxonomy remains unchanged

POST /v1/taxonomies/{taxonomy_identifier}/clone

Clone Taxonomy

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "taxonomy_name": "<string>",
  "description": "Cloned from product_tags with updated retriever",
  "config": {
    "input_mappings": [
      {
        "input_key": "image_vector",
        "path": "features.clip_vit_l_14",
        "source_type": "vector"
      }
    ],
    "retriever_id": "ret_clip_v1",
    "source_collection": {
      "collection_id": "col_products_v1",
      "enrichment_fields": [
        {
          "field_path": "metadata.tags",
          "merge_mode": "append"
        }
      ]
    },
    "taxonomy_type": "flat"
  }
}
'

201

{
  "taxonomy": {
    "taxonomy_name": "<string>",
    "config": {
      "input_mappings": [
        {
          "input_key": "image_vector",
          "path": "features.clip_vit_l_14",
          "source_type": "vector"
        }
      ],
      "retriever_id": "ret_clip_v1",
      "source_collection": {
        "collection_id": "col_products_v1",
        "enrichment_fields": [
          {
            "field_path": "metadata.tags",
            "merge_mode": "append"
          }
        ]
      },
      "taxonomy_type": "flat"
    },
    "taxonomy_id": "<string>",
    "version": 1,
    "description": "<string>",
    "retriever_id": "<string>",
    "input_mappings": [
      {
        "input_key": "<string>",
        "path": "<string>",
        "override": "<unknown>"
      }
    ],
    "ready": true,
    "created_at": "2023-11-07T05:31:56Z",
    "metadata": {}
  },
  "source_taxonomy_id": "<string>"
}

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 header returns 403; an invalid or revoked key returns 401.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

taxonomy_identifier · string · required

Source taxonomy ID or name to clone.

Body

application/json

Request to clone a taxonomy with optional modifications.

Purpose: Cloning creates a NEW taxonomy (with new ID) based on an existing one, allowing you to make changes that aren't allowed via PATCH (config, retriever_id, collections). This is the recommended way to iterate on taxonomy designs.

Clone vs Template vs Version:

• Clone: Copy THIS taxonomy and modify it (for iteration/fixes)
• Template: Create taxonomy from a reusable pattern (for new projects)
• Version: (Not implemented) - Use clone instead

Use Cases:

• Fix configuration errors without losing join history
• Change retriever or input mappings
• Change target collections
• Test modifications before replacing production taxonomy
• Create variants for different datasets

All fields are OPTIONAL:

• Omit a field to keep the original value
• Provide a field to override the original value
• taxonomy_name is REQUIRED (clones must have unique names)

taxonomy_name · string · required

REQUIRED. Name for the cloned taxonomy. Must be unique and different from the source taxonomy.

Minimum string length: 1

Examples:

"product_tags_v2"

"org_hierarchy_strict"

description · string | null

OPTIONAL. Description override. If omitted, copies from source taxonomy.

Example:

"Cloned from product_tags with updated retriever"

config · FlatTaxonomyConfig · object

Configuration for a flat taxonomy - single source collection with one retriever.

FlatTaxonomyConfig

HierarchicalTaxonomyConfig

Show child attributes

Example:

{
  "input_mappings": [
    {
      "input_key": "image_vector",
      "path": "features.clip_vit_l_14",
      "source_type": "vector"
    }
  ],
  "retriever_id": "ret_clip_v1",
  "source_collection": {
    "collection_id": "col_products_v1",
    "enrichment_fields": [
      {
        "field_path": "metadata.tags",
        "merge_mode": "append"
      }
    ]
  },
  "taxonomy_type": "flat"
}

Response

201

application/json

Successful Response

Response after cloning a taxonomy.

taxonomy · TaxonomyModel · object · required

Cloned taxonomy configuration with new taxonomy_id.

Show child attributes

Examples:

{
  "config": {
    "default_input_mappings": [
      {
        "input_key": "image_vector",
        "path": "features.clip_vit_l_14",
        "source_type": "vector"
      }
    ],
    "default_retriever_id": "ret_clip_v1",
    "source_collection": { "collection_id": "col_products_v1" },
    "taxonomy_type": "flat"
  },
  "namespace_id": "ns_123",
  "taxonomy_name": "product_tags",
  "taxonomy_type": "flat"
}

{
  "config": {
    "build_mode": "explicit",
    "default_input_mappings": [
      {
        "input_key": "face_vec",
        "path": "features.face",
        "source_type": "vector"
      }
    ],
    "default_retriever_id": "ret_face_v1",
    "hierarchical_nodes": [
      { "collection_id": "col_employees_v1" },
      {
        "collection_id": "col_executives_v1",
        "parent_collection_id": "col_employees_v1"
      }
    ],
    "taxonomy_type": "hierarchical"
  },
  "namespace_id": "ns_123",
  "taxonomy_name": "org_hierarchy",
  "taxonomy_type": "hierarchical"
}

source_taxonomy_id · string · required

ID of the source taxonomy that was cloned.