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

> List all retrievers in the namespace.



## OpenAPI

````yaml post /v1/retrievers/list
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/list:
    post:
      tags:
        - Retrievers
      summary: List Retrievers
      description: List all retrievers in the namespace.
      operationId: list_retrievers_v1_retrievers_list_post
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 1000
                minimum: 1
              - type: 'null'
            title: Limit
        - name: page_size
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 1000
                minimum: 1
              - type: 'null'
            title: Page Size
        - name: offset
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 10000
                minimum: 0
              - type: 'null'
            title: Offset
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            title: Page
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
        - name: include_total
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Total
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRetrieversRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRetrieversResponse'
        '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'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListRetrieversRequest:
      properties:
        search:
          anyOf:
            - type: string
            - type: 'null'
          title: Search
          description: >-
            Search term for wildcard search across retriever_id, retriever_name,
            description, and other text fields
        filters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Filters
          description: >-
            Filters applied directly to the query — any stored field works, e.g.
            {"collection_ids": {"$in": ["col_x"]}} to filter by collection, or
            {"retriever_name": "..."}.
        sorts:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Sorts
          description: Sort options for the retriever list
        case_sensitive:
          type: boolean
          title: Case Sensitive
          description: If True, filters and search will be case-sensitive
          default: false
      type: object
      title: ListRetrieversRequest
      description: Request to list retrievers.
    ListRetrieversResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/RetrieverModel-Output'
          type: array
          title: Results
          description: List of retrievers in the namespace.
        total:
          type: integer
          title: Total
          description: Total number of retrievers.
          default: 0
        pagination:
          anyOf:
            - $ref: '#/components/schemas/PaginationResponse'
            - type: 'null'
          description: Pagination details (next/previous cursors and total).
      type: object
      title: ListRetrieversResponse
      description: Response from listing retrievers.
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RetrieverModel-Output:
      properties:
        retriever_id:
          type: string
          title: Retriever Id
          description: Stable retriever identifier (REQUIRED).
        retriever_name:
          type: string
          minLength: 1
          title: Retriever Name
          description: Unique retriever name within namespace (REQUIRED).
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Detailed description of retriever behaviour (OPTIONAL).
        collection_ids:
          items:
            type: string
          type: array
          title: Collection Ids
          description: >-
            Collections queried by the retriever. Can be empty for query-only
            inference mode.
        stages:
          items:
            $ref: '#/components/schemas/StageConfig'
          type: array
          minItems: 1
          title: Stages
          description: Ordered list of stage configurations (REQUIRED).
        input_schema:
          additionalProperties:
            $ref: '#/components/schemas/RetrieverInputSchemaField-Output'
          type: object
          title: Input Schema
          description: >-
            JSON Schema describing expected user inputs (REQUIRED). Properties
            must use RetrieverInputSchemaField which supports all bucket types
            plus document_reference.
        budget_limits:
          $ref: '#/components/schemas/BudgetLimits'
          description: Execution budget limits for the retriever (OPTIONAL).
        feature_dependencies:
          anyOf:
            - items:
                $ref: '#/components/schemas/FeatureAddress'
              type: array
            - type: 'null'
          title: Feature Dependencies
          description: Feature addresses required by stages (OPTIONAL, aids validation).
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Arbitrary tags to help organise retrievers (OPTIONAL).
        display_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Display Config
          description: >-
            Display configuration for public retriever UI rendering (OPTIONAL).
            Defines how the search interface should appear when the retriever is
            published, including input fields, theme, layout, exposed result
            fields, and field formatting. This configuration is used as the
            default when publishing the retriever.
        version:
          type: integer
          minimum: 1
          title: Version
          description: Version number that increments on each update (REQUIRED).
          default: 1
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp in UTC (REQUIRED).
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp in UTC (REQUIRED).
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
          description: Identifier of the user who created the retriever (OPTIONAL).
        updated_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated By
          description: Identifier of the user who last updated the retriever (OPTIONAL).
        is_published:
          type: boolean
          title: Is Published
          description: >-
            Whether this retriever is currently published (either as public
            retriever or in marketplace)
          default: false
        marketplace_listing_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Marketplace Listing Id
          description: >-
            Marketplace listing ID if this retriever is published to the
            marketplace, None otherwise
        fusion:
          anyOf:
            - type: string
            - type: 'null'
          title: Fusion
          description: >-
            Fusion strategy used by this retriever's feature_search stage (e.g.
            'learned', 'rrf', 'dbsf'). Null if no feature_search stage.
          readOnly: true
      type: object
      required:
        - retriever_name
        - stages
        - fusion
      title: RetrieverModel
      description: Retriever configuration model exposed via API.
      examples:
        - budget_limits:
            max_credits: 100
            max_time_ms: 60000
          collection_ids:
            - col_marketing_ads
          input_schema:
            query_text:
              description: Full-text query
              type: string
          retriever_id: ret_abc123
          retriever_name: executive_ads_search
          stages:
            - config:
                parameters:
                  field: metadata.spend
                  operator: gt
                  value: 1000
                stage_name: attribute_filter
                version: v1
              name: filter_high_spend
              stage_type: filter
    PaginationResponse:
      properties:
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
        page_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Size
        total_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Pages
        next_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page
        previous_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Page
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      title: PaginationResponse
      description: |-
        PaginationResponse.

        Cursor-based pagination response:
        - Use next_cursor for navigation
        - Total count fields only populated when include_total=true
    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.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StageConfig:
      properties:
        stage_name:
          type: string
          minLength: 1
          title: Stage Name
          description: Human-readable stage instance name (REQUIRED).
        stage_type:
          anyOf:
            - $ref: '#/components/schemas/StageType'
            - type: 'null'
          description: >-
            Functional category of the stage. Optional for creation requests;
            auto-inferred from `stage_id` when omitted.
        config:
          additionalProperties: true
          type: object
          title: Config
          description: >-
            Stage implementation parameters (REQUIRED). Must include `stage_id`
            key referencing a registered retriever stage. Supports template
            expressions using Jinja2 syntax resolved at execution time. Template
            namespaces support both uppercase and lowercase formats:
            {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}},
            {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or
            {{stage.field}}. All formats work identically. Provide
            stage-specific configuration under `parameters`. Optional
            `pre_filters` and `post_filters` are placed as SIBLINGS of
            `parameters` (NOT nested inside). Pre-filters require payload
            indexes on the filtered fields.
        batch_size:
          anyOf:
            - type: string
            - type: 'null'
          title: Batch Size
          description: >-
            Optional templated batch size expression evaluated per execution.
            Supports template variables: {{INPUT.page_size}},
            {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both
            uppercase and lowercase namespace names are supported (e.g.,
            INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to
            stage-specific value when omitted.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: User-facing description of the stage (OPTIONAL).
        on_error:
          anyOf:
            - type: string
            - type: 'null'
          title: On Error
          description: >-
            Behavior when this stage fails. 'skip' continues execution with
            results from previous stages (graceful degradation). 'error'
            (default) fails the entire retriever. Useful for optional enrichment
            or multi-modal stages where one modality may not apply (e.g., face
            search on logo-only images).
        output_alias:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Alias
          description: >-
            Optional alias to persist this stage's results in the execution
            context. When set, results are stored in CONTEXT.<alias> in addition
            to replacing current_results. Downstream stages can reference them
            via {{CONTEXT.<alias>}} in templates. Useful for multi-stage
            pipelines where later stages should not overwrite earlier results
            (e.g., face search + logo search producing independent result sets).
      type: object
      required:
        - stage_name
        - config
      title: StageConfig
      description: >-
        Configuration for a single stage within a retriever.


        Stages support dynamic configuration through template expressions using
        Jinja2 syntax.


        IMPORTANT - Template Syntax:
            - Use DOUBLE curly braces: {{INPUT.query}} (correct)
            - Single curly braces will NOT work: {INPUT.query} (wrong - not substituted)
            - Namespace names are CASE-INSENSITIVE: {{INPUT.query}}, {{inputs.query}}, {{input.query}}
              all work identically

        Template Namespaces (case-insensitive):
            - INPUT / inputs / input: User-provided query parameters and inputs
            - DOC / doc: Current document fields (for per-document logic)
            - CONTEXT / context: Execution state (budget, timing, retriever metadata)
            - STAGE / stage: Previous stage outputs (for cascading logic)

        Examples:
            Correct: {{INPUT.query_text}}, {{inputs.query}}, {{DOC.content_type}}
            Correct: {{CONTEXT.budget_remaining}}, {{context.budget_remaining}}
            Wrong:   {INPUT.query} - single braces won't be substituted
      examples:
        - config:
            parameters:
              final_top_k: 25
              searches:
                - feature_uri: >-
                    mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1
                  query:
                    input_mode: text
                    value: '{{INPUT.query_text}}'
                  top_k: 100
            stage_id: feature_search
          description: Feature search stage with uppercase template namespace
          stage_name: semantic_search
          stage_type: filter
        - batch_size: '{{20 * inputs.page_size}}'
          config:
            parameters:
              field: metadata.price
              operator: gt
              value: '{{inputs.min_price}}'
            stage_id: attribute_filter
          description: Attribute filter with lowercase template namespace
          stage_name: price_filter
          stage_type: filter
        - config:
            parameters:
              batch_size: '{{CONTEXT.budget_remaining > 50 ? 200 : 50}}'
              criteria: '{{inputs.quality_criteria}}'
              field: '{{DOC.media_type == ''image'' ? ''image_url'' : ''video_url''}}'
            stage_id: llm_filter
          description: Mixed case templates in same stage
          stage_name: llm_filter
          stage_type: filter
        - config:
            parameters:
              final_top_k: 10
              searches:
                - feature_uri: >-
                    mixpeek://web_scraper@v1/jinaai__jina_embeddings_v2_base_code
                  query:
                    input_mode: text
                    value: '{{INPUT.query}}'
                  top_k: 50
            pre_filters:
              AND:
                - field: doc_type
                  operator: eq
                  value: code
            stage_id: feature_search
          description: Feature search with pre_filters (sibling of parameters, NOT inside)
          stage_name: search_code_blocks
          stage_type: filter
    RetrieverInputSchemaField-Output:
      properties:
        type:
          $ref: '#/components/schemas/RetrieverInputSchemaFieldType'
        default:
          anyOf:
            - {}
            - type: 'null'
          title: Default
        items:
          anyOf:
            - $ref: '#/components/schemas/RetrieverInputSchemaField-Output'
            - type: 'null'
        properties:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/RetrieverInputSchemaField-Output'
              type: object
            - type: 'null'
          title: Properties
        examples:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Examples
          description: >-
            OPTIONAL. List of example values for this field. Used by Apps to
            show example inputs in the UI. Provide multiple diverse examples
            when possible.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        enum:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Enum
        required:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Required
          default: false
      additionalProperties: true
      type: object
      required:
        - type
      title: RetrieverInputSchemaField
      description: >-
        Schema field definition for retriever input parameters.


        Identical structure to BucketSchemaField but uses
        RetrieverInputSchemaFieldType

        which includes additional reference types like document_reference.


        This allows retrievers to accept:

        1. Metadata inputs (strings, numbers, dates, etc.)

        2. File inputs (images, videos, documents for search)

        3. Reference inputs (document_reference for "find similar" queries)
    BudgetLimits:
      properties:
        max_credits:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Max Credits
          description: Maximum credits allowed for a single execution (OPTIONAL).
        max_time_ms:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Time Ms
          description: >-
            Maximum wall-clock time in milliseconds before forcing halt
            (OPTIONAL).
      type: object
      title: BudgetLimits
      description: User-defined limits for time and credits during execution.
      examples:
        - max_credits: 100
          max_time_ms: 60000
        - max_time_ms: 120000
    FeatureAddress:
      properties:
        scheme:
          type: string
          title: Scheme
          default: mixpeek
        extractor:
          type: string
          title: Extractor
        version:
          type: string
          title: Version
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
      type: object
      required:
        - extractor
        - version
      title: FeatureAddress
      description: >-
        Canonical feature address: mixpeek://{extractor}@{version}/{output}.


        The output segment is the inference_name (embedding model identifier),
        which enables

        cross-extractor compatibility checking. Two feature URIs with the same
        inference_name

        in the output segment produce compatible embeddings that can be
        compared/fused.


        Format examples:
            - mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1
            - mixpeek://multimodal_extractor@v1/multilingual_e5_large_instruct_v1  (compatible with above!)
            - mixpeek://image_extractor@v1/google_siglip_base_v1  (different model = incompatible)

        Short form without the output segment is allowed only if the extractor
        has

        a single vector output.
    StageType:
      type: string
      enum:
        - filter
        - sort
        - reduce
        - apply
        - enrich
      title: StageType
      description: >-
        Categorisation of stage behaviour within a retrieval flow.


        These functional categories describe how stages transform the document
        stream:


        - FILTER: N → ≤N documents (subset, same schema)

        - SORT: N → N documents (same docs, different order, same schema)

        - REDUCE: N → 1 document (aggregation, new schema)

        - APPLY: N → N or N*M documents (enrichment/expansion, expanded/new
        schema)

        - ENRICH: N → N documents (enrichment with computed fields)
    RetrieverInputSchemaFieldType:
      type: string
      enum:
        - string
        - number
        - integer
        - float
        - boolean
        - object
        - array
        - date
        - datetime
        - text
        - image
        - audio
        - video
        - pdf
        - excel
        - document_reference
      title: RetrieverInputSchemaFieldType
      description: >-
        Supported data types for retriever input schema fields.


        Retriever input schemas define what parameters users can provide when
        executing

        a retriever. This includes all bucket schema types plus additional
        reference types.


        Types fall into three categories:


        1. **Metadata Types** (JSON types):
           - Standard JSON-compatible types
           - Examples: string, number, boolean, date
           - Inherited from BucketSchemaFieldType

        2. **File Types** (blobs):
           - Users can upload files/content as search inputs
           - Examples: text, image, video, pdf
           - Inherited from BucketSchemaFieldType

        3. **Reference Types** (structured metadata):
           - Special types for referencing existing documents
           - Examples: document_reference
           - Only available in retriever input schemas (NOT in bucket schemas)

        **DOCUMENT_REFERENCE Usage**:
            Accept document reference for "find similar" queries.

            Example - Find similar products retriever:
            {
                "reference_product": {
                    "type": "document_reference",
                    "description": "Find products similar to this one",
                    "required": true
                }
            }

            Execution input:
            {
                "inputs": {
                    "reference_product": {
                        "collection_id": "col_products",
                        "document_id": "doc_item_123"
                    }
                }
            }

            The system will use the pre-computed features from doc_item_123
            to find similar documents without re-processing.

````