Retrievers

Patch Retriever

Changed on

Update a retriever's metadata.

Editable fields:

  • name, description, tags, display_config: metadata
  • collection_identifiers: re-points + re-validates stage feature URIs
  • stages: 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: NON-BREAKING evolution only (add default/examples/description to a field, add a new optional field). Breaking changes — removing a field, changing a type, making a field newly required — are rejected with 422 naming each one; clone the retriever for those.

budget_limits remains immutable; use POST /{retriever_id}/clone.

patch/v1/retrievers/{retriever_id}

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/retrievers/{retriever_id}
  • Auth: HTTP bearer and API key in header X-Namespace

Path parameters

retriever_idstring required

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

{
  "retriever_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_id": "attribute_filter"
        },
        "stage_name": "filter_high_spend",
        "stage_type": "filter"
      }
    ]
  }
}

Changes

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • 5d4c905106b4Revision changes
    • info

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API