> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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



## OpenAPI

````yaml post /v1/retrievers/{retriever_id}/clone
openapi: 3.1.0
info:
  title: Mixpeek API
  description: >-
    This is the Mixpeek API, providing access to various endpoints for data
    processing and retrieval.
  termsOfService: https://mixpeek.com/terms
  contact:
    name: Mixpeek Support
    url: https://mixpeek.com/contact
    email: info@mixpeek.com
  version: '0.82'
servers:
  - url: https://api.mixpeek.com
    description: Production
security: []
paths:
  /v1/retrievers/{retriever_id}/clone:
    post:
      tags:
        - Retrievers
      summary: Clone Retriever
      description: >-
        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
      operationId: clone_retriever_v1_retrievers__retriever_id__clone_post
      parameters:
        - name: retriever_id
          in: path
          required: true
          schema:
            type: string
            description: Source retriever ID or name to clone.
            title: Retriever Id
          description: Source retriever ID or name to clone.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneRetrieverRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloneRetrieverResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CloneRetrieverRequest:
      properties:
        retriever_name:
          type: string
          minLength: 1
          title: Retriever Name
          description: >-
            REQUIRED. Name for the cloned retriever. Must be unique and
            different from the source retriever.
          examples:
            - product_search_v2
            - semantic_search_strict
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            OPTIONAL. Description override. If omitted, copies from source
            retriever.
          examples:
            - Cloned from product_search with stricter filters
        collection_identifiers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Collection Identifiers
          description: >-
            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.
          examples:
            - - products_v2
            - - col_abc123
              - col_def456
        stages:
          anyOf:
            - items:
                $ref: '#/components/schemas/StageConfig'
              type: array
            - type: 'null'
          title: Stages
          description: >-
            OPTIONAL. Override stage configurations. If omitted, copies from
            source retriever. This is where you'd fix typos, add stages, or
            tweak parameters.
        input_schema:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/RetrieverInputSchemaField-Input'
              type: object
            - type: 'null'
          title: Input Schema
          description: >-
            OPTIONAL. Override input schema. If omitted, copies from source
            retriever.
        budget_limits:
          anyOf:
            - $ref: '#/components/schemas/BudgetLimits'
            - type: 'null'
          description: >-
            OPTIONAL. Override budget limits. If omitted, copies from source
            retriever.
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: OPTIONAL. Override tags. If omitted, copies from source retriever.
          examples:
            - - v2
              - production
            - - experimental
              - clone
        display_config:
          anyOf:
            - $ref: '#/components/schemas/DisplayConfig-Input'
            - type: 'null'
          description: >-
            OPTIONAL. Override display configuration. If omitted, copies from
            source retriever.
      type: object
      required:
        - retriever_name
      title: CloneRetrieverRequest
      description: >-
        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)
      examples:
        - example_desc: Clone with just a new name (exact copy)
          retriever_name: product_search_backup
        - description: Stricter version with higher min_score
          example_desc: Clone with stricter filters
          retriever_name: product_search_strict
          tags:
            - strict
            - production
        - collection_identifiers:
            - products_staging
          example_desc: Clone to different collections
          retriever_name: product_search_staging
          tags:
            - staging
    CloneRetrieverResponse:
      properties:
        retriever:
          $ref: '#/components/schemas/RetrieverConfig'
          description: Cloned retriever configuration with new retriever_id.
        source_retriever_id:
          type: string
          title: Source Retriever Id
          description: ID of the source retriever that was cloned.
      type: object
      required:
        - retriever
        - source_retriever_id
      title: CloneRetrieverResponse
      description: Response after cloning a retriever.
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        status:
          type: integer
          title: Status
          description: HTTP status code for this error
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details payload
      type: object
      required:
        - status
        - error
      title: ErrorResponse
      description: Error response model.
      examples:
        - error:
            details:
              id: ns_123
              resource: namespace
            message: Namespace not found
            type: NotFoundError
          status: 404
          success: false
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StageConfig:
      properties:
        stage_name:
          type: string
          minLength: 1
          title: Stage Name
          description: Human-readable stage instance name (REQUIRED).
        stage_type:
          anyOf:
            - $ref: '#/components/schemas/StageType'
            - type: 'null'
          description: >-
            Functional category of the stage. Optional for creation requests;
            auto-inferred from `stage_id` when omitted.
        config:
          additionalProperties: true
          type: object
          title: Config
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Batch Size
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: User-facing description of the stage (OPTIONAL).
        on_error:
          anyOf:
            - type: string
            - type: 'null'
          title: On Error
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Alias
          description: >-
            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).
      type: object
      required:
        - stage_name
        - config
      title: StageConfig
      description: >-
        Configuration for a single stage within a retriever.


        Stages support dynamic configuration through template expressions using
        Jinja2 syntax.


        IMPORTANT - Template Syntax:
            - Use DOUBLE curly braces: {{INPUT.query}} (correct)
            - Single curly braces will NOT work: {INPUT.query} (wrong - not substituted)
            - Namespace names are CASE-INSENSITIVE: {{INPUT.query}}, {{inputs.query}}, {{input.query}}
              all work identically

        Template Namespaces (case-insensitive):
            - INPUT / inputs / input: User-provided query parameters and inputs
            - DOC / doc: Current document fields (for per-document logic)
            - CONTEXT / context: Execution state (budget, timing, retriever metadata)
            - STAGE / stage: Previous stage outputs (for cascading logic)

        Examples:
            Correct: {{INPUT.query_text}}, {{inputs.query}}, {{DOC.content_type}}
            Correct: {{CONTEXT.budget_remaining}}, {{context.budget_remaining}}
            Wrong:   {INPUT.query} - single braces won't be substituted
      examples:
        - config:
            parameters:
              final_top_k: 25
              searches:
                - feature_uri: >-
                    mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1
                  query:
                    input_mode: text
                    value: '{{INPUT.query_text}}'
                  top_k: 100
            stage_id: feature_search
          description: Feature search stage with uppercase template namespace
          stage_name: semantic_search
          stage_type: filter
        - batch_size: '{{20 * inputs.page_size}}'
          config:
            parameters:
              field: metadata.price
              operator: gt
              value: '{{inputs.min_price}}'
            stage_id: attribute_filter
          description: Attribute filter with lowercase template namespace
          stage_name: price_filter
          stage_type: filter
        - config:
            parameters:
              batch_size: '{{CONTEXT.budget_remaining > 50 ? 200 : 50}}'
              criteria: '{{inputs.quality_criteria}}'
              field: '{{DOC.media_type == ''image'' ? ''image_url'' : ''video_url''}}'
            stage_id: llm_filter
          description: Mixed case templates in same stage
          stage_name: llm_filter
          stage_type: filter
        - config:
            parameters:
              final_top_k: 10
              searches:
                - feature_uri: >-
                    mixpeek://web_scraper@v1/jinaai__jina_embeddings_v2_base_code
                  query:
                    input_mode: text
                    value: '{{INPUT.query}}'
                  top_k: 50
            pre_filters:
              AND:
                - field: doc_type
                  operator: eq
                  value: code
            stage_id: feature_search
          description: Feature search with pre_filters (sibling of parameters, NOT inside)
          stage_name: search_code_blocks
          stage_type: filter
    RetrieverInputSchemaField-Input:
      properties:
        type:
          $ref: '#/components/schemas/RetrieverInputSchemaFieldType'
        default:
          anyOf:
            - {}
            - type: 'null'
          title: Default
        items:
          anyOf:
            - $ref: '#/components/schemas/RetrieverInputSchemaField-Input'
            - type: 'null'
        properties:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/RetrieverInputSchemaField-Input'
              type: object
            - type: 'null'
          title: Properties
        examples:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Examples
          description: >-
            OPTIONAL. List of example values for this field. Used by Apps to
            show example inputs in the UI. Provide multiple diverse examples
            when possible.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        enum:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Enum
        required:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Required
          default: false
      additionalProperties: true
      type: object
      required:
        - type
      title: RetrieverInputSchemaField
      description: >-
        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)
    BudgetLimits:
      properties:
        max_credits:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Max Credits
          description: Maximum credits allowed for a single execution (OPTIONAL).
        max_time_ms:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Time Ms
          description: >-
            Maximum wall-clock time in milliseconds before forcing halt
            (OPTIONAL).
      type: object
      title: BudgetLimits
      description: User-defined limits for time and credits during execution.
      examples:
        - max_credits: 100
          max_time_ms: 60000
        - max_time_ms: 120000
    DisplayConfig-Input:
      properties:
        title:
          type: string
          title: Title
          description: Title/heading for the public search page
          examples:
            - Product Search
            - Video Library
            - Creative Assets
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Optional description/subtitle for the page
          examples:
            - Search through thousands of products
            - Find the perfect video clip
        logo_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Logo Url
          description: URL to logo image
          examples:
            - https://example.com/logo.png
        icon_base64:
          anyOf:
            - type: string
              maxLength: 300000
            - type: 'null'
          title: Icon Base64
          description: >-
            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...'
          examples:
            - data:image/png;base64,iVBORw0KGgoAAAANS...
        seo:
          anyOf:
            - $ref: '#/components/schemas/SEOConfig'
            - type: 'null'
          description: >-
            SEO configuration for search engine and social media
            discoverability. Auto-generated during publishing with sensible
            defaults inferred from title, description, and retriever metadata.
            All fields can be overridden.
        markdowns:
          items:
            $ref: '#/components/schemas/MarkdownContent'
          type: array
          title: Markdowns
          description: >-
            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.
        theme:
          $ref: '#/components/schemas/ThemeConfig'
          description: Theme/styling configuration
        inputs:
          items:
            $ref: '#/components/schemas/InputRenderingConfig-Input'
          type: array
          title: Inputs
          description: >-
            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.
        layout:
          $ref: '#/components/schemas/LayoutConfig'
          description: Layout configuration for results
        exposed_fields:
          items:
            type: string
          type: array
          minItems: 1
          title: Exposed Fields
          description: >-
            List of document metadata fields to show in results. Only these
            fields are returned to end users.
        components:
          $ref: '#/components/schemas/ComponentsConfig'
          description: >-
            Configuration for UI components including search inputs, filters,
            and result card display options.
        field_config:
          additionalProperties:
            $ref: '#/components/schemas/FieldConfig'
          type: object
          title: Field Config
          description: >-
            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.
          examples:
            - created_at:
                format: date
                format_options:
                  date_format: relative
                  label: Posted
              price:
                format: number
                format_options:
                  decimals: 2
                  label: Price
                  prefix: $
              thumbnail_url:
                format: image
                format_options:
                  aspect_ratio: 16/9
                  height: 300
                  width: 400
              title:
                format: text
                format_options:
                  label: Title
                  truncate_chars: 60
        custom_cta:
          anyOf:
            - $ref: '#/components/schemas/CustomCTA'
            - type: 'null'
          description: >-
            Optional custom call-to-action button displayed in the header bar.
            Opens a markdown modal when clicked.
        external_links:
          items:
            $ref: '#/components/schemas/ExternalLink'
          type: array
          title: External Links
          description: >-
            External resource links for this retriever (GitHub repos, blog
            posts, docs, etc.). Displayed on homepage and retriever listing
            pages to provide additional context.
          examples:
            - - name: GitHub Repository
                url: https://github.com/org/repo
              - name: Blog Post
                url: https://blog.example.com/post
        template_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Template Type
          description: >-
            Template identifier for frontend rendering. Built-in templates:
            portrait-gallery, media-search, document-search. Custom templates
            can use any string identifier.
          examples:
            - portrait-gallery
            - media-search
            - document-search
        field_mappings:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Field Mappings
          description: >-
            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.
          examples:
            - boundingBox: ocr_bbox
              extractedText: ocr_text
              thumbnail: page_thumbnail_url
              title: document_title
        extensions:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extensions
          description: >-
            Generic extensions for template-specific configuration. Allows
            templates to store custom config without schema changes.
          examples:
            - show_timestamps: true
              video_autoplay: true
            - bbox_highlight_color: '#FF0000'
              show_confidence_badge: true
        retriever_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Retriever Config
          description: >-
            Embedded retriever configuration (stages, feature extractors) for
            the View Config modal. Auto-populated at publish time.
      additionalProperties: true
      type: object
      required:
        - title
        - inputs
        - exposed_fields
      title: DisplayConfig
      description: |-
        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.
      examples:
        - 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

              - Use quotes for exact phrases
              - Try descriptive terms
          description: Search through our product catalog
          exposed_fields:
            - title
            - description
            - price
            - image_url
          external_links:
            - name: GitHub Repository
              url: https://github.com/mixpeek/product-search
            - name: Blog Post
              url: https://blog.mixpeek.com/building-product-search
          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


                Our search uses **machine learning** to understand your queries
                and find the most relevant products.


                ## Features


                - **Semantic Search**: Understands meaning, not just keywords

                - **Visual Search**: Upload images to find similar products

                - **Smart Filters**: Automatically suggests relevant filters
              title: How it Works
            - content: >-
                ## Tips for Better Results


                1. Use descriptive terms (e.g., "wireless noise-canceling
                headphones")

                2. Try different keywords if you don't find what you're looking
                for

                3. Use filters to narrow down results


                *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
    RetrieverConfig:
      properties:
        retriever_id:
          type: string
          title: Retriever Id
          description: Stable retriever identifier (REQUIRED).
        retriever_name:
          type: string
          minLength: 1
          title: Retriever Name
          description: Unique retriever name within namespace (REQUIRED).
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Detailed description of retriever behaviour (OPTIONAL).
        collection_ids:
          items:
            type: string
          type: array
          title: Collection Ids
          description: >-
            Collections queried by the retriever. Can be empty for query-only
            inference mode.
        stages:
          items:
            $ref: '#/components/schemas/StageConfig'
          type: array
          minItems: 1
          title: Stages
          description: Ordered list of stage configurations (REQUIRED).
        input_schema:
          additionalProperties:
            $ref: '#/components/schemas/RetrieverInputSchemaField-Output'
          type: object
          title: Input Schema
          description: >-
            JSON Schema describing expected user inputs (REQUIRED). Properties
            must use RetrieverInputSchemaField which supports all bucket types
            plus document_reference.
        budget_limits:
          $ref: '#/components/schemas/BudgetLimits'
          description: Execution budget limits for the retriever (OPTIONAL).
        feature_dependencies:
          anyOf:
            - items:
                $ref: '#/components/schemas/FeatureAddress'
              type: array
            - type: 'null'
          title: Feature Dependencies
          description: Feature addresses required by stages (OPTIONAL, aids validation).
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Arbitrary tags to help organise retrievers (OPTIONAL).
        display_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Display Config
          description: >-
            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:
          type: integer
          minimum: 1
          title: Version
          description: Version number that increments on each update (REQUIRED).
          default: 1
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp in UTC (REQUIRED).
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp in UTC (REQUIRED).
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
          description: Identifier of the user who created the retriever (OPTIONAL).
        updated_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated By
          description: Identifier of the user who last updated the retriever (OPTIONAL).
        fusion:
          anyOf:
            - type: string
            - type: 'null'
          title: Fusion
          description: >-
            Fusion strategy used by this retriever's feature_search stage (e.g.
            'learned', 'rrf', 'dbsf'). Null if no feature_search stage.
          readOnly: true
      type: object
      required:
        - retriever_name
        - stages
        - fusion
      title: RetrieverConfig
      description: Full retriever definition persisted in MongoDB.
      examples:
        - 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
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error message
        type:
          type: string
          title: Type
          description: Stable error type identifier (machine-readable)
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Fine-grained error code for programmatic handling (e.g.,
            namespace_name_taken, feature_extractor_not_found). Present only
            when consumers may need to branch on a specific error condition.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: >-
            Optional structured details to help debugging (validation errors,
            IDs, etc.)
      type: object
      required:
        - message
        - type
      title: ErrorDetail
      description: Error detail model.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StageType:
      type: string
      enum:
        - filter
        - sort
        - reduce
        - apply
        - enrich
      title: StageType
      description: >-
        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)
    RetrieverInputSchemaFieldType:
      type: string
      enum:
        - string
        - number
        - integer
        - float
        - boolean
        - object
        - array
        - date
        - datetime
        - text
        - image
        - audio
        - video
        - pdf
        - excel
        - document_reference
      title: RetrieverInputSchemaFieldType
      description: >-
        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.
    SEOConfig:
      properties:
        meta_title:
          anyOf:
            - type: string
              maxLength: 60
            - type: 'null'
          title: Meta Title
          description: >-
            SEO-optimized page title (50-60 chars recommended). Auto-generated
            from display_config.title + site_name if not provided.
          examples:
            - Fitness Video Search | Mixpeek
            - Product Catalog | Your Brand
        meta_description:
          anyOf:
            - type: string
              maxLength: 160
            - type: 'null'
          title: Meta Description
          description: >-
            Meta description for search engine snippets (max 160 chars).
            Auto-generated from display_config.description if not provided.
          examples:
            - >-
              Search and discover fitness videos using AI-powered semantic
              search.
            - Browse our product catalog with intelligent visual search.
        keywords:
          items:
            type: string
          type: array
          title: Keywords
          description: >-
            Relevant keywords for search engines. Auto-inferred from title,
            description, and retriever tags.
          examples:
            - - fitness
              - yoga
              - workout
              - exercise videos
            - - products
              - catalog
              - search
              - e-commerce
        og_image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Og Image Url
          description: >-
            URL to OG image for social previews (1200x630px recommended).
            Auto-generated and uploaded to public S3 bucket during publishing.
          examples:
            - >-
              https://mixpeek-public-pages.s3.amazonaws.com/org/ns/og/video-search/og.png
        og_image_alt:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Og Image Alt
          description: Alt text for OG image (accessibility and SEO)
          examples:
            - Fitness video search interface
            - Product catalog preview
        og_type:
          type: string
          title: Og Type
          description: Open Graph content type
          default: website
          examples:
            - website
            - article
            - product
        twitter_card:
          type: string
          title: Twitter Card
          description: Twitter card display style
          default: summary_large_image
          examples:
            - summary
            - summary_large_image
            - app
        twitter_site:
          anyOf:
            - type: string
            - type: 'null'
          title: Twitter Site
          description: Twitter @handle for the site
          default: '@mixpeek'
          examples:
            - '@mixpeek'
            - '@yourbrand'
        twitter_creator:
          anyOf:
            - type: string
            - type: 'null'
          title: Twitter Creator
          description: Twitter @handle for content creator (optional)
          examples:
            - '@johndoe'
            - '@yourbrand'
        robots:
          type: string
          title: Robots
          description: >-
            Robots meta directive for search engine crawlers. Use 'noindex,
            nofollow' to hide from search engines.
          default: index, follow
          examples:
            - index, follow
            - noindex, nofollow
            - index, nofollow
        canonical_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Canonical Url
          description: >-
            Canonical URL if different from default. Auto-set to
            https://mxp.co/r/{public_name} if not provided.
          examples:
            - https://yourdomain.com/search
            - https://mxp.co/r/video-search
        site_name:
          type: string
          title: Site Name
          description: Site name for OG tags and branding
          default: Mixpeek
          examples:
            - Mixpeek
            - Your Brand
            - Company Name
        author:
          anyOf:
            - type: string
            - type: 'null'
          title: Author
          description: Content author/creator name
          examples:
            - Mixpeek
            - Your Organization
        locale:
          type: string
          title: Locale
          description: Content language/locale
          default: en_US
          examples:
            - en_US
            - en_GB
            - es_ES
            - fr_FR
        logo_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Logo Url
          description: >-
            URL to organization/brand logo for SEO and branding. Used in
            structured data and can be displayed in search results.
          examples:
            - https://example.com/logo.png
            - https://cdn.mixpeek.com/logos/acme.png
        favicon_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Favicon Url
          description: >-
            URL to favicon/icon for the public retriever page. Recommended
            sizes: 32x32, 48x48, or 180x180 for Apple touch icon.
          examples:
            - https://example.com/favicon.ico
            - https://cdn.mixpeek.com/icons/acme.png
        structured_data:
          $ref: '#/components/schemas/StructuredDataConfig'
          description: Schema.org structured data for rich search results
      type: object
      title: SEOConfig
      description: |-
        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
      examples:
        - author: Mixpeek
          favicon_url: https://example.com/favicon.ico
          keywords:
            - fitness
            - yoga
            - workout
            - exercise videos
          locale: en_US
          logo_url: https://example.com/logo.png
          meta_description: Search and discover fitness videos using AI-powered semantic search.
          meta_title: Fitness Video Search | Mixpeek
          og_image_alt: Fitness video search interface
          og_image_url: https://mixpeek-public-pages.s3.amazonaws.com/og.png
          og_type: website
          robots: index, follow
          site_name: Mixpeek
          structured_data:
            additional_properties:
              applicationCategory: Search
            type: WebApplication
          twitter_card: summary_large_image
          twitter_site: '@mixpeek'
    MarkdownContent:
      properties:
        title:
          type: string
          maxLength: 200
          minLength: 1
          title: Title
          description: Title for the markdown content section
          examples:
            - How it Works
            - Getting Started
            - About This Search
            - Search Tips
        content:
          type: string
          maxLength: 50000
          minLength: 1
          title: Content
          description: >-
            Markdown-formatted content. Supports standard markdown syntax
            including headers, lists, links, images, code blocks, and emphasis.
            Limited to 50KB to prevent database issues.
          examples:
            - |-
              # Welcome

              This search uses **AI** to understand your queries.
            - |-
              ## Features

              - Semantic search
              - Multi-modal
              - Fast results
            - |-
              ### Tips

              1. Use specific terms
              2. Try multiple queries

              [Learn more](https://docs.example.com)
      type: object
      required:
        - title
        - content
      title: MarkdownContent
      description: |-
        Reusable markdown content model with title and content.

        This model provides a structured way to include rich markdown content
        anywhere in the published retriever configuration. Includes safety
        constraints to prevent database issues.
    ThemeConfig:
      properties:
        primary_color:
          type: string
          title: Primary Color
          description: Primary brand color (hex code)
          default: '#007AFF'
          examples:
            - '#007AFF'
            - '#FF6B6B'
            - '#4ECDC4'
        secondary_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Secondary Color
          description: Secondary/accent color (hex code)
          examples:
            - '#FF6B6B'
            - '#95E1D3'
        font_family:
          type: string
          title: Font Family
          description: Font family for text
          default: system-ui, -apple-system, sans-serif
          examples:
            - Inter, sans-serif
            - Roboto, sans-serif
        background_color:
          type: string
          title: Background Color
          description: Background color (hex code)
          default: '#FFFFFF'
        text_color:
          type: string
          title: Text Color
          description: Primary text color (hex code)
          default: '#374151'
        heading_font_family:
          anyOf:
            - type: string
            - type: 'null'
          title: Heading Font Family
          description: Optional separate font family for headings
          examples:
            - Georgia, serif
            - Playfair Display, serif
        surface_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Surface Color
          description: Surface/card background color (hex code)
          examples:
            - '#F9FAFB'
            - '#F3F4F6'
        muted_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Muted Color
          description: Muted/secondary text color (hex code)
          examples:
            - '#6B7280'
            - '#9CA3AF'
        border_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Border Color
          description: Border color for cards and elements (hex code)
          examples:
            - '#E5E7EB'
            - '#D1D5DB'
        border_radius:
          anyOf:
            - type: string
            - type: 'null'
          title: Border Radius
          description: Default border radius for cards and elements
          default: 12px
          examples:
            - 8px
            - 12px
            - 16px
            - 24px
        card_style:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Style
          description: >-
            Card visual style: elevated (shadow), flat (no shadow), bordered, or
            glass (frosted glass effect)
          default: elevated
          examples:
            - elevated
            - flat
            - bordered
            - glass
        card_hover_effect:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Hover Effect
          description: 'Card hover animation effect: lift (move up), glow, scale, or none'
          default: lift
          examples:
            - lift
            - glow
            - scale
            - none
      type: object
      title: ThemeConfig
      description: >-
        Theme configuration for public retriever UI.


        Defines colors, fonts, and visual styling for the public search
        interface.
    InputRenderingConfig-Input:
      properties:
        field_name:
          type: string
          title: Field Name
          description: Name of the input field (matches retriever input_schema key)
          examples:
            - query
            - image_url
            - video_url
            - category
        field_schema:
          $ref: '#/components/schemas/RetrieverInputSchemaField-Input'
          description: >-
            Schema definition for this input field. Defines type, description,
            examples, and validation rules. Supports all bucket types (string,
            number, image, etc.) plus document_reference. Frontend uses this to
            render the appropriate input component (text input, image upload,
            dropdown, etc.)
        input_type:
          type: string
          title: Input Type
          description: >-
            UI input component type. Determines how the input is rendered: text
            (single line), select (dropdown), file (upload), multiselect
            (multiple choice)
          default: text
          examples:
            - text
            - select
            - file
            - multiselect
        label:
          type: string
          title: Label
          description: Human-readable label for the input
          examples:
            - Search Query
            - Upload Image
            - Select Category
        placeholder:
          anyOf:
            - type: string
            - type: 'null'
          title: Placeholder
          description: Placeholder text for the input
          examples:
            - Enter search terms...
            - Drag and drop or click to upload
        helper_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Helper Text
          description: Helper text displayed below the input to guide users
          examples:
            - Describe the aesthetic, outfit, or vibe you're looking for
            - Enter keywords separated by commas
            - Use natural language to describe what you're searching for
        suggestions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Suggestions
          description: >-
            Pre-filled suggestion chips that users can click to populate the
            input
          examples:
            - - streetwear urban
              - clean girl minimal
              - summer haul bright
            - - wireless headphones
              - laptop under $1000
              - gaming mouse
            - - minimalist
              - oversized hoodie
              - aesthetic vibe
        required:
          type: boolean
          title: Required
          description: Whether this input is required
          default: true
        order:
          type: integer
          minimum: 0
          title: Order
          description: Display order (lower numbers appear first)
          default: 0
      type: object
      required:
        - field_name
        - field_schema
        - label
      title: InputRenderingConfig
      description: |-
        Configuration for how to render an input field in the public UI.

        Maps to BucketSchemaField structure for consistency with how we define
        input types across the system.
      examples:
        - field_name: query
          field_schema:
            description: Text search query
            examples:
              - red sports car
              - sunset over ocean
            type: string
          helper_text: Describe the aesthetic, outfit, or vibe you're looking for
          label: Search by style
          order: 0
          placeholder: 'Try: oversized hoodie streetwear urban'
          required: true
          suggestions:
            - streetwear urban
            - clean girl minimal
            - summer haul bright
            - minimalist aesthetic
        - field_name: image_url
          field_schema:
            description: Image for visual search
            examples:
              - https://example.com/image.jpg
            type: image
          helper_text: Upload an image to find visually similar items
          label: Upload Image
          order: 1
          placeholder: Drop image or paste URL
          required: false
    LayoutConfig:
      properties:
        mode:
          type: string
          title: Mode
          description: Display mode for results
          default: grid
          examples:
            - grid
            - list
            - masonry
        columns:
          type: integer
          maximum: 6
          minimum: 1
          title: Columns
          description: Number of columns for grid/masonry layouts
          default: 3
        gap:
          type: string
          title: Gap
          description: Gap between items
          default: 16px
          examples:
            - 8px
            - 16px
            - 24px
        full_width:
          type: boolean
          title: Full Width
          description: Whether to use full viewport width for the layout (edge-to-edge)
          default: false
      type: object
      title: LayoutConfig
      description: Layout configuration for search results display.
    ComponentsConfig:
      properties:
        show_hero:
          type: boolean
          title: Show Hero
          description: Whether to show the hero section with title and description
          default: true
        show_search:
          type: boolean
          title: Show Search
          description: Whether to show search input fields
          default: true
        show_filters:
          type: boolean
          title: Show Filters
          description: Whether to show filters sidebar
          default: false
        show_results_header:
          type: boolean
          title: Show Results Header
          description: Whether to show the results header with count and sorting options
          default: true
        result_layout:
          type: string
          title: Result Layout
          description: Layout mode for results display
          default: grid
          examples:
            - grid
            - list
            - masonry
        result_card:
          anyOf:
            - $ref: '#/components/schemas/ResultCardProperties'
            - type: 'null'
          description: Configuration for result card display
      type: object
      title: ComponentsConfig
      description: Configuration for UI components.
      examples:
        - result_card:
            card_click_action: viewDetails
            field_order:
              - title
              - description
            layout: vertical
            show_find_similar: true
            show_thumbnail: true
          result_layout: grid
          show_filters: false
          show_hero: true
          show_results_header: true
          show_search: true
    FieldConfig:
      properties:
        format:
          $ref: '#/components/schemas/FieldFormatType'
          description: Format type for this field (text, image, date, number, etc.)
        format_options:
          $ref: '#/components/schemas/FieldFormatOptions'
          description: Format-specific display options
      type: object
      required:
        - format
      title: FieldConfig
      description: Configuration for how to display a specific field in results.
      examples:
        - format: text
          format_options:
            label: Title
            truncate_chars: 60
        - format: image
          format_options:
            aspect_ratio: 16/9
            height: 300
            lazy_load: true
            width: 400
        - format: date
          format_options:
            date_format: relative
            label: Posted
        - format: number
          format_options:
            decimals: 2
            label: Price
            prefix: $
    CustomCTA:
      properties:
        label:
          type: string
          maxLength: 50
          minLength: 1
          title: Label
          description: Button label text displayed in the header
          examples:
            - How to Use
            - Search Tips
            - About
            - Help
        markdown_content:
          type: string
          maxLength: 50000
          minLength: 1
          title: Markdown Content
          description: >-
            Markdown content displayed in the modal when button is clicked.
            Supports standard markdown syntax.
          examples:
            - |-
              # Getting Started

              This search engine allows you to...

              ## Tips

              - Use specific keywords
              - Try different queries
      type: object
      required:
        - label
        - markdown_content
      title: CustomCTA
      description: |-
        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.
      examples:
        - label: Search Tips
          markdown_content: |-
            # Search Tips

            - Use quotes for exact phrases
            - Filter by date using 'after:2024'
    ExternalLink:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Display name for the link
          examples:
            - GitHub Repository
            - Blog Post
            - Documentation
            - Demo Video
        url:
          type: string
          maxLength: 2048
          minLength: 1
          title: Url
          description: URL to the external resource
          examples:
            - https://github.com/org/repo
            - https://blog.example.com/post
            - https://docs.example.com
      type: object
      required:
        - name
        - url
      title: ExternalLink
      description: |-
        External resource link for a published retriever.

        Used to link to related resources like GitHub repos, blog posts,
        documentation, or other relevant URLs displayed on the homepage.
      examples:
        - name: GitHub Repository
          url: https://github.com/mixpeek/video-search
        - name: Blog Post
          url: https://blog.mixpeek.com/building-semantic-search
    RetrieverInputSchemaField-Output:
      properties:
        type:
          $ref: '#/components/schemas/RetrieverInputSchemaFieldType'
        default:
          anyOf:
            - {}
            - type: 'null'
          title: Default
        items:
          anyOf:
            - $ref: '#/components/schemas/RetrieverInputSchemaField-Output'
            - type: 'null'
        properties:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/RetrieverInputSchemaField-Output'
              type: object
            - type: 'null'
          title: Properties
        examples:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Examples
          description: >-
            OPTIONAL. List of example values for this field. Used by Apps to
            show example inputs in the UI. Provide multiple diverse examples
            when possible.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        enum:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Enum
        required:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Required
          default: false
      additionalProperties: true
      type: object
      required:
        - type
      title: RetrieverInputSchemaField
      description: >-
        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)
    FeatureAddress:
      properties:
        scheme:
          type: string
          title: Scheme
          default: mixpeek
        extractor:
          type: string
          title: Extractor
        version:
          type: string
          title: Version
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
      type: object
      required:
        - extractor
        - version
      title: FeatureAddress
      description: >-
        Canonical feature address: mixpeek://{extractor}@{version}/{output}.


        The output segment is the inference_name (embedding model identifier),
        which enables

        cross-extractor compatibility checking. Two feature URIs with the same
        inference_name

        in the output segment produce compatible embeddings that can be
        compared/fused.


        Format examples:
            - mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1
            - mixpeek://multimodal_extractor@v1/multilingual_e5_large_instruct_v1  (compatible with above!)
            - mixpeek://image_extractor@v1/google_siglip_base_v1  (different model = incompatible)

        Short form without the output segment is allowed only if the extractor
        has

        a single vector output.
    StructuredDataConfig:
      properties:
        type:
          type: string
          title: Type
          description: Schema.org type for structured data
          default: WebApplication
          examples:
            - WebApplication
            - SearchAction
            - WebPage
            - SoftwareApplication
        additional_properties:
          additionalProperties: true
          type: object
          title: Additional Properties
          description: Additional Schema.org properties
          examples:
            - applicationCategory: Search
              operatingSystem: Web
            - potentialAction:
                '@type': SearchAction
                target: '{search_term}'
      type: object
      title: StructuredDataConfig
      description: >-
        Schema.org structured data configuration for search engines.


        Enables rich search results and better understanding of the page
        content.
    ResultCardProperties:
      properties:
        layout:
          type: string
          title: Layout
          description: Card layout orientation
          default: vertical
          examples:
            - vertical
            - horizontal
        show_thumbnail:
          type: boolean
          title: Show Thumbnail
          description: Whether to show thumbnail image in results
          default: true
        thumbnail_aspect_ratio:
          type: string
          title: Thumbnail Aspect Ratio
          description: Aspect ratio for thumbnail images
          default: 16/9
          examples:
            - 16/9
            - 4/3
            - 1/1
        thumbnail_fit:
          type: string
          title: Thumbnail Fit
          description: How thumbnail should fit in container
          default: cover
          examples:
            - cover
            - contain
        show_score:
          type: boolean
          title: Show Score
          description: Whether to display relevance score
          default: false
        truncate_title:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Truncate Title
          description: Maximum characters for title before truncation
          examples:
            - 60
            - 80
            - 100
        truncate_description:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Truncate Description
          description: Maximum characters for description before truncation
          examples:
            - 120
            - 150
            - 200
        field_order:
          items:
            type: string
          type: array
          title: Field Order
          description: >-
            Order of fields to display in result card. Fields not in this list
            won't be shown. Must be subset of exposed_fields.
          examples:
            - - title
              - description
              - category
              - created_at
            - - thumbnail_url
              - title
              - price
              - views
        show_find_similar:
          type: boolean
          title: Show Find Similar
          description: Whether to show a 'Find Similar' button on result cards
          default: false
        card_click_action:
          type: string
          title: Card Click Action
          description: >-
            Action when card is clicked: none (no action), findSimilar (trigger
            similar search), viewDetails (open detail modal)
          default: viewDetails
          examples:
            - none
            - findSimilar
            - viewDetails
        thumbnail_field:
          anyOf:
            - type: string
            - type: 'null'
          title: Thumbnail Field
          description: Field name to use as thumbnail image source
          examples:
            - thumbnail_url
            - image_url
            - page_image
        title_field:
          anyOf:
            - type: string
            - type: 'null'
          title: Title Field
          description: Field name to use as card title
          examples:
            - title
            - name
            - document_title
        card_fields:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Card Fields
          description: >-
            Fields to display on the card (alternative to field_order for
            template compatibility)
          examples:
            - - title
              - description
              - price
        modal_fields:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Modal Fields
          description: Fields to display in the detail modal when card is clicked
          examples:
            - - title
              - description
              - full_text
              - metadata
        card_style:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Style
          description: >-
            Card style preset: default, portrait-discovery, media-search,
            document-search, or custom template-specific styles
          default: default
          examples:
            - default
            - portrait-discovery
            - media-search
            - document-search
      type: object
      title: ResultCardProperties
      description: Properties for result card display configuration.
      examples:
        - card_click_action: viewDetails
          card_style: default
          field_order:
            - title
            - description
            - category
            - created_at
          layout: vertical
          show_find_similar: true
          show_score: true
          show_thumbnail: true
          thumbnail_aspect_ratio: 16/9
          thumbnail_field: image_url
          thumbnail_fit: cover
          title_field: title
          truncate_description: 120
          truncate_title: 60
    FieldFormatType:
      type: string
      enum:
        - text
        - image
        - date
        - number
        - url
        - boolean
        - array
        - object
      title: FieldFormatType
      description: Supported field format types for result display.
    FieldFormatOptions:
      properties:
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
          description: Display label for this field
          examples:
            - Title
            - Price
            - Posted Date
        show_empty:
          type: boolean
          title: Show Empty
          description: Whether to show the field if value is empty/null
          default: true
        truncate_chars:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Truncate Chars
          description: Maximum characters before truncation (for text fields)
          examples:
            - 60
            - 120
            - 200
        width:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Width
          description: Image width in pixels
          examples:
            - 400
            - 800
        height:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Height
          description: Image height in pixels
          examples:
            - 300
            - 600
        lazy_load:
          type: boolean
          title: Lazy Load
          description: 'Enable lazy loading for images (default: true)'
          default: true
        aspect_ratio:
          anyOf:
            - type: string
            - type: 'null'
          title: Aspect Ratio
          description: Aspect ratio for image container
          examples:
            - 16/9
            - 4/3
            - 1/1
        object_fit:
          type: string
          title: Object Fit
          description: CSS object-fit property for images
          default: cover
          examples:
            - cover
            - contain
            - fill
        date_format:
          type: string
          title: Date Format
          description: 'Date format type: ''iso'', ''relative'', or custom format string'
          default: relative
          examples:
            - relative
            - iso
            - MMM DD, YYYY
        decimals:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Decimals
          description: Number of decimal places
          examples:
            - 0
            - 1
            - 2
        prefix:
          anyOf:
            - type: string
            - type: 'null'
          title: Prefix
          description: Prefix for number display
          examples:
            - $
            - €
            - '#'
        suffix:
          anyOf:
            - type: string
            - type: 'null'
          title: Suffix
          description: Suffix for number display
          examples:
            - '%'
            - k
            - M
        open_in_new_tab:
          type: boolean
          title: Open In New Tab
          description: 'Open URLs in new tab (default: true)'
          default: true
        show_domain:
          type: boolean
          title: Show Domain
          description: Show domain instead of full URL
          default: false
        true_label:
          type: string
          title: True Label
          description: Label for true values
          default: 'Yes'
        false_label:
          type: string
          title: False Label
          description: Label for false values
          default: 'No'
        separator:
          type: string
          title: Separator
          description: 'Separator for array items (default: '', '')'
          default: ', '
        max_items:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Items
          description: Maximum array items to display
      type: object
      title: FieldFormatOptions
      description: |-
        Format-specific options for field display.

        Different format types support different options:
        - text: label, truncate_chars, show_empty
        - image: width, height, lazy_load, aspect_ratio, object_fit
        - date: label, date_format (iso, relative, custom)
        - number: label, decimals, prefix, suffix, show_empty
        - url: label, open_in_new_tab, show_domain
        - boolean: label, true_label, false_label
        - array: label, separator, max_items
      examples:
        - label: Title
          show_empty: false
          truncate_chars: 60
        - aspect_ratio: 16/9
          height: 300
          label: Thumbnail
          lazy_load: true
          object_fit: cover
          width: 400
        - date_format: relative
          label: Posted
        - decimals: 2
          label: Price
          prefix: $

````