Taxonomies

Create a taxonomy from a document selection or a cluster run (one gesture)

Changed on

Promote a document selection (e.g. a lasso/cluster selection in the cluster visualization) into a NEW flat taxonomy in one call.

Creates, in order:

  1. a node collection mirroring the selection's vector index (same vector name, dimensions, and feature_uri — no re-embedding, no GPU work),
  2. a vector-search retriever over it,
  3. the flat taxonomy wired to both (input_mappings map an incoming document's stored embedding onto the retriever),
  4. the nodes, from one of two sources:
    • documents + node_label: one node whose anchor vector is the centroid of the referenced documents' stored vectors;
    • cluster_run ({cluster_id, run_id}): one node per cluster in that run, labeled with the cluster's label and anchored on its stored centroid, so a whole cluster run becomes a classifier in one call. The response's nodes lists every node created.

Documents enriched through the taxonomy afterwards are labeled with the nearest node's label. To add more nodes later, use POST /v1/taxonomies/{taxonomy_id}/nodes/from-documents.

Resources created before a failing step are cleaned up best-effort.

post/v1/taxonomies/from-documents

Request

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

Request body

node_labelstring nullable

Label of the node created from documents. Required with documents; with cluster_run each node takes its cluster's label.

node_fieldsobject nullable

Optional extra fields stored on the node document (e.g. description). Only fields listed in the taxonomy's enrichment_fields are copied during enrichment.

vector_namestring nullable

Optional explicit vector (index) name for the anchor. If omitted, it is derived from the taxonomy's node collection vector indexes.

provenanceobject nullable

Optional freeform origin context (e.g. cluster_id, run_id, selection type). Stored on the node document under metadata.promotion for auditability.

taxonomy_namestring required

Unique name for the new taxonomy.

descriptionstring nullable

Optional taxonomy description.

enrichment_target_fieldstring nullable

Field name written onto enriched documents (defaults to '<taxonomy_name>_label').

Response

Successful Response

taxonomy_idstring required
taxonomy_namestring required
node_document_idstring required

ID of the created node document (the taxonomy node).

node_collection_idstring required

The taxonomy's node (source) collection.

node_labelstring required
vector_namestring required

Vector index name the anchor was stored under.

vector_dimensionsinteger required
documents_usedinteger required

How many referenced documents contributed to the anchor.

taxonomy_createdboolean

True when this call also created the taxonomy (one-gesture mode).

retriever_idstring nullable

Retriever created for the taxonomy (one-gesture mode only).

enrichment_hintstring required

Plain-language description of how the new node will be applied to future data.

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

    • info

      added the new optional request property

    • info

      the request property became optional

    • info

      the request property became optional

    • info

      request property list-of-types was widened by adding types null to media type application/json

    • info

      request property list-of-types was widened by adding types null to media type application/json

    • info

      the request property's minLength was decreased from 1 to 0

    • info

      added the optional property to the response with the status