Sign in

v5

OpenAPI 3.1.02026-08-025631,1012.8 MB
Taxonomies

Partially Update Taxonomy

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.
patch/v1/taxonomies/{taxonomy_identifier}

Path parameters

taxonomy_identifierstring required

Taxonomy ID or name

Taxonomy ID or name

Request body

taxonomy_namestring nullable

Updated name for the taxonomy

descriptionstring nullable

Updated description for the taxonomy

metadataobject nullable

Updated metadata for the taxonomy

Response

Successful Response

taxonomy_idstring

Unique identifier for the taxonomy

versioninteger

Monotonic version number of the taxonomy configuration

taxonomy_namestring required

A unique name for the taxonomy within the namespace.

descriptionstring nullable

Optional human-readable description.

retriever_idstring nullable

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

readyboolean

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

created_atstring date-time

Creation timestamp for this taxonomy record

metadataobject

Additional user-defined metadata for the taxonomy

Example response

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