Skip to main content
POST
/
v1
/
retrievers
/
{retriever_id}
/
clone
Clone Retriever
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/clone \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "retriever_name": "<string>",
  "description": "Cloned from product_search with stricter filters",
  "collection_identifiers": [
    "products_v2"
  ],
  "stages": [
    {
      "stage_name": "<string>",
      "config": {},
      "stage_type": "filter",
      "batch_size": "<string>",
      "description": "<string>"
    }
  ],
  "input_schema": {},
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  },
  "tags": [
    "v2",
    "production"
  ],
  "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>"
  },
  "source_retriever_id": "<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

Source retriever ID or name to clone.

Body

application/json

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)
​
retriever_name
string
required

REQUIRED. Name for the cloned retriever. Must be unique and different from the source retriever.

Minimum string length: 1
Examples:

"product_search_v2"

"semantic_search_strict"

​
description
string | null

OPTIONAL. Description override. If omitted, copies from source retriever.

Example:

"Cloned from product_search with stricter filters"

​
collection_identifiers
string[] | null

OPTIONAL. Override target collections. If omitted, copies from source retriever. This allows you to apply the same retriever logic to different collections.

Example:
["products_v2"]
​
stages
StageConfig · object[] | null

OPTIONAL. Override stage configurations. If omitted, copies from source retriever. This is where you'd fix typos, add stages, or tweak parameters.

​
input_schema
Input Schema · object

OPTIONAL. Override input schema. If omitted, copies from source retriever.

​
budget_limits
BudgetLimits · object

OPTIONAL. Override budget limits. If omitted, copies from source retriever.

Example:
{ "max_credits": 100, "max_time_ms": 60000 }
​
tags
string[] | null

OPTIONAL. Override tags. If omitted, copies from source retriever.

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

OPTIONAL. Override display configuration. If omitted, copies from source retriever.

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

​
retriever
RetrieverConfig · object
required

Cloned retriever configuration with new retriever_id.

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"
    }
  ]
}
​
source_retriever_id
string
required

ID of the source retriever that was cloned.