---
title: "Patch Retriever"
method: PATCH
path: "/v1/retrievers/{retriever_id}"
tags: ["Retrievers"]
---

# Patch Retriever

`PATCH /v1/retrievers/{retriever_id}`

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.

## Path parameters

- `retriever_id` string, required — Retriever ID or name.

## Request body

- PatchRetrieverRequest — Request to update a retriever's metadata. **IMPORTANT: Partial Updates with Controlled Mutability** This endpoint allows updating ONLY metadata fields. Core retriever logic is immutable to ensure consistency for dependent resources (taxonomies, cached results, etc.). **✅ Fields You CAN Update (Metadata Only):** - `retriever_name`: Rename the retriever - `description`: Update documentation - `tags`: Update organization tags - `display_config`: Update display configuration for publishing **✅ Fields You CAN Also Update (With Re-validation):** - `collection_identifiers`: Target collections (re-validates feature URIs in stages) **✅ Fields You CAN Update on UNPUBLISHED retrievers (With Re-validation):** - `stages`: Retriever stages/configs (BACKE-1287). Edit a filter/operator/rerank in place instead of clone+repoint+delete. Re-validated as on create; a PUBLISHED retriever's stages stay immutable (clone/unpublish to change). **❌ Fields You CANNOT Update (Immutable Core Logic):** - `input_schema`: Input field definitions (breaks dependent taxonomies) - `budget_limits`: Budget constraints (affects execution behavior) **Need to Modify Core Logic?** Use POST /retrievers/{retriever_id}/clone instead. Cloning creates a new retriever with a new ID, allowing you to: - Fix typos in stage names - Add or remove stages - Change target collections - Modify input schema or budget limits **Behavior:** - All fields are OPTIONAL - provide only what you want to update - Version number automatically increments on each update - Empty updates (no fields provided) will be rejected with 400 error - Original retriever remains unchanged (no destructive operations) **Why This Design?** - Taxonomies reference retrievers by ID and expect consistent behavior - Cached results remain valid after metadata-only changes - Version tracking enables auditing and rollback - Published retrievers maintain stable behavior for consumers
  - `retriever_name` string, nullable — Updated retriever name. OPTIONAL - only provide if you want to rename the retriever.
  - `description` string, 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_id` string, nullable — Updated marketplace listing ID. OPTIONAL - only provide if you want to update the marketplace listing.
  - `requires_subscription` boolean, nullable — Updated subscription requirement. OPTIONAL - only provide if you want to change the subscription requirement.
  - `tags` string[], nullable — Updated tags for organization and filtering. OPTIONAL - replaces existing tags if provided.
  - `metadata` object, nullable — Updated custom key-value metadata. OPTIONAL - replaces existing metadata if provided.
  - `display_config` DisplayConfigInput — Display configuration for public retriever UI. This model defines how the public search interface should be rendered, including input fields, theme, layout, and result card configuration. The frontend (mxp.co) uses this to dynamically build the UI without hardcoded components.
    - `title` string, required — Title/heading for the public search page
    - `description` string, nullable — Optional description/subtitle for the page
    - `logo_url` string, nullable — URL to logo image
    - `icon_base64` string, nullable — Base64 encoded icon/favicon (data URI format recommended). Max size: ~200KB encoded. Use for small icons that should be embedded. Example: 'data:image/png;base64,iVBORw0KGgo...'
    - `seo` SEOConfig — SEO configuration for public retriever discoverability. Auto-generated during publishing with sensible defaults inferred from the retriever's display_config. All fields can be overridden manually. This configuration controls how the public retriever appears in: - Search engine results (Google, Bing, etc.) - Social media shares (Twitter, Facebook, LinkedIn) - Link previews in messaging apps
      - `meta_title` string, nullable — SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided.
      - `meta_description` string, nullable — Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided.
      - `keywords` string[] — Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags.
      - `og_image_url` string, nullable — URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing.
      - `og_image_alt` string, nullable — Alt text for OG image (accessibility and SEO)
      - `og_type` string — Open Graph content type
      - `twitter_card` string — Twitter card display style
      - `twitter_site` string, nullable — Twitter @handle for the site
      - `twitter_creator` string, nullable — Twitter @handle for content creator (optional)
      - `robots` string — Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines.
      - `canonical_url` string, nullable — Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided.
      - `site_name` string — Site name for OG tags and branding
      - `author` string, nullable — Content author/creator name
      - `locale` string — Content language/locale
      - `logo_url` string, nullable — URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results.
      - `favicon_url` string, nullable — URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon.
      - `structured_data` StructuredDataConfig — Schema.org structured data configuration for search engines. Enables rich search results and better understanding of the page content.
        - `type` string — Schema.org type for structured data
        - `additional_properties` object — Additional Schema.org properties
    - `markdowns` MarkdownContent[] — Array of markdown content sections for documentation, guides, or informational modals. Each section has a title and markdown-formatted content. Displayed in modals, expandable sections, or tabs on the public interface. Examples: 'How it Works', 'Search Guide', 'About', 'FAQ', etc.
      - `title` string, required — Title for the markdown content section
      - `content` string, required — Markdown-formatted content. Supports standard markdown syntax including headers, lists, links, images, code blocks, and emphasis. Limited to 50KB to prevent database issues.
    - `theme` ThemeConfig — Theme configuration for public retriever UI. Defines colors, fonts, and visual styling for the public search interface.
      - `primary_color` string — Primary brand color (hex code)
      - `secondary_color` string, nullable — Secondary/accent color (hex code)
      - `font_family` string — Font family for text
      - `background_color` string — Background color (hex code)
      - `text_color` string — Primary text color (hex code)
      - `heading_font_family` string, nullable — Optional separate font family for headings
      - `surface_color` string, nullable — Surface/card background color (hex code)
      - `muted_color` string, nullable — Muted/secondary text color (hex code)
      - `border_color` string, nullable — Border color for cards and elements (hex code)
      - `border_radius` string, nullable — Default border radius for cards and elements
      - `card_style` string, nullable — Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect)
      - `card_hover_effect` string, nullable — Card hover animation effect: lift (move up), glow, scale, or none
    - `inputs` InputRenderingConfigInput[], required — List of input fields to render in the search interface. Each input maps to a field in the retriever's input_schema. Frontend uses the field_schema to render the appropriate component type.
      - `field_name` string, required — Name of the input field (matches retriever input_schema key)
      - `field_schema` RetrieverInputSchemaFieldInput, required — Schema field definition for retriever input parameters. Identical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType which includes additional reference types like document_reference. This allows retrievers to accept: 1. Metadata inputs (strings, numbers, dates, etc.) 2. File inputs (images, videos, documents for search) 3. Reference inputs (document_reference for "find similar" queries)
        - `type` 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'object' | 'array' | 'date' | 'datetime' | 'text' | 'image' | 'audio' | 'video' | 'pdf' | 'excel' | 'document_reference', required — Supported data types for retriever input schema fields. Retriever input schemas define what parameters users can provide when executing a retriever. This includes all bucket schema types plus additional reference types. Types fall into three categories: 1. **Metadata Types** (JSON types): - Standard JSON-compatible types - Examples: string, number, boolean, date - Inherited from BucketSchemaFieldType 2. **File Types** (blobs): - Users can upload files/content as search inputs - Examples: text, image, video, pdf - Inherited from BucketSchemaFieldType 3. **Reference Types** (structured metadata): - Special types for referencing existing documents - Examples: document_reference - Only available in retriever input schemas (NOT in bucket schemas) **DOCUMENT_REFERENCE Usage**: Accept document reference for "find similar" queries. Example - Find similar products retriever: { "reference_product": { "type": "document_reference", "description": "Find products similar to this one", "required": true } } Execution input: { "inputs": { "reference_product": { "collection_id": "col_products", "document_id": "doc_item_123" } } } The system will use the pre-computed features from doc_item_123 to find similar documents without re-processing.
        - `default` unknown
        - `items` RetrieverInputSchemaFieldInput — recursive
        - `properties` object, nullable
        - `examples` unknown[], nullable — OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.
          - unknown
        - `description` string, nullable
        - `enum` unknown[], nullable
          - unknown
        - `required` boolean, nullable
      - `input_type` string — UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice)
      - `label` string, required — Human-readable label for the input
      - `placeholder` string, nullable — Placeholder text for the input
      - `helper_text` string, nullable — Helper text displayed below the input to guide users
      - `suggestions` string[], nullable — Pre-filled suggestion chips that users can click to populate the input
      - `required` boolean — Whether this input is required
      - `order` integer — Display order (lower numbers appear first)
    - `layout` LayoutConfig — Layout configuration for search results display.
      - `mode` string — Display mode for results
      - `columns` integer — Number of columns for grid/masonry layouts
      - `gap` string — Gap between items
      - `full_width` boolean — Whether to use full viewport width for the layout (edge-to-edge)
    - `exposed_fields` string[], required — List of document metadata fields to show in results. Only these fields are returned to end users.
    - `components` ComponentsConfig — Configuration for UI components.
      - `show_hero` boolean — Whether to show the hero section with title and description
      - `show_search` boolean — Whether to show search input fields
      - `show_filters` boolean — Whether to show filters sidebar
      - `show_results_header` boolean — Whether to show the results header with count and sorting options
      - `result_layout` string — Layout mode for results display
      - `result_card` ResultCardProperties — Properties for result card display configuration.
        - `layout` string — Card layout orientation
        - `show_thumbnail` boolean — Whether to show thumbnail image in results
        - `thumbnail_aspect_ratio` string — Aspect ratio for thumbnail images
        - `thumbnail_fit` string — How thumbnail should fit in container
        - `show_score` boolean — Whether to display relevance score
        - `truncate_title` integer, nullable — Maximum characters for title before truncation
        - `truncate_description` integer, nullable — Maximum characters for description before truncation
        - `field_order` string[] — Order of fields to display in result card. Fields not in this list won't be shown. Must be subset of exposed_fields.
        - `show_find_similar` boolean — Whether to show a 'Find Similar' button on result cards
        - `card_click_action` string — Action when card is clicked: none (no action), findSimilar (trigger similar search), viewDetails (open detail modal)
        - `thumbnail_field` string, nullable — Field name to use as thumbnail image source
        - `title_field` string, nullable — Field name to use as card title
        - `card_fields` string[], nullable — Fields to display on the card (alternative to field_order for template compatibility)
        - `modal_fields` string[], nullable — Fields to display in the detail modal when card is clicked
        - `card_style` string, nullable — Card style preset: default, portrait-discovery, media-search, document-search, or custom template-specific styles
    - `field_config` object — Configuration for how each field should be displayed. Keys are field names (must be subset of exposed_fields). Values are FieldConfig objects specifying format and display options.
    - `custom_cta` CustomCTA — Optional custom button in header that opens a markdown modal. Allows users to add a custom call-to-action button in the header bar that opens a modal with markdown content when clicked.
      - `label` string, required — Button label text displayed in the header
      - `markdown_content` string, required — Markdown content displayed in the modal when button is clicked. Supports standard markdown syntax.
    - `external_links` ExternalLink[] — External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context.
      - `name` string, required — Display name for the link
      - `url` string, required — URL to the external resource
    - `template_type` string, nullable — Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier.
    - `field_mappings` object, nullable — Field mappings from collection output fields to template display slots. Maps template slot names (e.g., 'thumbnail', 'title') to actual field names in the search results.
    - `extensions` object, nullable — Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes.
    - `retriever_config` object, nullable — Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time.
  - `collection_identifiers` string[], 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.
  - `stages` StageConfigInput[], nullable — BACKE-1287: edit the retriever's stages IN PLACE (change a filter, operator, rerank params, etc.) without a clone+repoint+delete. OPTIONAL. The full stage list is REPLACED and re-validated exactly as on create (feature URIs resolved against the retriever's collections). Only allowed on UNPUBLISHED retrievers — a published retriever's stages stay immutable for consumer stability; clone or unpublish to change it.
    - `stage_name` string, required — Human-readable stage instance name (REQUIRED).
    - `stage_type` 'filter' | 'sort' | 'reduce' | 'apply' | 'enrich' — Categorisation of stage behaviour within a retrieval flow. These functional categories describe how stages transform the document stream: - FILTER: N → ≤N documents (subset, same schema) - SORT: N → N documents (same docs, different order, same schema) - REDUCE: N → 1 document (aggregation, new schema) - APPLY: N → N or N*M documents (enrichment/expansion, expanded/new schema) - ENRICH: N → N documents (enrichment with computed fields)
    - `config` object, required — Stage implementation parameters (REQUIRED). Must include `stage_id` key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under `parameters`. Optional `pre_filters` and `post_filters` are placed as SIBLINGS of `parameters` (NOT nested inside). Pre-filters require payload indexes on the filtered fields.
    - `batch_size` string, nullable — Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted.
    - `description` string, nullable — User-facing description of the stage (OPTIONAL).
    - `on_error` string, nullable — Behavior when this stage fails. 'skip' continues execution with results from previous stages (graceful degradation). 'error' (default) fails the entire retriever. Useful for optional enrichment or multi-modal stages where one modality may not apply (e.g., face search on logo-only images).
    - `output_alias` string, nullable — Optional alias to persist this stage's results in the execution context. When set, results are stored in CONTEXT.<alias> in addition to replacing current_results. Downstream stages can reference them via {{CONTEXT.<alias>}} in templates. Useful for multi-stage pipelines where later stages should not overwrite earlier results (e.g., face search + logo search producing independent result sets).
  - `input_schema` object, 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.

## Response `200`

Successful Response

- PatchRetrieverResponse — Response after updating a retriever.
  - `retriever` RetrieverConfig, required — Full retriever definition persisted in MongoDB.
    - `retriever_id` string — Stable retriever identifier (REQUIRED).
    - `retriever_name` string, required — Unique retriever name within namespace (REQUIRED).
    - `description` string, nullable — Detailed description of retriever behaviour (OPTIONAL).
    - `collection_ids` string[] — Collections queried by the retriever. Can be empty for query-only inference mode.
    - `stages` StageConfigOutput[], required — Ordered list of stage configurations (REQUIRED).
      - `stage_name` string, required — Human-readable stage instance name (REQUIRED).
      - `stage_type` 'filter' | 'sort' | 'reduce' | 'apply' | 'enrich' — Categorisation of stage behaviour within a retrieval flow. These functional categories describe how stages transform the document stream: - FILTER: N → ≤N documents (subset, same schema) - SORT: N → N documents (same docs, different order, same schema) - REDUCE: N → 1 document (aggregation, new schema) - APPLY: N → N or N*M documents (enrichment/expansion, expanded/new schema) - ENRICH: N → N documents (enrichment with computed fields)
      - `config` object, required — Stage implementation parameters (REQUIRED). Must include `stage_id` key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under `parameters`. Optional `pre_filters` and `post_filters` are placed as SIBLINGS of `parameters` (NOT nested inside). Pre-filters require payload indexes on the filtered fields.
      - `batch_size` string, nullable — Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted.
      - `description` string, nullable — User-facing description of the stage (OPTIONAL).
      - `on_error` string, nullable — Behavior when this stage fails. 'skip' continues execution with results from previous stages (graceful degradation). 'error' (default) fails the entire retriever. Useful for optional enrichment or multi-modal stages where one modality may not apply (e.g., face search on logo-only images).
      - `output_alias` string, nullable — Optional alias to persist this stage's results in the execution context. When set, results are stored in CONTEXT.<alias> in addition to replacing current_results. Downstream stages can reference them via {{CONTEXT.<alias>}} in templates. Useful for multi-stage pipelines where later stages should not overwrite earlier results (e.g., face search + logo search producing independent result sets).
      - `parameters` object, required — Mirror of config.parameters at the stage top level, so anything round-tripping a stage (clone-by-GET, UI re-save, an agent verifying its own write) reads a populated stage instead of an empty one. Always equal to config['parameters'] (FRUSTRATIONS 2026-07-22: a retriever cloned from GET output was created with NO searches because the real stage config only lived under config.parameters). Read-only — on input this key is ignored and recomputed from config, so the two can't drift; config stays the source of truth.
    - `input_schema` object — JSON Schema describing expected user inputs (REQUIRED). Properties must use RetrieverInputSchemaField which supports all bucket types plus document_reference.
    - `budget_limits` BudgetLimits — User-defined limits for time and credits during execution.
      - `max_credits` number, nullable — Maximum credits allowed for a single execution (OPTIONAL).
      - `max_time_ms` integer, nullable — Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL).
    - `feature_dependencies` FeatureAddress[], nullable — Feature addresses required by stages (OPTIONAL, aids validation).
      - `scheme` string
      - `extractor` string, required
      - `version` string, required
      - `output` string, nullable
    - `tags` string[] — Arbitrary tags to help organise retrievers (OPTIONAL).
    - `metadata` object — Custom key-value metadata (OPTIONAL). Round-trips on create/get/list and is updatable via PATCH — useful for automation markers like seed/config versions.
    - `display_config` object, nullable — Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever.
    - `version` integer — Version number that increments on each update (REQUIRED).
    - `created_at` string, date-time — Creation timestamp in UTC (REQUIRED).
    - `updated_at` string, date-time — Last update timestamp in UTC (REQUIRED).
    - `created_by` string, nullable — Identifier of the user who created the retriever (OPTIONAL).
    - `updated_by` string, nullable — Identifier of the user who last updated the retriever (OPTIONAL).
    - `fusion` string, nullable, required — Fusion strategy used by this retriever's feature_search stage (e.g. 'learned', 'rrf', 'dbsf'). Null if no feature_search stage.
    - `collection_identifiers` string[], required — Mirror of collection_ids under the field name CREATE accepts (collection_identifiers), so a create → read round-trip reads back the field it wrote. Always equal to collection_ids (FRUSTRATIONS 2026-07-16: SDKs/agents re-reading their own write saw collection_identifiers null and concluded the retriever was unscoped).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/5d4c905106b4/schema)