Clone Retriever
Clone a retriever with optional modifications.
Purpose: Creates a NEW retriever (with new ID) based on an existing one. This is the recommended way to iterate on retriever designs when you need to modify core logic that PATCH doesn’t allow (stages, input_schema, collections).
Clone vs PATCH vs Template:
- PATCH: Update metadata only (name, description, tags, display_config)
- Clone: Copy and modify core logic (stages, input_schema, collections)
- Template: Start from a pre-configured pattern (for new projects)
Common Use Cases:
- Fix a typo in a stage name
- Add or remove stages
- Change target collections
- Create variants (e.g., “strict” vs “relaxed” versions)
- Test modifications before replacing production retriever
How it works:
- Source retriever is copied
- You provide a new name (REQUIRED)
- Optionally override any other fields
- A new retriever is created with a new ID
- Original retriever remains unchanged
All fields except retriever_name are OPTIONAL:
- Omit a field to copy from source
- Provide a field to override the source value
Headers
Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
"Bearer YOUR_MIXPEEK_API_KEY"
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'. Falls back to ?namespace= query parameter if the header is omitted.
"ns_abc123def456"
"production"
"my-namespace"
Path Parameters
Source retriever ID or name to clone.
Body
Request to clone a retriever with optional modifications.
Purpose: Cloning creates a NEW retriever (with new ID) based on an existing one, allowing you to make changes that aren't allowed via PATCH (stages, input_schema, collections). This is the recommended way to iterate on retriever designs.
Clone vs Template vs Version:
- Clone: Copy THIS retriever and modify it (for iteration/fixes)
- Template: Create retriever from a reusable pattern (for new projects)
- Version: (Not implemented) - Use clone instead
Use Cases:
- Fix a typo in a stage name without losing execution history
- Add/remove stages while keeping the original intact
- Change collections while preserving the original retriever
- Test modifications before replacing production retriever
- Create variants (e.g., "strict" vs "relaxed" versions)
All fields are OPTIONAL:
- Omit a field to keep the original value
- Provide a field to override the original value
- retriever_name is REQUIRED (clones must have unique names)
REQUIRED. Name for the cloned retriever. Must be unique and different from the source retriever.
1"product_search_v2"
"semantic_search_strict"
OPTIONAL. Description override. If omitted, copies from source retriever.
"Cloned from product_search with stricter filters"
OPTIONAL. Override target collections. If omitted, copies from source retriever. This allows you to apply the same retriever logic to different collections. Also accepts 'collection_ids' as an alias.
["products_v2"]OPTIONAL. Override stage configurations. If omitted, copies from source retriever. This is where you'd fix typos, add stages, or tweak parameters.
OPTIONAL. Override input schema. If omitted, copies from source retriever.
OPTIONAL. Override budget limits. If omitted, copies from source retriever.
{ "max_credits": 100, "max_time_ms": 60000 }OPTIONAL. Override tags. If omitted, copies from source retriever.
["v2", "production"]OPTIONAL. Override display configuration. If omitted, copies from source retriever.
{
"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"
],
"external_links": [
{
"name": "GitHub Repository",
"url": "https://github.com/mixpeek/product-search"
},
{
"name": "Blog Post",
"url": "https://blog.mixpeek.com/building-product-search"
}
],
"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 cloning a retriever.
Cloned retriever configuration with new retriever_id.
{
"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"
}
]
}ID of the source retriever that was cloned.