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

# Get Public Retriever Template

`GET /v1/public/retrievers/{public_name}/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)

## Path parameters

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

## Response `200`

Successful Response

- PublicRetrieverTemplateResponse — 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
  - `retriever_name` string, required — Original retriever name (you'll change this when creating your own). Provided as reference.
  - `description` string, nullable — Original retriever description (you can use or modify this). Provides context about what this retriever does.
  - `collection_identifiers` string[], required — IMPORTANT: These are the original collections. You MUST replace these with your own collection identifiers when creating a retriever from this template.
  - `stages` object[], required — Pipeline stages configuration. You can use as-is or modify for your needs. This is the core retrieval logic.
  - `input_schema` object, required — 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` object, required — Budget limits for execution. You can adjust these based on your needs.
  - `tags` string[] — Original tags (optional, for reference)
  - `display_config` DisplayConfigOutput — 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.
  - `source_public_name` string, required — Public name of the source retriever (for reference)
  - `source_public_url` string, required — Public URL of the source retriever (to view it in action)
  - `feature_extractors` object[], nullable — 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.

## 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/04b379bdbb7c/schema)