Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Taxonomies

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

Path parameters

taxonomy_identifierstring required

Source taxonomy ID or name to clone.

Source taxonomy ID or name to clone.

Request body

taxonomy_namestring required

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

descriptionstring nullable

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

Example request

{
  "example_desc": "Clone with just a new name (exact copy)",
  "taxonomy_name": "product_tags_backup"
}

Response

Successful Response

source_taxonomy_idstring required

ID of the source taxonomy that was cloned.

Example response

{
  "taxonomy": {
    "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"
  }
}