Patch Retriever

curl --request PATCH \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "retriever_name": "product_search_v2",
  "description": "Enhanced version with better caching",
  "tags": [
    "production",
    "v2"
  ]
}
'

{
  "retriever": {
    "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>"
  }
}

PATCH

retrievers

{retriever_id}

Patch Retriever

curl --request PATCH \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "retriever_name": "product_search_v2",
  "description": "Enhanced version with better caching",
  "tags": [
    "production",
    "v2"
  ]
}
'

{
  "retriever": {
    "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>"
  }
}

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.

Body

application/json

Request to update a retriever's metadata.

IMPORTANT: Partial Updates with Controlled Mutability

This endpoint allows updating ONLY metadata fields. Core retriever logic is immutable to ensure consistency for dependent resources (taxonomies, cached results, etc.).

✅ Fields You CAN Update (Metadata Only):

retriever_name: Rename the retriever
description: Update documentation
tags: Update organization tags

❌ Fields You CANNOT Update (Immutable Core Logic):

input_schema: Input field definitions (breaks dependent taxonomies)
stages: Retriever stages and configurations (changes matching behavior)
collection_ids: Target collections (changes data sources)

Behavior:

All fields are OPTIONAL - provide only what you want to update
Version number automatically increments on each update
Empty updates (no fields provided) will be rejected with 400 error
For structural changes, create a new retriever version instead

Why This Design?

Taxonomies reference retrievers by ID and expect consistent behavior
Cached results remain valid after metadata-only changes
Version tracking enables auditing and rollback

retriever_name

string | null

Updated retriever name. OPTIONAL - only provide if you want to rename the retriever.

Minimum string length: 1

Example:

"product_search_v2"

description

string | null

Updated human-readable description. OPTIONAL - only provide if you want to update the description.

Example:

"Enhanced version with better caching"

Response

Successful Response

Response after updating a retriever.

retriever

RetrieverConfig · object

required

Updated retriever configuration.

Show child attributes

retriever.retriever_name

string

required

Unique retriever name within namespace (REQUIRED).

Minimum string length: 1

retriever.collection_ids

string[]

required

Collections queried by the retriever (REQUIRED).

Minimum array length: 1

retriever.stages

StageConfig · object[]

required

Ordered list of stage configurations (REQUIRED).

Minimum array length: 1

Show child attributes

retriever.stages.stage_name

string

required

Human-readable stage instance name (REQUIRED).

Minimum string length: 1

retriever.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.

retriever.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

retriever.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.

retriever.stages.description

string | null

User-facing description of the stage (OPTIONAL).

retriever.retriever_id

string

Stable retriever identifier (REQUIRED).

retriever.description

string | null

Detailed description of retriever behaviour (OPTIONAL).

retriever.input_schema

Input Schema · object

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

Show child attributes

retriever.input_schema.{key}

BucketSchemaField · object

Schema field definition for bucket objects.

Show child attributes

retriever.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

retriever.input_schema.{key}.default

unknown

retriever.input_schema.{key}.items

unknown

retriever.input_schema.{key}.properties

Properties · object

retriever.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.

retriever.input_schema.{key}.description

string | null

retriever.input_schema.{key}.enum

any[] | null

retriever.input_schema.{key}.required

boolean | null

default:false

retriever.budget_limits

BudgetLimits · object

Execution budget limits for the retriever (OPTIONAL).

Show child attributes

retriever.budget_limits.max_credits

number | null

Maximum credits allowed for a single execution (OPTIONAL).

Required range: x >= 0

retriever.budget_limits.max_time_ms

integer | null

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

Required range: x >= 0

retriever.feature_dependencies

FeatureAddress · object[] | null

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

Show child attributes

retriever.feature_dependencies.extractor

string

required

retriever.feature_dependencies.version

string

required

retriever.feature_dependencies.scheme

string

default:mixpeek

retriever.feature_dependencies.output

string | null

retriever.tags

string[]

Arbitrary tags to help organise retrievers (OPTIONAL).

retriever.version

integer

default:1

Version number that increments on each update (REQUIRED).

Required range: x >= 1

retriever.created_at

string<date-time>

Creation timestamp in UTC (REQUIRED).

retriever.updated_at

string<date-time>

Last update timestamp in UTC (REQUIRED).

retriever.created_by

string | null

Identifier of the user who created the retriever (OPTIONAL).

retriever.updated_by

string | null

Identifier of the user who last updated the retriever (OPTIONAL).

Get Retriever Clone Retriever

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Patch Retriever

Headers

Path Parameters

Body

Response