Get Retriever

curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id} \
  --header 'Authorization: <authorization>' \
  --header 'X-Namespace: <x-namespace>'

{
  "retriever_name": "<string>",
  "collection_ids": [
    "<string>"
  ],
  "stages": [
    {
      "stage_name": "<string>",
      "config": {},
      "stage_type": "filter",
      "batch_size": "<string>",
      "description": "<string>"
    }
  ],
  "retriever_id": "<string>",
  "description": "<string>",
  "input_schema": {},
  "budget_limits": {
    "max_credits": 1,
    "max_time_ms": 1
  },
  "feature_dependencies": [
    {
      "extractor": "<string>",
      "version": "<string>",
      "scheme": "mixpeek",
      "output": "<string>"
    }
  ],
  "tags": [
    "<string>"
  ],
  "version": 1,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "updated_by": "<string>",
  "is_published": false
}

GET

retrievers

{retriever_id}

Get Retriever

curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id} \
  --header 'Authorization: <authorization>' \
  --header 'X-Namespace: <x-namespace>'

{
  "retriever_name": "<string>",
  "collection_ids": [
    "<string>"
  ],
  "stages": [
    {
      "stage_name": "<string>",
      "config": {},
      "stage_type": "filter",
      "batch_size": "<string>",
      "description": "<string>"
    }
  ],
  "retriever_id": "<string>",
  "description": "<string>",
  "input_schema": {},
  "budget_limits": {
    "max_credits": 1,
    "max_time_ms": 1
  },
  "feature_dependencies": [
    {
      "extractor": "<string>",
      "version": "<string>",
      "scheme": "mixpeek",
      "output": "<string>"
    }
  ],
  "tags": [
    "<string>"
  ],
  "version": 1,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "updated_by": "<string>",
  "is_published": false
}

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.

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'

Path Parameters

retriever_id

string

required

Retriever ID or name.

Response

Successful Response

Retriever configuration model exposed via API.

retriever_name

string

required

Unique retriever name within namespace (REQUIRED).

Minimum string length: 1

collection_ids

string[]

required

Collections queried by the retriever (REQUIRED).

Minimum array length: 1

stages

StageConfig · object[]

required

Ordered list of stage configurations (REQUIRED).

Minimum array length: 1

Show child attributes

stages.stage_name

string

required

Human-readable stage instance name (REQUIRED).

Minimum string length: 1

stages.config

Config · object

required

Stage implementation parameters (REQUIRED). Must include stage_id key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under parameters.

stages.stage_type

enum<string> | null

Functional category of the stage. Optional for creation requests; auto-inferred from stage_id when omitted.

Available options:

filter,

sort,

reduce,

apply

stages.batch_size

string | null

Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted.

stages.description

string | null

User-facing description of the stage (OPTIONAL).

retriever_id

string

Stable retriever identifier (REQUIRED).

description

string | null

Detailed description of retriever behaviour (OPTIONAL).

input_schema

Input Schema · object

JSON Schema describing expected user inputs (REQUIRED). Properties must use BucketSchemaField for consistency with ingestion schemas.

Show child attributes

input_schema.{key}

BucketSchemaField · object

Schema field definition for bucket objects.

Show child attributes

input_schema.{key}.type

enum<string>

required

Supported data types for bucket schema fields.

Types fall into two categories:

Explicit Types (Type-Safe):
- Provide type guarantees for extractors
- User must pre-classify content
- Compatible with type-specific extractors
Automatic Type (Flexible):
- No type guarantee (runtime detection)
- User doesn't pre-classify content
- Only compatible with multimodal extractors

Available options:

string,

number,

integer,

float,

boolean,

object,

array,

date,

datetime,

json,

file,

text,

image,

audio,

video,

pdf,

document,

spreadsheet,

presentation,

dense_vector,

sparse_vector,

int8_vector,

automatic

input_schema.{key}.default

unknown

input_schema.{key}.items

unknown

input_schema.{key}.properties

Properties · object

input_schema.{key}.examples

any[] | null

OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.

input_schema.{key}.description

string | null

input_schema.{key}.enum

any[] | null

input_schema.{key}.required

boolean | null

default:false

budget_limits

BudgetLimits · object

Execution budget limits for the retriever (OPTIONAL).

Show child attributes

budget_limits.max_credits

number | null

Maximum credits allowed for a single execution (OPTIONAL).

Required range: x >= 0

budget_limits.max_time_ms

integer | null

Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL).

Required range: x >= 0

feature_dependencies

FeatureAddress · object[] | null

Feature addresses required by stages (OPTIONAL, aids validation).

Show child attributes

feature_dependencies.extractor

string

required

feature_dependencies.version

string

required

feature_dependencies.scheme

string

default:mixpeek

feature_dependencies.output

string | null

Health

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

Get Retriever

Headers

Path Parameters

Response