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_uri": "mixpeek://text_extractor@v1/embedding",
          "query_text": "{{INPUT.query_text}}",
          "top_k": 100
        },
        "stage_id": "hybrid_search"
      },
      "description": "Hybrid search stage with uppercase template namespace",
      "stage_name": "semantic_search",
      "stage_type": "filter"
    }
  ],
  "input_schema": {},
  "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).

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