Taxonomies

Create Taxonomy

Changed on

Create a taxonomy and return the created resource.

post/v1/taxonomies

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/taxonomies
  • Auth: HTTP bearer and API key in header X-Namespace

Request body

taxonomy_namestring required

A unique name for the taxonomy within the namespace.

descriptionstring nullable

An optional description of the taxonomy.

metadataobject nullable

OPTIONAL caller metadata, stored with the taxonomy and merged with the system entries (validation_warnings). PATCH /taxonomies/{id} accepted this field before create did.

Example request

{
  "config": {
    "input_mappings": [
      {
        "input_key": "image_vector",
        "path": "features.clip",
        "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_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"
}

Changes

  • 62302d591b8eRevision changes
    • info

      added the new optional request property //

    • info

      added the optional property // to the response with the status

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status