Clone Taxonomy

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone \
  --header 'Authorization: Bearer <token>' \
  --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"
  }
}
'

import requests

url = "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone"

	payload := strings.NewReader("{\n  \"taxonomy_name\": \"<string>\",\n  \"description\": \"Cloned from product_tags with updated retriever\",\n  \"config\": {\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip_vit_l_14\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"retriever_id\": \"ret_clip_v1\",\n    \"source_collection\": {\n      \"collection_id\": \"col_products_v1\",\n      \"enrichment_fields\": [\n        {\n          \"field_path\": \"metadata.tags\",\n          \"merge_mode\": \"append\"\n        }\n      ]\n    },\n    \"taxonomy_type\": \"flat\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"taxonomy_name\": \"<string>\",\n  \"description\": \"Cloned from product_tags with updated retriever\",\n  \"config\": {\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip_vit_l_14\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"retriever_id\": \"ret_clip_v1\",\n    \"source_collection\": {\n      \"collection_id\": \"col_products_v1\",\n      \"enrichment_fields\": [\n        {\n          \"field_path\": \"metadata.tags\",\n          \"merge_mode\": \"append\"\n        }\n      ]\n    },\n    \"taxonomy_type\": \"flat\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"taxonomy_name\": \"<string>\",\n  \"description\": \"Cloned from product_tags with updated retriever\",\n  \"config\": {\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip_vit_l_14\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"retriever_id\": \"ret_clip_v1\",\n    \"source_collection\": {\n      \"collection_id\": \"col_products_v1\",\n      \"enrichment_fields\": [\n        {\n          \"field_path\": \"metadata.tags\",\n          \"merge_mode\": \"append\"\n        }\n      ]\n    },\n    \"taxonomy_type\": \"flat\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

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:

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

POST

taxonomies

{taxonomy_identifier}

clone

Clone Taxonomy

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone \
  --header 'Authorization: Bearer <token>' \
  --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"
  }
}
'

import requests

url = "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone"

	payload := strings.NewReader("{\n  \"taxonomy_name\": \"<string>\",\n  \"description\": \"Cloned from product_tags with updated retriever\",\n  \"config\": {\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip_vit_l_14\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"retriever_id\": \"ret_clip_v1\",\n    \"source_collection\": {\n      \"collection_id\": \"col_products_v1\",\n      \"enrichment_fields\": [\n        {\n          \"field_path\": \"metadata.tags\",\n          \"merge_mode\": \"append\"\n        }\n      ]\n    },\n    \"taxonomy_type\": \"flat\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"taxonomy_name\": \"<string>\",\n  \"description\": \"Cloned from product_tags with updated retriever\",\n  \"config\": {\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip_vit_l_14\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"retriever_id\": \"ret_clip_v1\",\n    \"source_collection\": {\n      \"collection_id\": \"col_products_v1\",\n      \"enrichment_fields\": [\n        {\n          \"field_path\": \"metadata.tags\",\n          \"merge_mode\": \"append\"\n        }\n      ]\n    },\n    \"taxonomy_type\": \"flat\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/clone")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"taxonomy_name\": \"<string>\",\n  \"description\": \"Cloned from product_tags with updated retriever\",\n  \"config\": {\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip_vit_l_14\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"retriever_id\": \"ret_clip_v1\",\n    \"source_collection\": {\n      \"collection_id\": \"col_products_v1\",\n      \"enrichment_fields\": [\n        {\n          \"field_path\": \"metadata.tags\",\n          \"merge_mode\": \"append\"\n        }\n      ]\n    },\n    \"taxonomy_type\": \"flat\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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

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.

Create Taxonomy Version Delete Taxonomy

Organization

Namespaces

Buckets

Feature Extractors

Batch Queue

Collections

Documents

Retrievers

Taxonomies

Clusters

Triggers

Alerts

Webhooks

Apps

Agent Sessions

Annotations

Templates

Manifest

Discovery

Analytics

Notifications

Tasks

Inference

Resource Search

Pricing

Clone Taxonomy

Authorizations

Path Parameters

Body

Response