Sign in

v

latestOpenAPI 3.1.02026-08-085671,1112.8 MB
Retriever Stages

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.

get/v1/retrievers/stages

Response

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)

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

descriptionstring 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

iconstring 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_schemaobject 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.

Example response

[
  {
    "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"
  }
]