> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Classify Content

> Auto-label documents with taxonomies, retriever enrichments, and annotations

![Content classification: documents are enriched via taxonomies (flat or hierarchical similarity matching) or retriever enrichments (pipeline execution with field write-back)](https://mintcdn.com/mixpeek/pDBzbsnRaRIThJZv/assets/mixpeek-enrichment.svg?fit=max\&auto=format\&n=pDBzbsnRaRIThJZv\&q=85\&s=87c8771bf4023383ab93a1b794a9e9eb)

> [!NOTE]
>
> For full configuration details, parameters, and advanced options, see the [Taxonomies reference](https://docs.mixpeek.com/docs/enrichment/taxonomies.md).

## Taxonomies

Auto-classify documents by matching them against reference collections. Two types:

**Flat** — match each document against a single reference collection. When similarity exceeds the threshold, enrichment fields (SKU, category, label) are attached.

**Hierarchical** — parent/child nodes with inheritance. Documents traverse levels of refinement (brand → category → subcategory) using different features at each level.

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/taxonomies" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy_name": "product-categories",
    "config": {
      "taxonomy_type": "flat",
      "retriever_id": "'$REF_RETRIEVER_ID'",
      "input_mappings": [
        { "input_key": "query", "source_type": "payload", "path": "title" }
      ],
      "source_collection": {
        "collection_id": "'$REF_COLLECTION_ID'",
        "enrichment_fields": [
          { "field_path": "category", "merge_mode": "replace" },
          { "field_path": "subcategory", "merge_mode": "replace" },
          { "field_path": "brand", "merge_mode": "replace" }
        ]
      }
    }
  }'
```

### When to Run

| Mode | Runs | Configured via | Use case |
| - | - | - | - |
| On-demand | At query time | A `taxonomy_enrich` stage on a retriever | Dynamic classification, A/B testing |
| Materialized | After extraction, persists to collection | `taxonomy_applications[].execution_mode: "materialize"` on the collection | Stable labels, fast queries |
| Retroactive | Reapplies when taxonomy updates | `POST /v1/collections/{id}/apply-taxonomy` | Backfill when reference data improves |

`taxonomy_applications[].execution_mode` only accepts `materialize`; on-demand and retroactive run through the other two surfaces above, each with its own request shape (see [Taxonomies](https://docs.mixpeek.com/docs/enrichment/taxonomies.md)).

[Taxonomy API →](https://docs.mixpeek.com/docs/api-reference/taxonomies/create-taxonomy.md)

## Retriever Enrichments

Attach a retriever pipeline to a collection so it runs on every new document. The retriever executes, and selected result fields are written back to the document.

```bash theme={null}
curl -X PATCH "https://api.mixpeek.com/v1/collections/$COLLECTION_ID" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "retriever_enrichments": [{
      "retriever_id": "'$RETRIEVER_ID'",
      "input_mappings": { "query_text": { "source": "payload", "path": "description" } },
      "write_back_fields": { "category": { "mode": "first", "path": "results[0].metadata.category" } }
    }]
  }'
```

Use cases: auto-classify via LLM, cross-collection joins, label propagation from seed documents.

[Collection update API →](https://docs.mixpeek.com/docs/api-reference/collections/update-collection.md)

## Annotations

Explicit human decisions with full provenance — the ground truth layer for compliance, review workflows, and improving retrieval quality over time.

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/annotations" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_abc",
    "collection_id": "col_xyz",
    "retriever_id": "ret_123",
    "execution_id": "exec_789",
    "stage_name": "feature_search",
    "label": "approved",
    "confidence": 0.95,
    "reasoning": "Matches reference product exactly",
    "payload": { "sku": "SKU-001", "action": "keep", "actor_id": "user_456", "actor_type": "human" }
  }'
```

### What Each Annotation Captures

| Field | Purpose |
| - | - |
| `document_id`, `collection_id` | What was reviewed |
| `retriever_id`, `execution_id`, `stage_name` | How it was surfaced |
| `label`, `confidence`, `reasoning` | The decision |
| `payload` | Structured workflow-specific data (SKU, action, notes). Who decided goes here too: there are no top-level `actor_id` / `actor_type` fields |

Annotations are stored independently from documents — they never modify the source data. Use them to build review queues, audit trails, and curated ground truth datasets.

### Bulk Operations

Process review queues at scale with the bulk API:

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/annotations/bulk" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "create": [
      { "document_id": "doc_1", "collection_id": "col_xyz", "label": "approved" },
      { "document_id": "doc_2", "collection_id": "col_xyz", "label": "rejected", "reasoning": "Low quality match" }
    ],
    "update": [],
    "delete": []
  }'
```

### The Feedback Loop

Annotations feed directly into the platform's learning cycle:

1. **Annotations** provide explicit ground truth for edge cases
2. **Learned fusion** uses annotations to auto-tune retriever stage weights
3. **Approved annotations** can be piped into reference collections, expanding your taxonomy's coverage
4. **Retroactive taxonomy application** reclassifies existing documents when annotations improve the reference set

[Annotation API →](https://docs.mixpeek.com/docs/api-reference/annotations/create-annotation.md) · [Bulk API →](https://docs.mixpeek.com/docs/api-reference/annotations/bulk-annotations.md)

## Choosing an Approach

| Goal | Use |
| - | - |
| Auto-label with a reference catalog | Flat taxonomy (materialize mode) |
| Hierarchical classification (brand → category → SKU) | Hierarchical taxonomy |
| Auto-classify via LLM at ingest | Retriever enrichment with `llm_enrich` stage |
| Cross-collection joins (enrich from another dataset) | Retriever enrichment with `document_enrich` stage |
| Human review with audit trail | Annotations |
| Backfill when labels improve | Retroactive taxonomy application |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.