---
title: "List Available Retriever Stages"
method: GET
path: "/v1/retrievers/stages"
tags: ["Retriever Stages"]
---

# List Available Retriever Stages

`GET /v1/retrievers/stages`

List all registered retriever stages with their configurations. Use this endpoint to discover available stages before creating retrievers. Each stage includes its ID, description, category, and full parameter schema. The parameter_schema field contains complete Pydantic JSON Schema with validation rules, descriptions, and examples for all stage parameters.

## Response `200`

List of retriever stage definitions with complete parameter schemas. Each stage includes: - stage_id: Unique identifier to use in retriever configurations - description: Human-readable purpose and behavior - category: Transformation type (filter/sort/reduce/apply) - icon: UI icon identifier - parameter_schema: Full JSON Schema for stage parameters (null if no params)

- RetrieverStageDefinition[]
  - `stage_id` string, required — REQUIRED. Unique identifier for the stage type. Use this ID in the 'stage_id' field when configuring stages in a retriever. Common stage IDs: 'attribute_filter', 'feature_filter', 'llm_filter', 'sort_relevance', 'document_enrich', 'taxonomy_enrich'. Stage IDs are immutable and versioned separately from implementation.
  - `description` string, required — REQUIRED. Human-readable description of what the stage does. Explains the stage's purpose, behavior, and when to use it. Use this to understand stage capabilities before using in pipelines.
  - `category` 'filter' | 'sort' | 'reduce' | 'apply' | 'enrich', required — Retriever stage categories organized by transformation pattern. Values: FILTER: Subset of input documents (N → ≤N, same schema) - Removes documents that don't match criteria - Examples: attribute_filter, feature_filter, llm_filter - Use for: Removing irrelevant results, applying business rules - Performance: Fast (attribute) to slow (LLM) SORT: Reorders documents (N → N, same schema, different order) - Changes document ordering based on criteria - Examples: sort_relevance, sort_attribute - Use for: Ordering by relevance, recency, custom fields - Performance: Fast (in-memory sort) REDUCE: Aggregates to summary (N → 1, new schema) - Combines multiple documents into one summary - Examples: aggregate_stats, group_by - Use for: Summaries, statistics, reports - Performance: Varies by aggregation logic APPLY: Enrichment or expansion (N → N or N*M) - 1-1: Enriches each doc (N → N, expanded schema) - 1-N: Expands each doc (N → N*M, new/same schema) - Examples: document_enrich, taxonomy_enrich, llm_enrich - Use for: Adding related data, tagging, recursive lookups - Performance: Moderate (DB) to slow (LLM) ENRICH: Document enrichment (N → N, potentially expanded schema) - Adds computed fields to each document - Examples: code_execution, llm_enrich, taxonomy_enrich - Use for: Custom transformations, data extraction, LLM processing - Performance: Varies (fast for code, slow for LLM) Pipeline Patterns: - Basic: FILTER → SORT - Enriched: FILTER → SORT → APPLY - Tag expansion: FILTER → APPLY (1-N) - Summary: FILTER → SORT → REDUCE
  - `icon` string, required — REQUIRED. Lucide React icon identifier for UI rendering. Used by frontend clients to display stage icons in pipeline builders. See https://lucide.dev for available icon names. Common icons: 'filter' (attribute_filter), 'search' (semantic), 'brain-circuit' (LLM), 'arrow-up-down' (sort).
  - `parameter_schema` object, nullable — OPTIONAL. JSON Schema defining the parameters this stage accepts. Contains full Pydantic schema including types, descriptions, examples, and validation rules for all stage parameters. Use this schema to validate stage configurations before submission. Null if stage requires no parameters (rare). Schema includes: field types, required fields, defaults, validation constraints, field descriptions, and usage examples.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/23e05292e326/schema)