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' \
  --data '{
  "retriever_name": "product_search_v1",
  "description": "CLIP + metadata prefiltering",
  "input_schema": {
    "properties": {}
  },
  "collection_ids": [
    "col_products_v1"
  ],
  "stages": [
    {
      "stage_name": "<string>",
      "version": "<string>",
      "parameters": {},
      "pre_filters": {
        "AND": [
          {
            "field": "name",
            "operator": "eq",
            "value": "John"
          },
          {
            "field": "age",
            "operator": "gte",
            "value": 30
          }
        ],
        "OR": [
          {
            "field": "status",
            "operator": "eq",
            "value": "active"
          },
          {
            "field": "role",
            "operator": "eq",
            "value": "admin"
          }
        ],
        "NOT": [
          {
            "field": "department",
            "operator": "eq",
            "value": "HR"
          },
          {
            "field": "location",
            "operator": "eq",
            "value": "remote"
          }
        ],
        "case_sensitive": true
      },
      "post_filters": {
        "AND": [
          {
            "field": "name",
            "operator": "eq",
            "value": "John"
          },
          {
            "field": "age",
            "operator": "gte",
            "value": 30
          }
        ],
        "OR": [
          {
            "field": "status",
            "operator": "eq",
            "value": "active"
          },
          {
            "field": "role",
            "operator": "eq",
            "value": "admin"
          }
        ],
        "NOT": [
          {
            "field": "department",
            "operator": "eq",
            "value": "HR"
          },
          {
            "field": "location",
            "operator": "eq",
            "value": "remote"
          }
        ],
        "case_sensitive": true
      },
      "stats": {
        "avg_execution_ms": 0,
        "execution_count": 0,
        "error_count": 0,
        "last_executed_at": "2023-11-07T05:31:56Z"
      }
    }
  ],
  "metadata": {},
  "tags": [
    "<string>"
  ],
  "enabled": true
}'
{
  "retriever_id": "<string>",
  "retriever_name": "<string>",
  "description": "<string>",
  "input_schema": {
    "properties": {}
  },
  "collection_ids": [
    "<string>"
  ],
  "stages": [
    {
      "stage_name": "<string>",
      "version": "<string>",
      "parameters": {},
      "pre_filters": {
        "AND": [
          {
            "field": "name",
            "operator": "eq",
            "value": "John"
          },
          {
            "field": "age",
            "operator": "gte",
            "value": 30
          }
        ],
        "OR": [
          {
            "field": "status",
            "operator": "eq",
            "value": "active"
          },
          {
            "field": "role",
            "operator": "eq",
            "value": "admin"
          }
        ],
        "NOT": [
          {
            "field": "department",
            "operator": "eq",
            "value": "HR"
          },
          {
            "field": "location",
            "operator": "eq",
            "value": "remote"
          }
        ],
        "case_sensitive": true
      },
      "post_filters": {
        "AND": [
          {
            "field": "name",
            "operator": "eq",
            "value": "John"
          },
          {
            "field": "age",
            "operator": "gte",
            "value": 30
          }
        ],
        "OR": [
          {
            "field": "status",
            "operator": "eq",
            "value": "active"
          },
          {
            "field": "role",
            "operator": "eq",
            "value": "admin"
          }
        ],
        "NOT": [
          {
            "field": "department",
            "operator": "eq",
            "value": "HR"
          },
          {
            "field": "location",
            "operator": "eq",
            "value": "remote"
          }
        ],
        "case_sensitive": true
      },
      "stats": {
        "avg_execution_ms": 0,
        "execution_count": 0,
        "error_count": 0,
        "last_executed_at": "2023-11-07T05:31:56Z"
      }
    }
  ],
  "cache_config": {
    "enabled": true,
    "ttl_seconds": 3600,
    "stage": "retrieval",
    "exclude_fields": [
      "<string>"
    ],
    "stats": {
      "hit_count": 0,
      "miss_count": 0,
      "hit_rate": 0,
      "size_bytes": 0,
      "entry_count": 0,
      "last_invalidated_at": "2023-11-07T05:31:56Z"
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "last_executed_at": "2023-11-07T05:31:56Z",
  "enabled": true,
  "status": "active",
  "usage_stats": {
    "total_queries": 0,
    "queries_last_24h": 0,
    "avg_latency_ms": 0,
    "error_rate": 0,
    "last_error": "<string>",
    "cache_hit_rate": 0.5
  },
  "collections": [
    {
      "collection_id": "<string>",
      "collection_name": "<string>",
      "document_count": 123,
      "enabled": true,
      "last_indexed_at": "2023-11-07T05:31:56Z"
    }
  ],
  "metadata": {},
  "tags": [
    "<string>"
  ],
  "created_by": {
    "user_id": "<string>",
    "email": "<string>",
    "name": "<string>"
  },
  "updated_by": {
    "user_id": "<string>",
    "email": "<string>",
    "name": "<string>"
  },
  "version": 1,
  "revision_history": [
    {
      "version": 123,
      "updated_at": "2023-11-07T05:31:56Z",
      "updated_by": "<string>",
      "changes": "<string>"
    }
  ],
  "health": {
    "status": "healthy",
    "last_check": "2023-11-07T05:31:56Z",
    "issues": [
      "<string>"
    ]
  }
}

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 | null

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. Example: 'Bearer sk_1234567890abcdef'

​
X-Namespace
string | null

Optional namespace for data isolation. This can be a namespace name or namespace ID. Example: 'netflix_prod' or 'ns_1234567890'. To create a namespace, use the /namespaces endpoint.

Body

application/json

The retriever creation request.

​
retriever_name
string
required

Human-readable retriever name

Examples:

"product_search_v1"

​
input_schema
object
required

Schema defining the expected input format

​
collection_ids
string[]
required

List of collection IDs to search in

Examples:
["col_products_v1"]
​
stages
StageInstanceConfig · object[]
required

List of stages to execute in order

​
description
string | null

Description of the retriever

Examples:

"CLIP + metadata prefiltering"

​
metadata
object

Custom metadata for the retriever

​
tags
string[]

Tags for organization and filtering

​
enabled
boolean
default:true

Whether the retriever should be enabled on creation

Response

Successful Response

Retriever model.

​
retriever_name
string
required

Name of the retriever

​
input_schema
object
required

Input schema for the retriever

​
collection_ids
string[]
required

List of collection IDs

​
stages
StageInstanceConfig · object[]
required

List of stage configurations

​
retriever_id
string

Unique identifier for the retriever

​
description
string | null

Description of the retriever

​
cache_config
object | null

Cache configuration for this retriever. If not provided, caching is disabled. Configuration for retriever result caching.

Controls how retriever results are cached to improve performance and reduce redundant compute.

​
created_at
string<date-time>

When the retriever was created

​
updated_at
string<date-time>

When the retriever was last modified

​
last_executed_at
string<date-time> | null

When the retriever was last executed

​
enabled
boolean
default:true

Whether the retriever is enabled (can be toggled on/off)

​
status
enum<string>

Current operational status

Available options:
active,
draft,
disabled,
error
​
usage_stats
object | null

Usage and performance statistics Usage statistics for a retriever.

​
collections
CollectionDetail · object[] | null

Expanded collection details with names and metadata

​
metadata
object

Custom key-value metadata

​
tags
string[]

Tags for organization and filtering

​
created_by
object | null

Information about who created this retriever Information about who created or updated a resource.

​
updated_by
object | null

Information about who last updated this retriever Information about who created or updated a resource.

​
version
integer
default:1

Version number (increments on each update)

​
revision_history
RevisionHistoryEntry · object[]

History of changes (optional, last N changes)

​
health
object | null

Health status and diagnostics Health check information for a retriever.

⌘I