Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Retrievers

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:

  1. Source retriever is copied
  2. You provide a new name (REQUIRED)
  3. Optionally override any other fields
  4. A new retriever is created with a new ID
  5. 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
post/v1/retrievers/{retriever_id}/clone

Path parameters

retriever_idstring required

Source retriever ID or name to clone.

Source retriever ID or name to clone.

Request body

retriever_namestring required

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

descriptionstring nullable

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

collection_identifiersstring[] nullable

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.

input_schemaobject nullable

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

tagsstring[] nullable

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

Example request

{
  "example_desc": "Clone with just a new name (exact copy)",
  "retriever_name": "product_search_backup"
}

Response

Successful Response

source_retriever_idstring required

ID of the source retriever that was cloned.

Example response

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