Skip to main content
PATCH
/
v1
/
retrievers
/
{retriever_id}
Patch Retriever
curl --request PATCH \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id} \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "retriever_name": "product_search_v2",
  "description": "Enhanced version with better caching",
  "tags": [
    "production",
    "v2"
  ],
  "display_config": {
    "components": {
      "result_card": {
        "card_click_action": "viewDetails",
        "field_order": [
          "title",
          "description",
          "price"
        ],
        "layout": "vertical",
        "show_find_similar": true,
        "show_thumbnail": true
      },
      "result_layout": "grid",
      "show_hero": true,
      "show_results_header": true,
      "show_search": true
    },
    "custom_cta": {
      "label": "Search Tips",
      "markdown_content": "# Search Tips\n\n- Use quotes for exact phrases\n- Try descriptive terms"
    },
    "description": "Search through our product catalog",
    "exposed_fields": [
      "title",
      "description",
      "price",
      "image_url"
    ],
    "field_config": {
      "price": {
        "format": "number",
        "format_options": {
          "decimals": 2,
          "label": "Price",
          "prefix": "$"
        }
      },
      "title": {
        "format": "text",
        "format_options": {
          "label": "Product Name",
          "truncate_chars": 60
        }
      }
    },
    "field_mappings": {
      "thumbnail": "image_url",
      "title": "title"
    },
    "inputs": [
      {
        "field_name": "query",
        "field_schema": {
          "description": "Search query",
          "examples": [
            "wireless headphones",
            "laptop"
          ],
          "type": "string"
        },
        "input_type": "text",
        "label": "Search Products",
        "order": 0,
        "placeholder": "What are you looking for?",
        "required": true
      }
    ],
    "layout": {
      "columns": 3,
      "gap": "16px",
      "mode": "grid"
    },
    "logo_url": "https://example.com/logo.png",
    "markdowns": [
      {
        "content": "# AI-Powered Product Search\n\nOur search uses **machine learning** to understand your queries and find the most relevant products.\n\n## Features\n\n- **Semantic Search**: Understands meaning, not just keywords\n- **Visual Search**: Upload images to find similar products\n- **Smart Filters**: Automatically suggests relevant filters",
        "title": "How it Works"
      },
      {
        "content": "## Tips for Better Results\n\n1. Use descriptive terms (e.g., \"wireless noise-canceling headphones\")\n2. Try different keywords if you don't find what you're looking for\n3. Use filters to narrow down results\n\n*Happy searching!*",
        "title": "Search Guide"
      }
    ],
    "template_type": "media-search",
    "theme": {
      "border_radius": "12px",
      "card_style": "elevated",
      "font_family": "Inter, sans-serif",
      "primary_color": "#007AFF"
    },
    "title": "Product Search"
  }
}
EOF
{
  "retriever": {
    "retriever_name": "<string>",
    "stages": [
      {
        "stage_name": "<string>",
        "config": {},
        "stage_type": "filter",
        "batch_size": "<string>",
        "description": "<string>"
      }
    ],
    "retriever_id": "<string>",
    "description": "<string>",
    "collection_ids": [
      "<string>"
    ],
    "input_schema": {},
    "budget_limits": {
      "max_credits": 1,
      "max_time_ms": 1
    },
    "feature_dependencies": [
      {
        "extractor": "<string>",
        "version": "<string>",
        "scheme": "mixpeek",
        "output": "<string>"
      }
    ],
    "tags": [
      "<string>"
    ],
    "display_config": {},
    "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: 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 YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

​
X-Namespace
string

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 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
  • display_config: Update display configuration for publishing

❌ 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)
  • budget_limits: Budget constraints (affects execution behavior)

Need to Modify Core Logic? Use POST /retrievers/{retriever_id}/clone instead. Cloning creates a new retriever with a new ID, allowing you to:

  • Fix typos in stage names
  • Add or remove stages
  • Change target collections
  • Modify input schema or budget limits

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
  • Original retriever remains unchanged (no destructive operations)

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
  • Published retrievers maintain stable behavior for consumers
​
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"

​
tags
string[] | null

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

Example:
["production", "v2"]
​
display_config
DisplayConfig · object

Updated display configuration for public retriever UI rendering. OPTIONAL - only provide if you want to update the display settings. Defines how the search interface should appear when published.

Example:
{
  "components": {
    "result_card": {
      "card_click_action": "viewDetails",
      "field_order": ["title", "description", "price"],
      "layout": "vertical",
      "show_find_similar": true,
      "show_thumbnail": true
    },
    "result_layout": "grid",
    "show_hero": true,
    "show_results_header": true,
    "show_search": true
  },
  "custom_cta": {
    "label": "Search Tips",
    "markdown_content": "# Search Tips\n\n- Use quotes for exact phrases\n- Try descriptive terms"
  },
  "description": "Search through our product catalog",
  "exposed_fields": [
    "title",
    "description",
    "price",
    "image_url"
  ],
  "field_config": {
    "price": {
      "format": "number",
      "format_options": {
        "decimals": 2,
        "label": "Price",
        "prefix": "$"
      }
    },
    "title": {
      "format": "text",
      "format_options": {
        "label": "Product Name",
        "truncate_chars": 60
      }
    }
  },
  "field_mappings": {
    "thumbnail": "image_url",
    "title": "title"
  },
  "inputs": [
    {
      "field_name": "query",
      "field_schema": {
        "description": "Search query",
        "examples": ["wireless headphones", "laptop"],
        "type": "string"
      },
      "input_type": "text",
      "label": "Search Products",
      "order": 0,
      "placeholder": "What are you looking for?",
      "required": true
    }
  ],
  "layout": {
    "columns": 3,
    "gap": "16px",
    "mode": "grid"
  },
  "logo_url": "https://example.com/logo.png",
  "markdowns": [
    {
      "content": "# AI-Powered Product Search\n\nOur search uses **machine learning** to understand your queries and find the most relevant products.\n\n## Features\n\n- **Semantic Search**: Understands meaning, not just keywords\n- **Visual Search**: Upload images to find similar products\n- **Smart Filters**: Automatically suggests relevant filters",
      "title": "How it Works"
    },
    {
      "content": "## Tips for Better Results\n\n1. Use descriptive terms (e.g., \"wireless noise-canceling headphones\")\n2. Try different keywords if you don't find what you're looking for\n3. Use filters to narrow down results\n\n*Happy searching!*",
      "title": "Search Guide"
    }
  ],
  "template_type": "media-search",
  "theme": {
    "border_radius": "12px",
    "card_style": "elevated",
    "font_family": "Inter, sans-serif",
    "primary_color": "#007AFF"
  },
  "title": "Product Search"
}

Response

Successful Response

Response after updating a retriever.

​
retriever
RetrieverConfig · object
required

Updated retriever configuration.

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