List Retrievers

List all retrievers in the namespace.

POST /v1/retrievers/list

List Retrievers

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "search": "<string>",
  "filters": {},
  "sorts": [
    {}
  ],
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "case_sensitive": false
}
'

200

{
  "results": [
    {
      "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"
        }
      ]
    }
  ],
  "total": 0,
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>",
    "next_cursor": "<string>"
  },
  "warnings": [
    {
      "resource": "taxonomy",
      "reason": "not found in namespace",
      "next_step": "Fix the taxonomy_id on the stage, or create the taxonomy.",
      "id": "tax_abc123",
      "stage": "<string>"
    }
  ]
}

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.

Query Parameters

limit · integer | null

Required range: 1 <= x <= 1000

page_size · integer | null

Required range: 1 <= x <= 1000

offset · integer | null

Required range: 0 <= x <= 10000

page · integer | null

Required range: x >= 1

cursor · string | null

next_cursor · string | null

after · string | null

include_total · boolean · default: false

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request to list retrievers.

search · string | null

Search term for wildcard search across retriever_id, retriever_name, description, and other text fields

filters · Filters · object | null

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 · Sorts · object[] | null

Sort options for the retriever list

sort · SortOption · object | null

Single sort option (alias for the first entry of sorts). Every other list resource accepts this shape, so callers reach for it here too; without it, a sort on retrievers was silently dropped and DESC returned ASC order (class).

Show child attributes

case_sensitive · boolean · default: false

If True, filters and search will be case-sensitive

Response

200

application/json

Successful Response

Response from listing retrievers.

results · RetrieverModel · object[]

List of retrievers in the namespace.

Show child attributes

total · integer · default: 0

Total number of retrievers.

pagination · PaginationResponse · object | null

Pagination details (next/previous cursors and total).

Show child attributes

warnings · DegradedEntry · object[]

Why this page may not be the whole answer. An entry with resource 'namespace' and reason 'unresolved' means X-Namespace did not resolve for this API key, so the empty list is not that namespace's contents (the same condition as the X-Namespace-Unresolved response header). Empty when the namespace resolved.

Show child attributes