List Retriever Templates

List retriever templates (system + organization + user).

Supports filtering, sorting, and search like other list operations.

Request Body (optional):

• filters: Attribute-based filters {"AND": [{"field": "category", "operator": "eq", "value": "semantic_search"}]}
• sort: Sort options {"field": "name", "direction": "asc"}
• search: Wildcard search across template_id, name, description, tags
• scope: Filter by scope (system, organization, user)
• category: Filter by category
• is_active: Show only active templates (default: true)
• tags: Filter by tags (templates must have ALL specified tags)

POST /v1/templates/retrievers

List Retriever Templates

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/templates/retrievers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "filters": {},
  "sort": {},
  "search": "<string>",
  "category": "<string>",
  "is_active": true,
  "tags": [
    "<string>"
  ]
}
'

200

{
  "results": [
    {
      "template_id": "<string>",
      "internal_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "configuration": {},
      "mode": "config",
      "category": "<string>",
      "tags": [
        "<string>"
      ],
      "is_active": true,
      "is_public": false,
      "use_cases": [
        "<string>"
      ],
      "requirements": [
        "<string>"
      ],
      "created_by": "<string>",
      "source_resource_id": "<string>",
      "sample_namespace_id": "<string>",
      "example_queries": [
        "<string>"
      ],
      "whats_inside": "<string>",
      "materialize_estimate": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total_count": 123
}

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 header returns 403; an invalid or revoked key returns 401.

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.

Body

application/json

Request model for listing templates.

Provides the same filtering, sorting, and search capabilities as other list operations (list collections, list buckets, etc.).

filters · Filters · object | null

Filters to apply when listing templates. Format: {"AND": [{"field": "field_name", "operator": "eq", "value": "value"}]}

sort · Sort · object | null

Sort options for the results. Format: {'field': 'name', 'direction': 'asc'}

Show child attributes

search · string | null

Search term for wildcard search across template_id, name, description, and tags

scope · enum<string> | null

Filter by scope (system, organization, or user)

Available options: system, organization, user, public

category · string | null

Filter by category

is_active · boolean · default: true

Show only active templates

tags · string[] | null

Filter by tags (templates must have ALL specified tags)

Response

200

application/json

Successful Response

Response model for listing templates.

results · BaseTemplateModel · object[] · required

List of templates

Show child attributes

total_count · integer · required

Total number of templates matching the query