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.

Authorizations

Authorization · string · header · required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

Authorization · string · required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

X-Namespace · string · required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Response

200

application/json

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_search', 'llm_filter', 'sort_relevance', 'document_enrich', 'taxonomy_enrich'. Stage IDs are immutable and versioned separately from implementation.

Examples:

"attribute_filter"

"feature_search"

"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

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 · object | null

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