---
title: "Get Public Retriever Config"
method: GET
path: "/v1/public/retrievers/{public_name}/config"
tags: ["Public Retriever API"]
---

# Get Public Retriever Config

`GET /v1/public/retrievers/{public_name}/config`

Get display configuration for public page rendering.

⚠️ **DEPRECATED**: Use `/v1/marketplace/catalog/{public_name}/config` instead.
This endpoint is maintained for backwards compatibility but may be removed in the future.

Returns the UI configuration needed to render the public search interface.
Used by the frontend app at mxp.co to dynamically build the UI.

**Authentication:**
- NO authentication required - this endpoint is public
- Anyone can access the config if they know the public_name
- The config includes the public_api_key needed for execute/interact endpoints

**Response includes:**
- Display config (logo, theme, components, field rendering)
- Title and description
- Password protection status
- Public API key for subsequent authenticated requests

**Example (deprecated):**
```bash
curl -X GET "https://api.mixpeek.com/v1/public/retrievers/video-search/config"
```

**Example (recommended):**
```bash
curl -X GET "https://api.mixpeek.com/v1/marketplace/catalog/video-search/config"
```

## Path parameters

- `public_name` string, required — Public name of the published retriever

## Response `200`

Successful Response

- PublicRetrieverConfigResponse — Response for fetching public retriever configuration (for UI rendering). This is what the public frontend (mxp.co/r/{name}) fetches to render the search interface. It includes everything needed for UI rendering. Note: API keys are no longer required. The execute endpoint can be called without authentication - rate limiting and optional password protection provide security.
  - `public_name` string, required — Public name of the retriever
  - `public_api_key` string, nullable — DEPRECATED: API keys are no longer required for public access. The execute endpoint can be called without authentication.
  - `display_config` DisplayConfigOutput, required — Display configuration for public retriever UI. This model defines how the public search interface should be rendered, including input fields, theme, layout, and result card configuration. The frontend (mxp.co) uses this to dynamically build the UI without hardcoded components.
    - `title` string, required — Title/heading for the public search page
    - `description` string, nullable — Optional description/subtitle for the page
    - `logo_url` string, nullable — URL to logo image
    - `icon_base64` string, nullable — Base64 encoded icon/favicon (data URI format recommended). Max size: ~200KB encoded. Use for small icons that should be embedded. Example: 'data:image/png;base64,iVBORw0KGgo...'
    - `seo` SEOConfig — SEO configuration for public retriever discoverability. Auto-generated during publishing with sensible defaults inferred from the retriever's display_config. All fields can be overridden manually. This configuration controls how the public retriever appears in: - Search engine results (Google, Bing, etc.) - Social media shares (Twitter, Facebook, LinkedIn) - Link previews in messaging apps
      - `meta_title` string, nullable — SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided.
      - `meta_description` string, nullable — Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided.
      - `keywords` string[] — Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags.
      - `og_image_url` string, nullable — URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing.
      - `og_image_alt` string, nullable — Alt text for OG image (accessibility and SEO)
      - `og_type` string — Open Graph content type
      - `twitter_card` string — Twitter card display style
      - `twitter_site` string, nullable — Twitter @handle for the site
      - `twitter_creator` string, nullable — Twitter @handle for content creator (optional)
      - `robots` string — Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines.
      - `canonical_url` string, nullable — Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided.
      - `site_name` string — Site name for OG tags and branding
      - `author` string, nullable — Content author/creator name
      - `locale` string — Content language/locale
      - `logo_url` string, nullable — URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results.
      - `favicon_url` string, nullable — URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon.
      - `structured_data` StructuredDataConfig — Schema.org structured data configuration for search engines. Enables rich search results and better understanding of the page content.
        - `type` string — Schema.org type for structured data
        - `additional_properties` object — Additional Schema.org properties
    - `markdowns` MarkdownContent[] — Array of markdown content sections for documentation, guides, or informational modals. Each section has a title and markdown-formatted content. Displayed in modals, expandable sections, or tabs on the public interface. Examples: 'How it Works', 'Search Guide', 'About', 'FAQ', etc.
      - `title` string, required — Title for the markdown content section
      - `content` string, required — Markdown-formatted content. Supports standard markdown syntax including headers, lists, links, images, code blocks, and emphasis. Limited to 50KB to prevent database issues.
    - `theme` ThemeConfig — Theme configuration for public retriever UI. Defines colors, fonts, and visual styling for the public search interface.
      - `primary_color` string — Primary brand color (hex code)
      - `secondary_color` string, nullable — Secondary/accent color (hex code)
      - `font_family` string — Font family for text
      - `background_color` string — Background color (hex code)
      - `text_color` string — Primary text color (hex code)
      - `heading_font_family` string, nullable — Optional separate font family for headings
      - `surface_color` string, nullable — Surface/card background color (hex code)
      - `muted_color` string, nullable — Muted/secondary text color (hex code)
      - `border_color` string, nullable — Border color for cards and elements (hex code)
      - `border_radius` string, nullable — Default border radius for cards and elements
      - `card_style` string, nullable — Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect)
      - `card_hover_effect` string, nullable — Card hover animation effect: lift (move up), glow, scale, or none
    - `inputs` InputRenderingConfigOutput[], required — List of input fields to render in the search interface. Each input maps to a field in the retriever's input_schema. Frontend uses the field_schema to render the appropriate component type.
      - `field_name` string, required — Name of the input field (matches retriever input_schema key)
      - `field_schema` RetrieverInputSchemaFieldOutput, required — Schema field definition for retriever input parameters. Identical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType which includes additional reference types like document_reference. This allows retrievers to accept: 1. Metadata inputs (strings, numbers, dates, etc.) 2. File inputs (images, videos, documents for search) 3. Reference inputs (document_reference for "find similar" queries)
        - `type` 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'object' | 'array' | 'date' | 'datetime' | 'text' | 'image' | 'audio' | 'video' | 'pdf' | 'excel' | 'document_reference', required — Supported data types for retriever input schema fields. Retriever input schemas define what parameters users can provide when executing a retriever. This includes all bucket schema types plus additional reference types. Types fall into three categories: 1. **Metadata Types** (JSON types): - Standard JSON-compatible types - Examples: string, number, boolean, date - Inherited from BucketSchemaFieldType 2. **File Types** (blobs): - Users can upload files/content as search inputs - Examples: text, image, video, pdf - Inherited from BucketSchemaFieldType 3. **Reference Types** (structured metadata): - Special types for referencing existing documents - Examples: document_reference - Only available in retriever input schemas (NOT in bucket schemas) **DOCUMENT_REFERENCE Usage**: Accept document reference for "find similar" queries. Example - Find similar products retriever: { "reference_product": { "type": "document_reference", "description": "Find products similar to this one", "required": true } } Execution input: { "inputs": { "reference_product": { "collection_id": "col_products", "document_id": "doc_item_123" } } } The system will use the pre-computed features from doc_item_123 to find similar documents without re-processing.
        - `default` unknown
        - `items` RetrieverInputSchemaFieldOutput — recursive
        - `properties` object, nullable
        - `examples` unknown[], nullable — OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.
          - unknown
        - `description` string, nullable
        - `enum` unknown[], nullable
          - unknown
        - `required` boolean, nullable
      - `input_type` string — UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice)
      - `label` string, required — Human-readable label for the input
      - `placeholder` string, nullable — Placeholder text for the input
      - `helper_text` string, nullable — Helper text displayed below the input to guide users
      - `suggestions` string[], nullable — Pre-filled suggestion chips that users can click to populate the input
      - `required` boolean — Whether this input is required
      - `order` integer — Display order (lower numbers appear first)
    - `layout` LayoutConfig — Layout configuration for search results display.
      - `mode` string — Display mode for results
      - `columns` integer — Number of columns for grid/masonry layouts
      - `gap` string — Gap between items
      - `full_width` boolean — Whether to use full viewport width for the layout (edge-to-edge)
    - `exposed_fields` string[], required — List of document metadata fields to show in results. Only these fields are returned to end users.
    - `components` ComponentsConfig — Configuration for UI components.
      - `show_hero` boolean — Whether to show the hero section with title and description
      - `show_search` boolean — Whether to show search input fields
      - `show_filters` boolean — Whether to show filters sidebar
      - `show_results_header` boolean — Whether to show the results header with count and sorting options
      - `result_layout` string — Layout mode for results display
      - `result_card` ResultCardProperties — Properties for result card display configuration.
        - `layout` string — Card layout orientation
        - `show_thumbnail` boolean — Whether to show thumbnail image in results
        - `thumbnail_aspect_ratio` string — Aspect ratio for thumbnail images
        - `thumbnail_fit` string — How thumbnail should fit in container
        - `show_score` boolean — Whether to display relevance score
        - `truncate_title` integer, nullable — Maximum characters for title before truncation
        - `truncate_description` integer, nullable — Maximum characters for description before truncation
        - `field_order` string[] — Order of fields to display in result card. Fields not in this list won't be shown. Must be subset of exposed_fields.
        - `show_find_similar` boolean — Whether to show a 'Find Similar' button on result cards
        - `card_click_action` string — Action when card is clicked: none (no action), findSimilar (trigger similar search), viewDetails (open detail modal)
        - `thumbnail_field` string, nullable — Field name to use as thumbnail image source
        - `title_field` string, nullable — Field name to use as card title
        - `card_fields` string[], nullable — Fields to display on the card (alternative to field_order for template compatibility)
        - `modal_fields` string[], nullable — Fields to display in the detail modal when card is clicked
        - `card_style` string, nullable — Card style preset: default, portrait-discovery, media-search, document-search, or custom template-specific styles
    - `field_config` object — Configuration for how each field should be displayed. Keys are field names (must be subset of exposed_fields). Values are FieldConfig objects specifying format and display options.
    - `custom_cta` CustomCTA — Optional custom button in header that opens a markdown modal. Allows users to add a custom call-to-action button in the header bar that opens a modal with markdown content when clicked.
      - `label` string, required — Button label text displayed in the header
      - `markdown_content` string, required — Markdown content displayed in the modal when button is clicked. Supports standard markdown syntax.
    - `external_links` ExternalLink[] — External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context.
      - `name` string, required — Display name for the link
      - `url` string, required — URL to the external resource
    - `template_type` string, nullable — Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier.
    - `field_mappings` object, nullable — Field mappings from collection output fields to template display slots. Maps template slot names (e.g., 'thumbnail', 'title') to actual field names in the search results.
    - `extensions` object, nullable — Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes.
    - `retriever_config` object, nullable — Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time.
  - `password_protected` boolean, required — Whether this retriever requires password authentication
  - `retriever_metadata` RetrieverMetadata — Metadata explaining how the retriever works. This is separate from DisplayConfig and provides technical information about the retriever's architecture for developers/debugging.
    - `stages` object[] — Pipeline stages used in this retriever
    - `collections` object[] — Collections and feature extractors used
    - `capabilities` object — Capabilities and features of this retriever

## Other responses

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

---

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