> ## 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.

# Get Public Retriever Template

> Get retriever configuration as a reusable template.

Returns the published retriever's configuration in a format that can be
directly used to create your own retriever. This is perfect for discovering
patterns and adapting them to your own data.

**Authentication:**
- NO authentication required - this endpoint is completely public
- Anyone can get the template if they know the public_name

**Use Case:**
1. Browse public retrievers to find patterns you like
2. GET this endpoint to get the full configuration
3. Copy the config and modify for your needs (especially `collection_identifiers`)
4. POST to `/v1/retrievers` to create your own retriever
5. Optionally publish it with the same display_config

**What's included:**
- Retriever configuration (stages, input_schema, budget_limits)
- Display configuration (for publishing with similar UI)
- Original metadata for reference

**What you need to change:**
- `collection_identifiers`: Replace with your own collection IDs
- `retriever_name`: Give it a unique name
- Optionally modify stages, inputs, display_config as needed

**Example:**
```bash
# 1. Get the template
curl -X GET "https://api.mixpeek.com/v1/public/retrievers/video-search/template"

# 2. Modify the response and create your own retriever
curl -X POST "https://api.mixpeek.com/v1/retrievers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "retriever_name": "my_video_search",
    "collection_identifiers": ["my_videos"],
    "stages": [...],  # From template
    "input_schema": {...},  # From template
    "budget_limits": {...},  # From template
    "display_config": {...}  # From template (optional)
  }'
```

**Response includes:**
- All retriever configuration fields
- Display config for publishing (optional to use)
- Source reference (where this template came from)



## OpenAPI

````yaml get /v1/public/retrievers/{public_name}/template
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/public/retrievers/{public_name}/template:
    get:
      tags:
        - Public Retriever API
      summary: Get Public Retriever Template
      description: >-
        Get retriever configuration as a reusable template.


        Returns the published retriever's configuration in a format that can be

        directly used to create your own retriever. This is perfect for
        discovering

        patterns and adapting them to your own data.


        **Authentication:**

        - NO authentication required - this endpoint is completely public

        - Anyone can get the template if they know the public_name


        **Use Case:**

        1. Browse public retrievers to find patterns you like

        2. GET this endpoint to get the full configuration

        3. Copy the config and modify for your needs (especially
        `collection_identifiers`)

        4. POST to `/v1/retrievers` to create your own retriever

        5. Optionally publish it with the same display_config


        **What's included:**

        - Retriever configuration (stages, input_schema, budget_limits)

        - Display configuration (for publishing with similar UI)

        - Original metadata for reference


        **What you need to change:**

        - `collection_identifiers`: Replace with your own collection IDs

        - `retriever_name`: Give it a unique name

        - Optionally modify stages, inputs, display_config as needed


        **Example:**

        ```bash

        # 1. Get the template

        curl -X GET
        "https://api.mixpeek.com/v1/public/retrievers/video-search/template"


        # 2. Modify the response and create your own retriever

        curl -X POST "https://api.mixpeek.com/v1/retrievers" \
          -H "Authorization: Bearer YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "retriever_name": "my_video_search",
            "collection_identifiers": ["my_videos"],
            "stages": [...],  # From template
            "input_schema": {...},  # From template
            "budget_limits": {...},  # From template
            "display_config": {...}  # From template (optional)
          }'
        ```


        **Response includes:**

        - All retriever configuration fields

        - Display config for publishing (optional to use)

        - Source reference (where this template came from)
      operationId: >-
        get_public_retriever_template_v1_public_retrievers__public_name__template_get
      parameters:
        - name: public_name
          in: path
          required: true
          schema:
            type: string
            description: Public name of the published retriever
            title: Public Name
          description: Public name of the published retriever
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicRetrieverTemplateResponse'
        '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:
    PublicRetrieverTemplateResponse:
      properties:
        retriever_name:
          type: string
          title: Retriever Name
          description: >-
            Original retriever name (you'll change this when creating your own).
            Provided as reference.
          examples:
            - video-search-example
            - product-catalog-demo
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            Original retriever description (you can use or modify this).
            Provides context about what this retriever does.
        collection_identifiers:
          items:
            type: string
          type: array
          title: Collection Identifiers
          description: >-
            IMPORTANT: These are the original collections. You MUST replace
            these with your own collection identifiers when creating a retriever
            from this template.
          examples:
            - - public_videos
            - - demo_products
              - demo_images
        stages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Stages
          description: >-
            Pipeline stages configuration. You can use as-is or modify for your
            needs. This is the core retrieval logic.
        input_schema:
          additionalProperties:
            $ref: '#/components/schemas/RetrieverInputSchemaField-Output'
          type: object
          title: Input Schema
          description: >-
            Input schema defining expected inputs. If you change the input field
            names, make sure to update references in stages (e.g.,
            {{inputs.query}}).
        budget_limits:
          additionalProperties: true
          type: object
          title: Budget Limits
          description: >-
            Budget limits for execution. You can adjust these based on your
            needs.
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: Original tags (optional, for reference)
        display_config:
          anyOf:
            - $ref: '#/components/schemas/DisplayConfig-Output'
            - type: 'null'
          description: >-
            OPTIONAL: Display configuration used for the public interface.
            Include this if you plan to publish your retriever and want to use a
            similar UI design. Otherwise, you can omit it.
        source_public_name:
          type: string
          title: Source Public Name
          description: Public name of the source retriever (for reference)
          examples:
            - video-search
            - product-catalog
        source_public_url:
          type: string
          title: Source Public Url
          description: Public URL of the source retriever (to view it in action)
          examples:
            - https://mxp.co/r/video-search
        feature_extractors:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Feature Extractors
          description: >-
            Feature extractors from all collections used by this retriever. Each
            extractor includes: feature_extractor_name, version, params,
            input_mappings, collection_id, and collection_name for reference.
            Shows how each collection processes data into searchable features.
      type: object
      required:
        - retriever_name
        - collection_identifiers
        - stages
        - input_schema
        - budget_limits
        - source_public_name
        - source_public_url
      title: PublicRetrieverTemplateResponse
      description: >-
        Response containing public retriever configuration as a reusable
        template.


        This returns the retriever's configuration in a format that can be
        directly

        used in a CreateRetrieverRequest. Users can copy this config, modify it
        for

        their needs (e.g., change collection_identifiers), and create their own
        retriever.


        Use Case:
            1. Browse public retrievers to find patterns you like
            2. GET /public/retrievers/{public_name}/template to get the config
            3. Modify collection_identifiers and other fields as needed
            4. POST /retrievers to create your own retriever with this config
            5. Optionally POST /retrievers/{id}/publish to publish it similarly
      examples:
        - budget_limits:
            max_credits: 10
            max_time_ms: 30000
          collection_identifiers:
            - demo_videos
          description: AI-powered video search using semantic understanding
          display_config:
            components:
              result_layout: grid
              show_search: true
            description: Search through video content
            exposed_fields:
              - title
              - thumbnail_url
              - duration
            inputs:
              - field_name: query
                field_schema:
                  type: text
                label: Search Videos
                order: 0
                placeholder: Describe what you're looking for...
                required: true
            title: Video Search
          input_schema:
            query:
              description: Search query
              examples:
                - action scenes
                - romantic moments
              required: true
              type: text
          retriever_name: video-search-demo
          source_public_name: video-search
          source_public_url: https://mxp.co/r/video-search
          stages:
            - config:
                parameters:
                  final_top_k: 25
                  searches:
                    - feature_uri: mixpeek://text_extractor@v1/embedding
                      query:
                        input_mode: text
                        text: '{{inputs.query}}'
                      top_k: 100
                stage_id: feature_search
              stage_name: semantic_search
              stage_type: filter
          tags:
            - video
            - semantic-search
            - demo
    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
    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)
    DisplayConfig-Output:
      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-Output'
          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
    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
    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-Output:
      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-Output'
          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
    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: $

````