Skip to main content
POST
/
v1
/
taxonomies
/
{taxonomy_identifier}
/
clone
Clone Taxonomy
curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone \
  --header 'Content-Type: application/json' \
  --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"
  }
}
'
{
  "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>"
}

Headers

​
Authorization
string

Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Example:

"Bearer YOUR_MIXPEEK_API_KEY"

​
authorization
string
​
X-Namespace
string

Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'. Falls back to ?namespace= query parameter if the header is omitted.

Examples:

"ns_abc123def456"

"production"

"my-namespace"

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.

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

Successful Response

Response after cloning a taxonomy.

​
taxonomy
TaxonomyModel · object
required

Cloned taxonomy configuration with new taxonomy_id.

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.