Retrievers

Create Retriever

Changed on

Create a new retriever.

A retriever executes a series of stages to find and process documents from one or more collections.

post/v1/retrievers

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/retrievers
  • Auth: HTTP bearer and API key in header X-Namespace

Request body

retriever_namestring required

Unique retriever name (REQUIRED).

descriptionstring nullable

Human readable retriever description (OPTIONAL).

visibility'private' | 'public' | 'marketplace'

Visibility level of a retriever determining who can access it.

marketplace_listing_idstring nullable

Associated marketplace listing ID when visibility is MARKETPLACE (OPTIONAL).

requires_subscriptionboolean

Whether this retriever requires an active subscription to access (marketplace only).

collection_identifiersstring[]

Collection identifiers (names or IDs) queried by the retriever (OPTIONAL). Identifiers can be collection names (e.g., 'my_collection') or collection IDs (e.g., 'col_abc123'). The system will resolve names to IDs automatically. Can be empty for inference-only pipelines (e.g., LLM query analysis without document retrieval). Also accepts 'collection_ids' as an alias for backward compatibility.

input_schemaobject

Input schema properties keyed by field name (OPTIONAL). Can be empty for static retrievers with hardcoded stage parameters. Each field can include: type, description, required, default, and examples. The 'examples' field (list) provides sample values that will be shown to users when the retriever is published with include_metadata=true.

tagsstring[]

Optional retriever tags for search/filters.

metadataobject

Custom key-value metadata stored on the retriever (OPTIONAL). Round-trips on create/get/list and is updatable via PATCH — useful for automation markers like seed/config versions. Previously this field was silently dropped on create (FRUSTRATIONS silent-drop class).

Example request

{
  "collection_identifiers": [
    "product_embeddings"
  ],
  "input_schema": {
    "query": {
      "description": "Search query",
      "required": true,
      "type": "text"
    }
  },
  "retriever_name": "product_search",
  "stages": [
    {
      "config": {
        "parameters": {
          "final_top_k": 20,
          "searches": [
            {
              "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
              "query": {
                "input_mode": "text",
                "value": "{{INPUT.query}}"
              },
              "top_k": 100
            }
          ]
        },
        "stage_id": "feature_search"
      },
      "stage_name": "search",
      "stage_type": "filter"
    }
  ]
}

Response

Successful Response

retriever_idstring

Stable retriever identifier (REQUIRED).

retriever_namestring required

Unique retriever name within namespace (REQUIRED).

descriptionstring nullable

Detailed description of retriever behaviour (OPTIONAL).

collection_idsstring[]

Collections queried by the retriever. Can be empty for query-only inference mode.

input_schemaobject

JSON Schema describing expected user inputs (REQUIRED). Properties must use RetrieverInputSchemaField which supports all bucket types plus document_reference.

tagsstring[]

Arbitrary tags to help organise retrievers (OPTIONAL).

metadataobject

Custom key-value metadata (OPTIONAL). Round-trips on create/get/list and is updatable via PATCH — useful for automation markers like seed/config versions.

display_configobject nullable

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.

versioninteger

Version number that increments on each update (REQUIRED).

created_atstring date-time

Creation timestamp in UTC (REQUIRED).

updated_atstring date-time

Last update timestamp in UTC (REQUIRED).

created_bystring nullable

Identifier of the user who created the retriever (OPTIONAL).

updated_bystring nullable

Identifier of the user who last updated the retriever (OPTIONAL).

fusionstring nullable required

Fusion strategy used by this retriever's feature_search stage (e.g. 'learned', 'rrf', 'dbsf'). Null if no feature_search stage.

collection_identifiersstring[] required

Mirror of collection_ids under the field name CREATE accepts (collection_identifiers), so a create → read round-trip reads back the field it wrote. Always equal to collection_ids (FRUSTRATIONS 2026-07-16: SDKs/agents re-reading their own write saw collection_identifiers null and concluded the retriever was unscoped).

Example response

{
  "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_id": "attribute_filter"
      },
      "stage_name": "filter_high_spend",
      "stage_type": "filter"
    }
  ]
}

Changes

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • 5d4c905106b4Revision changes
    • info

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API