Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Taxonomies

Create Taxonomy

Create a taxonomy and return the created resource.

post/v1/taxonomies

Request body

taxonomy_namestring required

A unique name for the taxonomy within the namespace.

descriptionstring nullable

An optional description of the taxonomy.

Example request

{
  "config": {
    "collection_id": "col_products_v1",
    "enrichment_fields": [
      {
        "field_path": "metadata.tags",
        "merge_mode": "append"
      }
    ],
    "input_mappings": [
      {
        "input_key": "image_vector",
        "path": "features.clip",
        "source_type": "vector"
      }
    ],
    "retriever_id": "ret_clip_v1",
    "taxonomy_type": "flat"
  },
  "taxonomy_name": "product_tags"
}

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