Skip to main content
GET
/
v1
/
retrievers
/
stages
List Available Retriever Stages
curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/stages \
  --header 'Authorization: Bearer <token>'
[
  {
    "stage_id": "<string>",
    "description": "<string>",
    "category": "filter",
    "icon": "<string>",
    "parameter_schema": {
      "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"
    }
  }
]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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

Examples:

"attribute_filter"

"feature_filter"

"llm_filter"

"sort_relevance"

"document_enrich"

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

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
enum<string>
required

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.

Available options:
filter,
sort,
reduce,
apply,
enrich
Examples:

"filter"

"sort"

"reduce"

"apply"

​
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).

Examples:

"filter"

"search"

"brain-circuit"

"arrow-up-down"

"database"

​
parameter_schema
Parameter Schema · object

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:
{
  "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"
}