Skip to main content
PATCH
/
v1
/
retrievers
/
{retriever_id}
Patch Retriever
curl --request PATCH \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "example_desc": "Update only the name",
  "name": "product_search_v2"
}'
{
  "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"
      }
    },
    "name": "executive_ads_search",
    "pipeline_id": "pipe_abc123",
    "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"

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 pipeline logic is immutable to ensure consistency for dependent resources (taxonomies, cached results, etc.).

✅ Fields You CAN Update (Metadata Only):

  • 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: Pipeline 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
​
name
string | null

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

Minimum length: 1
Examples:

"product_search_v2"

"customer_lookup_enhanced"

​
description
string | null

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

Examples:

"Enhanced version with better caching"

"Updated for Q4 2025"

​
tags
string[] | null

Updated tags for organization and filtering. OPTIONAL - replaces existing tags if provided.

Examples:
["production", "v2"]
["experimental", "ml-enhanced"]

Response

Successful Response

Response after updating a retriever.

​
retriever
object
required

Updated 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"
    }
  },
  "name": "executive_ads_search",
  "pipeline_id": "pipe_abc123",
  "stages": [
    {
      "config": {
        "parameters": {
          "field": "metadata.spend",
          "operator": "gt",
          "value": 1000
        },
        "stage_name": "attribute_filter",
        "version": "v1"
      },
      "name": "filter_high_spend",
      "stage_type": "filter"
    }
  ]
}