Clone Taxonomy

Headers

Authorization

string

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

X-Namespace

string

REQUIRED: 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'

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

description

string | null

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

Example:

"Cloned from product_tags with updated retriever"

config

FlatTaxonomyConfig · object

OPTIONAL. Override taxonomy configuration. If omitted, copies from source taxonomy. This allows you to change retriever_id, input_mappings, enrichment_fields, or collection hierarchy.

FlatTaxonomyConfig
HierarchicalTaxonomyConfig

Show child attributes

config.retriever_id

string

required

The retriever to use for matching against the source collection.

config.input_mappings

InputMapping · object[]

required

Input mappings defining how to construct retriever inputs.

Show child attributes

config.input_mappings.input_key

string

required

Key used in the constructed inputs payload.

config.input_mappings.source_type

enum<string> | null

Source of the value (payload, literal, vector).

Available options:

payload,

literal,

vector

config.input_mappings.path

string | null

Dot-notation path inside payload/vector when source_type is PAYLOAD or VECTOR.

config.input_mappings.override

any | null

Static value used when source_type is LITERAL. Overrides any path.

config.source_collection

SourceCollection · object

required

The single source collection for this flat taxonomy.

Show child attributes

config.source_collection.collection_id

string

required

The ID of the source collection for the taxonomy.

config.source_collection.enrichment_fields

EnrichmentField · object[] | null

Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied.

Show child attributes

config.source_collection.enrichment_fields.field_path

string

required

Dot-notation path of the field to copy from the taxonomy node.

config.source_collection.enrichment_fields.target_field

string | null

Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label → visual_style).

Example:

"visual_style"

config.source_collection.enrichment_fields.merge_mode

enum<string>

default:replace

Whether to overwrite the target's value or append (for arrays).

Available options:

replace,

append

config.taxonomy_type

string

default:flat

Discriminator identifying this as a flat taxonomy.

Allowed value: "flat"

config.step_analytics

StepAnalyticsConfig · object

Optional configuration for step transition analytics. Enables tracking how documents progress through taxonomy labels over time (e.g., email thread progression from 'inquiry' to 'closed_won'). If not provided, only basic assignment events are logged.

Show child attributes

config.step_analytics.timestamp_field

string

required

Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')

config.step_analytics.sequence_id_field

string

required

Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')

config.step_analytics.step_key_source

enum<string>

default:assignment_label

How to determine the 'step' for each document (label, node_id, or custom field)

Available options:

assignment_label,

assignment_node_id,

field_path

config.step_analytics.step_key_field_path

string | null

Required if step_key_source='field_path'. Dot-notation path to step value in document.

Example:

"metadata.workflow_stage"

config.step_analytics.covariates

CovariateConfig · object[]

Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)

Maximum array length: 20

Show child attributes

config.step_analytics.covariates.field_path

string

required

Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')

config.step_analytics.covariates.covariate_type

enum<string>

required

Type of covariate determines analysis strategy (categorical/numeric/embedding/cluster)

Available options:

categorical,

numeric,

embedding,

cluster_id

config.step_analytics.covariates.name

string

required

Human-readable name for this covariate in analytics results

Required string length: 1 - 100

config.step_analytics.covariates.binning_strategy

enum<string> | null

default:quartiles

How to bin numeric values for lift analysis (only used for NUMERIC type)

Available options:

quartiles,

deciles,

custom

config.step_analytics.covariates.clustering_method

enum<string> | null

default:kmeans

Clustering algorithm for embedding analysis (only used for EMBEDDING type)

Available options:

kmeans,

hdbscan

config.step_analytics.covariates.n_clusters

integer | null

default:10

Number of clusters for embedding-based predictors (only used for EMBEDDING type)

Required range: 2 <= x <= 100

config.step_analytics.max_sequence_duration_days

integer | null

Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues.

Required range: 1 <= x <= 365

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

taxonomy.taxonomy_name

string

required

A unique name for the taxonomy within the namespace.

taxonomy.config

FlatTaxonomyConfig · object

required

Configuration specific to the taxonomy type.

FlatTaxonomyConfig
HierarchicalTaxonomyConfig

Show child attributes

taxonomy.config.retriever_id

string

required

The retriever to use for matching against the source collection.

taxonomy.config.input_mappings

InputMapping · object[]

required

Input mappings defining how to construct retriever inputs.

Show child attributes

taxonomy.config.input_mappings.input_key

string

required

Key used in the constructed inputs payload.

taxonomy.config.input_mappings.source_type

enum<string> | null

Source of the value (payload, literal, vector).

Available options:

payload,

literal,

vector

taxonomy.config.input_mappings.path

string | null

Dot-notation path inside payload/vector when source_type is PAYLOAD or VECTOR.

taxonomy.config.input_mappings.override

any | null

Static value used when source_type is LITERAL. Overrides any path.

taxonomy.config.source_collection

SourceCollection · object

required

The single source collection for this flat taxonomy.

Show child attributes

taxonomy.config.source_collection.collection_id

string

required

The ID of the source collection for the taxonomy.

taxonomy.config.source_collection.enrichment_fields

EnrichmentField · object[] | null

Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied.

Show child attributes

taxonomy.config.source_collection.enrichment_fields.field_path

string

required

Dot-notation path of the field to copy from the taxonomy node.

taxonomy.config.source_collection.enrichment_fields.target_field

string | null

Example:

"visual_style"

taxonomy.config.source_collection.enrichment_fields.merge_mode

enum<string>

default:replace

Whether to overwrite the target's value or append (for arrays).

Available options:

replace,

append

taxonomy.config.taxonomy_type

string

default:flat

Discriminator identifying this as a flat taxonomy.

Allowed value: "flat"

taxonomy.config.step_analytics

StepAnalyticsConfig · object

Show child attributes

taxonomy.config.step_analytics.timestamp_field

string

required

Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')

taxonomy.config.step_analytics.sequence_id_field

string

required

Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')

taxonomy.config.step_analytics.step_key_source

enum<string>

default:assignment_label

How to determine the 'step' for each document (label, node_id, or custom field)

Available options:

assignment_label,

assignment_node_id,

field_path

taxonomy.config.step_analytics.step_key_field_path

string | null

Required if step_key_source='field_path'. Dot-notation path to step value in document.

Example:

"metadata.workflow_stage"

taxonomy.config.step_analytics.covariates

CovariateConfig · object[]

Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)

Maximum array length: 20

Show child attributes

taxonomy.config.step_analytics.covariates.field_path

string

required

Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')

taxonomy.config.step_analytics.covariates.covariate_type

enum<string>

required

Type of covariate determines analysis strategy (categorical/numeric/embedding/cluster)

Available options:

categorical,

numeric,

embedding,

cluster_id

taxonomy.config.step_analytics.covariates.name

string

required

Human-readable name for this covariate in analytics results

Required string length: 1 - 100

taxonomy.config.step_analytics.covariates.binning_strategy

enum<string> | null

default:quartiles

How to bin numeric values for lift analysis (only used for NUMERIC type)

Available options:

quartiles,

deciles,

custom

taxonomy.config.step_analytics.covariates.clustering_method

enum<string> | null

default:kmeans

Clustering algorithm for embedding analysis (only used for EMBEDDING type)

Available options:

kmeans,

hdbscan

taxonomy.config.step_analytics.covariates.n_clusters

integer | null

default:10

Number of clusters for embedding-based predictors (only used for EMBEDDING type)

Required range: 2 <= x <= 100

taxonomy.config.step_analytics.max_sequence_duration_days

integer | null

Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues.

Required range: 1 <= x <= 365

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

taxonomy.taxonomy_id

string

Unique identifier for the taxonomy

taxonomy.version

integer

default:1

Monotonic version number of the taxonomy configuration

Required range: x >= 1

taxonomy.description

string | null

Optional human-readable description.

taxonomy.retriever_id

string | null

Optional taxonomy-level retriever (prefer per-layer).

taxonomy.input_mappings

InputMapping · object[] | null

Optional taxonomy-level inputs (prefer per-layer).

Show child attributes

taxonomy.input_mappings.input_key

string

required

Key used in the constructed inputs payload.

taxonomy.input_mappings.source_type

enum<string> | null

Source of the value (payload, literal, vector).

Available options:

payload,

literal,

vector

taxonomy.input_mappings.path

string | null

Dot-notation path inside payload/vector when source_type is PAYLOAD or VECTOR.

taxonomy.input_mappings.override

any | null

Static value used when source_type is LITERAL. Overrides any path.

taxonomy.ready

boolean

default:true

Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies.

taxonomy.created_at

string<date-time>

Creation timestamp for this taxonomy record

taxonomy.metadata

Metadata · object

Additional user-defined metadata for the taxonomy

source_taxonomy_id

string

required

ID of the source taxonomy that was cloned.

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Headers

Path Parameters

Body

Response