---
title: "Partially Update Taxonomy"
method: PATCH
path: "/v1/taxonomies/{taxonomy_identifier}"
tags: ["Taxonomies"]
---

# Partially Update Taxonomy

`PATCH /v1/taxonomies/{taxonomy_identifier}`

Update a taxonomy's metadata.

    **Metadata Only Updates:**
    This endpoint allows updating ONLY metadata fields. Core taxonomy logic is immutable
    to ensure consistency for join history and dependent resources.

    **Fields You CAN Update:**
    - taxonomy_name: Rename the taxonomy
    - description: Update documentation
    - metadata: Update custom metadata

    **Fields You CANNOT Update:**
    - config: Taxonomy configuration (retriever_id, input_mappings, collections)
    - taxonomy_type: Type (flat vs hierarchical)

    **Need to Modify Core Logic?**
    Use POST /{taxonomy_identifier}/clone instead to modify configuration,
    retriever_id, input_mappings, or collections.

## Path parameters

- `taxonomy_identifier` string, required — Taxonomy ID or name

## Request body

- PatchTaxonomyRequest — Request to update a taxonomy's metadata. **IMPORTANT: Partial Updates with Controlled Mutability** This endpoint allows updating ONLY metadata fields. Core taxonomy logic is immutable to ensure consistency for join history and dependent resources. **✅ Fields You CAN Update (Metadata Only):** - `taxonomy_name`: Rename the taxonomy - `description`: Update documentation - `metadata`: Update custom metadata fields **❌ Fields You CANNOT Update (Immutable Core Logic):** - `config`: Taxonomy configuration (retriever_id, input_mappings, collections, hierarchy) - `taxonomy_type`: Type (flat vs hierarchical) - `retriever_id`: Associated retriever - `input_mappings`: Field mappings - `enrichment_fields`: Enrichment configuration **Need to Modify Core Logic?** Use POST /taxonomies/{taxonomy_id}/clone instead. Cloning creates a new taxonomy with a new ID, allowing you to: - Change retriever or input mappings - Modify enrichment fields - Update collection configuration - Change taxonomy hierarchy **Behavior:** - All fields are OPTIONAL - provide only what you want to update - Empty updates (no fields provided) will be rejected with 400 error - Original taxonomy remains unchanged (no destructive operations) **Why This Design?** - Join history is tied to specific taxonomy configuration - Changing retriever would invalidate previous joins - Version tracking enables auditing and rollback
  - `taxonomy_name` string, nullable — Updated name for the taxonomy
  - `description` string, nullable — Updated description for the taxonomy
  - `metadata` object, nullable — Updated metadata for the taxonomy

## Response `200`

Successful Response

- TaxonomyResponse — Response model for a taxonomy.
  - `taxonomy_id` string — Unique identifier for the taxonomy
  - `version` integer — Monotonic version number of the taxonomy configuration
  - `taxonomy_name` string, required — A unique name for the taxonomy within the namespace.
  - `description` string, nullable — Optional human-readable description.
  - `retriever_id` string, nullable — Optional taxonomy-level retriever (prefer per-layer).
  - `input_mappings` InputMapping[], nullable — Optional taxonomy-level inputs (prefer per-layer).
    - `input_key` string, required — Key used in the constructed inputs payload.
    - `source_type` 'payload' | 'literal' | 'vector' | 'blob' — Where the value for an input should be retrieved from.
    - `path` string, nullable — Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
    - `override` unknown
  - `config` union, required — Configuration specific to the taxonomy type.
    - FlatTaxonomyConfigOutput — Configuration for a *flat* taxonomy - single source collection with one retriever.
      - `taxonomy_type` 'flat' — Discriminator identifying this as a flat taxonomy.
      - `retriever_id` string, required — The retriever to use for matching against the source collection.
      - `input_mappings` InputMapping[], required — Input mappings defining how to construct retriever inputs.
        - `input_key` string, required — Key used in the constructed inputs payload.
        - `source_type` 'payload' | 'literal' | 'vector' | 'blob' — Where the value for an input should be retrieved from.
        - `path` string, nullable — Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
        - `override` unknown
      - `source_collection` SourceCollectionOutput, required — A source collection for a flat taxonomy.
        - `collection_id` string, required — The ID of the source collection for the taxonomy.
        - `enrichment_fields` EnrichmentField[], nullable — Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied.
          - `field_path` string, required — Dot-notation path of the field to copy from the taxonomy node.
          - `target_field` string, nullable — 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).
          - `merge_mode` 'replace' | 'append' — How a field from the taxonomy node should be merged into the target doc.
      - `step_analytics` StepAnalyticsConfigOutput — Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ```
        - `timestamp_field` string, required — Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')
        - `sequence_id_field` string, required — Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')
        - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path' — Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage")
        - `step_key_field_path` string, nullable — Required if step_key_source='field_path'. Dot-notation path to step value in document.
        - `covariates` CovariateConfig[] — Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)
          - `field_path` string, required — Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')
          - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required — Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ```
          - `name` string, required — Human-readable name for this covariate in analytics results
          - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable — How to bin numeric values for lift analysis (only used for NUMERIC type)
          - `clustering_method` 'kmeans' | 'hdbscan', nullable — Clustering algorithm for embedding analysis (only used for EMBEDDING type)
          - `n_clusters` integer, nullable — Number of clusters for embedding-based predictors (only used for EMBEDDING type)
        - `max_sequence_duration_days` integer, nullable — Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues.
    - HierarchicalTaxonomyConfigOutput — Hybrid hierarchical taxonomy configuration supporting inference with manual additions. All hierarchical taxonomies are hybrid: - Base hierarchy can be inferred via schema, clustering, or LLM - Additional collections can be explicitly added with specific retrievers - Supports mixing inference strategies with manual additions/overrides Examples: 1. Pure inference: Set inference_strategy + inference_collections 2. Pure manual: Set hierarchical_nodes only 3. Hybrid: Set inference_strategy + inference_collections + hierarchical_nodes (infers base from collections, adds/overrides with explicit nodes)
      - `taxonomy_type` 'hierarchical' — Discriminator identifying this as a hierarchical taxonomy.
      - `retriever_id` string, nullable — Default retriever to use for all nodes unless overridden per-node.
      - `input_mappings` InputMapping[], nullable — Default input mappings for all nodes unless overridden per-node.
        - `input_key` string, required — Key used in the constructed inputs payload.
        - `source_type` 'payload' | 'literal' | 'vector' | 'blob' — Where the value for an input should be retrieved from.
        - `path` string, nullable — Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
        - `override` unknown
      - `inference_strategy` 'schema' | 'cluster' | 'llm' — Strategy for inferring the base hierarchy structure. Can be combined with manual overrides via hierarchical_nodes for hybrid configuration: - SCHEMA: Infer based on overlapping collection schemas - CLUSTER: Infer based on clustering algorithms and overlap detection - LLM: Infer using AI/language models
      - `inference_collections` string[], nullable — Collection IDs to use for hierarchy inference. The inference_strategy will analyze these collections to discover relationships. Can be combined with hierarchical_nodes for hybrid configuration.
      - `llm_provider` 'openai_chat_v1', nullable — LLM provider to use for hierarchy inference (default openai_chat_v1)
      - `llm_model` string, nullable — LLM model name (e.g., gpt-4o-mini)
      - `llm_prompt_template` string, nullable — Optional prompt template. Variables available: {collection_id}, {collection_name}.
      - `llm_sample_size` integer — Optional number of sample docs to include in prompts (0 = disabled).
      - `cluster_ids` string[], nullable — Cluster IDs to use for CLUSTER inference strategy
      - `cluster_overlap_threshold` number — Minimum overlap ratio to establish parent-child relationship between clusters
      - `hierarchical_nodes` HierarchicalNodeOutput[], nullable — Explicit node definitions that either: 1) Define the entire hierarchy (when inference_strategy is None), 2) Add additional nodes to an inferred hierarchy, or 3) Override specific relationships in an inferred hierarchy. Supports true hybrid: infer from some collections, manually add others.
        - `collection_id` string, required — REQUIRED. Collection ID representing this node in the hierarchy. Must reference an existing collection containing documents for this hierarchy level. Format: 'col_' prefix followed by alphanumeric/underscore characters. Used to: Match documents against this level, identify node in path, store enrichment data. Example: 'col_executives' for executive level, 'col_products_phones' for phones category.
        - `parent_collection_id` string, nullable — OPTIONAL. Collection ID of the parent node in the hierarchy. When None: This is a root node (top of hierarchy). When set: References parent node's collection_id, creating parent-child relationship. Format: Same as collection_id ('col_' prefix). Used to: Build hierarchy tree, determine inheritance order, construct path arrays. Example: 'col_managers' is parent of 'col_executives', 'col_products' is parent of 'col_electronics'. Validation: Must reference a valid collection_id from another node in same taxonomy.
        - `label` string, nullable — OPTIONAL. Human-readable display name for this hierarchy node. Used in UI, visualizations, and taxonomy assignment results. NOT REQUIRED - When None: collection name or auto-generated label may be used. Format: Free text, typically title case, 2-50 characters. Examples: 'Executive Leadership', 'Mobile Phones', 'Engineering Team'. Can be LLM-generated or manually specified during taxonomy creation.
        - `summary` string, nullable — OPTIONAL. Brief description of this hierarchy level and its contents. Used for: Documentation, UI tooltips, understanding hierarchy structure. NOT REQUIRED - When None: no summary available for this node. Format: Free text, typically 1-3 sentences, up to 500 characters. Can be LLM-generated or manually provided.
        - `keywords` string[], nullable — OPTIONAL. Keywords or tags describing this hierarchy level. Used for: Search, filtering, categorization, LLM understanding. NOT REQUIRED - When None: no keywords defined for this node. Format: List of strings, typically 3-10 keywords per node. Can be LLM-generated from collection contents or manually specified.
        - `retriever_id` string, nullable — OPTIONAL. Retriever to use for matching documents at this hierarchy level. When None: Uses taxonomy-level retriever_id (inheritance from parent config). When set: Overrides taxonomy-level retriever for this specific node. Format: 'ret_' prefix followed by alphanumeric characters. Use for: Specialized matching at certain levels (e.g., face recognition for employees, semantic search for products). Must reference an existing RetrieverModel.
        - `enrichment_fields` EnrichmentField[], nullable — OPTIONAL. Fields to enrich into documents when they match this hierarchy level. Specifies which properties from node collection to copy to matched documents. When None: No field-level enrichment (only taxonomy assignment recorded). Format: List of EnrichmentField objects with field_path and merge_mode. Inheritance: Child nodes inherit all parent enrichment_fields plus their own. Example: executives node adds 'executive_level' on top of inherited 'employee_id', 'department'.
          - `field_path` string, required — Dot-notation path of the field to copy from the taxonomy node.
          - `target_field` string, nullable — 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).
          - `merge_mode` 'replace' | 'append' — How a field from the taxonomy node should be merged into the target doc.
        - `input_mappings` InputMapping[], nullable — OPTIONAL. Custom input mappings for the retriever at this hierarchy level. Specifies how to construct retriever inputs from document features. When None: Uses taxonomy-level input_mappings (inheritance). When set: Overrides taxonomy-level mappings for this specific node. Format: List of InputMapping objects specifying input_key, source_type, path. Use for: Different matching strategies at different levels (e.g., face at employee level, text at department level).
          - `input_key` string, required — Key used in the constructed inputs payload.
          - `source_type` 'payload' | 'literal' | 'vector' | 'blob' — Where the value for an input should be retrieved from.
          - `path` string, nullable — Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
          - `override` unknown
      - `step_analytics` StepAnalyticsConfigOutput — Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ```
        - `timestamp_field` string, required — Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')
        - `sequence_id_field` string, required — Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')
        - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path' — Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage")
        - `step_key_field_path` string, nullable — Required if step_key_source='field_path'. Dot-notation path to step value in document.
        - `covariates` CovariateConfig[] — Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)
          - `field_path` string, required — Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')
          - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required — Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ```
          - `name` string, required — Human-readable name for this covariate in analytics results
          - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable — How to bin numeric values for lift analysis (only used for NUMERIC type)
          - `clustering_method` 'kmeans' | 'hdbscan', nullable — Clustering algorithm for embedding analysis (only used for EMBEDDING type)
          - `n_clusters` integer, nullable — Number of clusters for embedding-based predictors (only used for EMBEDDING type)
        - `max_sequence_duration_days` integer, nullable — Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues.
  - `ready` boolean — Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies.
  - `created_at` string, date-time — Creation timestamp for this taxonomy record
  - `metadata` object — Additional user-defined metadata for the taxonomy

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/5307993e44d3/schema)