Skip to main content
POST
/
v1
/
retrievers
Create Retriever
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "retriever_name": "<string>",
  "description": "<string>",
  "collection_identifiers": [
    "my_collection",
    "products"
  ],
  "stages": [
    {
      "config": {
        "parameters": {
          "feature_uris": [
            {
              "input": {
                "text": "{{INPUT.query_text}}"
              },
              "uri": "urn:embedding:text:bge_base_en_v1_5:1"
            }
          ],
          "limit": 100
        },
        "stage_id": "feature_filter"
      },
      "description": "Feature filter stage with uppercase template namespace",
      "stage_name": "semantic_search",
      "stage_type": "filter"
    }
  ],
  "input_schema": {
    "category": {
      "description": "Filter by category",
      "examples": [
        "electronics",
        "clothing"
      ],
      "required": false,
      "type": "string"
    },
    "query": {
      "description": "Search query text",
      "examples": [
        "red sports car",
        "sunset over ocean"
      ],
      "required": true,
      "type": "text"
    }
  },
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  },
  "tags": [
    "<string>"
  ]
}'
{
  "retriever": {
    "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"
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Body

application/json

Payload for creating a new retriever.

​
retriever_name
string
required

Unique retriever name (REQUIRED).

Minimum length: 1
​
collection_identifiers
string[]
required

Collection identifiers (names or IDs) queried by the retriever (REQUIRED). Identifiers can be collection names (e.g., 'my_collection') or collection IDs (e.g., 'col_abc123'). The system will resolve names to IDs automatically.

Minimum length: 1
Examples:
["my_collection", "products"]
["col_abc123", "col_def456"]
​
stages
StageConfig · object[]
required

Ordered stage configurations (REQUIRED).

Minimum length: 1
​
description
string | null

Human readable retriever description (OPTIONAL).

​
input_schema
object

Input schema properties keyed by field name (REQUIRED). 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.

Examples:
{
  "category": {
    "description": "Filter by category",
    "examples": ["electronics", "clothing"],
    "required": false,
    "type": "string"
  },
  "query": {
    "description": "Search query text",
    "examples": ["red sports car", "sunset over ocean"],
    "required": true,
    "type": "text"
  }
}
​
budget_limits
object

Budget limits for execution (OPTIONAL).

Examples:
{ "max_credits": 100, "max_time_ms": 60000 }
{ "max_time_ms": 120000 }
​
tags
string[]

Optional retriever tags for search/filters.

Response

Successful Response

Response after creating a retriever.

​
retriever
object
required

Created retriever configuration.

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