Sign in

v5

OpenAPI 3.1.02026-08-025631,1012.8 MB
Retrievers

Patch Retriever

Update a retriever's metadata.

Editable fields:

  • name, description, tags, display_config: metadata
  • collection_identifiers: re-points + re-validates stage feature URIs
  • stages (BACKE-1287): edit stages in place on an UNPUBLISHED retriever (change a filter/operator/rerank without clone+repoint+delete); the full stage list is replaced + re-validated as on create. A PUBLISHED retriever's stages stay immutable — clone or unpublish to change them.

input_schema and budget_limits remain immutable; use POST /{retriever_id}/clone.

patch/v1/retrievers/{retriever_id}

Path parameters

retriever_idstring required

Retriever ID or name.

Retriever ID or name.

Request body

retriever_namestring nullable

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

descriptionstring nullable

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

visibility'private' | 'public' | 'marketplace'

Visibility level of a retriever determining who can access it.

marketplace_listing_idstring nullable

Updated marketplace listing ID. OPTIONAL - only provide if you want to update the marketplace listing.

requires_subscriptionboolean nullable

Updated subscription requirement. OPTIONAL - only provide if you want to change the subscription requirement.

tagsstring[] nullable

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

metadataobject nullable

Updated custom key-value metadata. OPTIONAL - replaces existing metadata if provided.

collection_identifiersstring[] nullable

Updated target collection IDs or names. OPTIONAL - provide to re-point the retriever at different collections. Feature URIs in stages will be re-validated against the new collections.

input_schemaobject nullable

OPTIONAL. Update the input field definitions — but ONLY as a NON-BREAKING evolution of the current schema, so dependent taxonomies and existing callers keep working. Allowed: add default/examples/description to existing fields (e.g. clickable default queries in Studio), add a new OPTIONAL field. REJECTED (422, with the specific reason): removing a field, changing a field's type, or making a field newly required. For those breaking changes, clone the retriever. The full schema is REPLACED after the non-breaking check passes.

Example request

{
  "example_desc": "Update only the name",
  "name": "product_search_v2"
}

Response

Successful Response

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