> ## 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.

# List Available Retriever 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.



## OpenAPI

````yaml get /v1/retrievers/stages
openapi: 3.1.0
info:
  title: Mixpeek API
  description: >-
    This is the Mixpeek API, providing access to various endpoints for data
    processing and retrieval.
  termsOfService: https://mixpeek.com/terms
  contact:
    name: Mixpeek Support
    url: https://mixpeek.com/contact
    email: info@mixpeek.com
  version: '0.82'
servers:
  - url: https://api.mixpeek.com
    description: Production
security: []
paths:
  /v1/retrievers/stages:
    get:
      tags:
        - Retriever Stages
      summary: List Available Retriever Stages
      description: >-
        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.
      operationId: list_stages_v1_retrievers_stages_get
      responses:
        '200':
          description: >-
            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)
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RetrieverStageDefinition'
                type: array
                title: Response List Stages V1 Retrievers Stages Get
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RetrieverStageDefinition:
      properties:
        stage_id:
          type: string
          title: Stage Id
          description: >-
            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.
          examples:
            - attribute_filter
            - feature_filter
            - llm_filter
            - sort_relevance
            - document_enrich
        description:
          type: string
          title: Description
          description: >-
            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.
          examples:
            - Filter documents by attribute conditions with boolean logic
            - Unified multi-vector search with N feature URIs and fusion
            - >-
              Filter documents using LLM-based reasoning and natural language
              criteria
            - Sort documents by relevance scores
        category:
          $ref: '#/components/schemas/StageCategory'
          description: >-
            REQUIRED. Transformation category defining how the stage processes
            documents. Categories: 'filter' (subset, N→≤N), 'sort' (reorder,
            N→N), 'reduce' (aggregate, N→1), 'apply' (enrich/expand, N→N or
            N→N*M). Use category to understand stage's impact on document flow.
          examples:
            - filter
            - sort
            - reduce
            - apply
        icon:
          type: string
          title: Icon
          description: >-
            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).
          examples:
            - filter
            - search
            - brain-circuit
            - arrow-up-down
            - database
        parameter_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameter Schema
          description: >-
            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.
          examples:
            - properties:
                field:
                  description: Dot-delimited field path to evaluate
                  examples:
                    - metadata.status
                    - metadata.priority
                  type: string
                operator:
                  description: Comparison operator
                  enum:
                    - eq
                    - ne
                    - gt
                    - gte
                    - lt
                    - lte
                    - in
                    - nin
                value:
                  description: Comparison value (type depends on field)
              required:
                - field
                - operator
                - value
              type: object
            - null
      type: object
      required:
        - stage_id
        - description
        - category
        - icon
      title: RetrieverStageDefinition
      description: >-
        Public definition of a retriever stage available in the system.


        Each stage represents a specific operation in a retrieval pipeline
        (filter, sort,

        enrich, etc). Use the `/v1/retrievers/stages` endpoint to discover
        available stages

        and their parameter schemas before creating retrievers.


        Stage Registration:
            - Stages are registered in the retriever stage registry
            - Each stage has a unique ID, category, and parameter schema
            - Parameter schemas are Pydantic models with full validation

        Usage Flow:
            1. Call GET /v1/retrievers/stages to list all available stages
            2. Review parameter_schema for each stage to understand requirements
            3. Compose stages into a retrieval pipeline
            4. Create retriever via POST /v1/collections/{id}/retrievers

        Example Workflow:
            ```
            # 1. Discover stages
            GET /v1/retrievers/stages

            # 2. Review attribute_filter schema
            {
              "stage_id": "attribute_filter",
              "description": "Filter documents by attribute conditions",
              "category": "filter",
              "parameter_schema": {
                "type": "object",
                "properties": {
                  "field": {"type": "string"},
                  "operator": {"enum": ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]},
                  "value": {}
                }
              }
            }

            # 3. Create retriever using discovered stage
            POST /v1/collections/col_123/retrievers
            {
              "stages": [
                {
                  "stage_name": "filter_active",
                  "stage_type": "filter",
                  "config": {
                    "stage_id": "attribute_filter",
                    "parameters": {
                      "field": "status",
                      "operator": "eq",
                      "value": "active"
                    }
                  }
                }
              ]
            }
            ```

        Requirements:
            - stage_id: REQUIRED, unique identifier for the stage
            - description: REQUIRED, human-readable description of stage purpose
            - category: REQUIRED, transformation category (filter/sort/reduce/apply)
            - icon: REQUIRED, UI icon identifier (Lucide React)
            - parameter_schema: OPTIONAL, JSON Schema for stage parameters (null if no params)
      examples:
        - category: filter
          description: >-
            Filter documents by attribute conditions with boolean logic
            (AND/OR/NOT). Fast, operates on metadata fields.
          icon: filter
          parameter_schema:
            properties:
              field:
                description: Dot-delimited field path
                examples:
                  - metadata.status
                  - metadata.category
                type: string
              operator:
                description: Comparison operator
                enum:
                  - eq
                  - ne
                  - gt
                  - gte
                  - lt
                  - lte
              value:
                description: Comparison value
            required:
              - field
              - operator
              - value
            type: object
          stage_id: attribute_filter
        - category: filter
          description: >-
            Filter documents using LLM-based reasoning. Slow but powerful for
            complex semantic filtering.
          icon: brain-circuit
          parameter_schema:
            properties:
              provider:
                description: LLM provider (google, openai, anthropic)
                examples:
                  - google
                  - openai
                  - anthropic
                type: string
              model_name:
                description: Specific model name
                examples:
                  - gemini-2.5-flash
                  - gpt-4o-mini
                  - claude-3-5-haiku-20241022
                type: string
              criteria:
                description: Natural language filtering criteria
                examples:
                  - Keep only enterprise-focused content
                  - Discard negative sentiment
                type: string
            required:
              - criteria
            type: object
          stage_id: llm_filter
        - category: sort
          description: Sort documents by relevance scores in ascending or descending order.
          icon: arrow-up-down
          parameter_schema:
            properties:
              order:
                default: desc
                description: Sort order
                enum:
                  - asc
                  - desc
            type: object
          stage_id: sort_relevance
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        status:
          type: integer
          title: Status
          description: HTTP status code for this error
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details payload
      type: object
      required:
        - status
        - error
      title: ErrorResponse
      description: Error response model.
      examples:
        - error:
            details:
              id: ns_123
              resource: namespace
            message: Namespace not found
            type: NotFoundError
          status: 404
          success: false
    StageCategory:
      type: string
      enum:
        - filter
        - sort
        - reduce
        - apply
        - enrich
      title: StageCategory
      description: |-
        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
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error message
        type:
          type: string
          title: Type
          description: Stable error type identifier (machine-readable)
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Fine-grained error code for programmatic handling (e.g.,
            namespace_name_taken, feature_extractor_not_found). Present only
            when consumers may need to branch on a specific error condition.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: >-
            Optional structured details to help debugging (validation errors,
            IDs, etc.)
      type: object
      required:
        - message
        - type
      title: ErrorDetail
      description: Error detail model.

````