Get Retriever

Get a retriever by ID or name.

GET /v1/retrievers/{retriever_id}

Get Retriever

cURL

curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Namespace: <api-key>'

200

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

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

retriever_id · string · required

Retriever ID or name.

Response

200

application/json

Successful Response

Retriever configuration model exposed via API.

retriever_name · string · required

Unique retriever name within namespace (REQUIRED).

Minimum string length: 1

stages · StageConfig · object[] · required

Ordered list of stage configurations (REQUIRED).

Minimum array length: 1

Show child attributes

fusion · string | null · required

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

collection_identifiers · string[] · required · read-only

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

retriever_id · string

Stable retriever identifier (REQUIRED).

description · string | null

Detailed description of retriever behaviour (OPTIONAL).

collection_ids · string[]

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

input_schema · Input Schema · object

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

Show child attributes

budget_limits · BudgetLimits · object

Execution budget limits for the retriever (OPTIONAL).

Show child attributes

Examples:

{ "max_credits": 100, "max_time_ms": 60000 }

{ "max_time_ms": 120000 }

feature_dependencies · FeatureAddress · object[] | null

Feature addresses required by stages (OPTIONAL, aids validation).

Show child attributes

tags · string[]

Arbitrary tags to help organise retrievers (OPTIONAL).

metadata · Metadata · object

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_config · Display Config · object | null

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 · integer · default: 1

Version number that increments on each update (REQUIRED).

Required range: x >= 1

created_at · string<date-time>

Creation timestamp in UTC (REQUIRED).

updated_at · string<date-time>

Last update timestamp in UTC (REQUIRED).

created_by · string | null

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

updated_by · string | null

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

is_published · boolean · default: false

Whether this retriever is currently published (either as public retriever or in marketplace)

marketplace_listing_id · string | null

Marketplace listing ID if this retriever is published to the marketplace, None otherwise