Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Published Retrievers

Publish Retriever

Publish a retriever as a public search interface.

Creates a public API endpoint and branded page for the retriever. Returns a public API key that should be stored securely (shown only once).

Limits:

  • Maximum 10 published retrievers per organization
  • Public name must be globally unique

Security:

  • Public API key is required for all requests
  • Optional password protection via organization secrets
  • Configurable rate limits per retriever
  • Field masking ensures only approved fields are exposed
post/v1/retrievers/{retriever_id}/publish

Path parameters

retriever_idstring required

ID of the retriever to publish

ID of the retriever to publish

Request body

display_namestring nullable

Human-readable display name for this retriever (free-form text). Example: 'Peptide Evidence Search'. A URL-safe slug is auto-generated from this if public_name is not provided.

public_namestring nullable

URL-safe slug (lowercase letters, digits, hyphens only). Must start and end with an alphanumeric character. Example: 'peptide-evidence-search'. Used in the public URL: mxp.co/r/{public_name}. Auto-generated from display_name if not provided.

descriptionstring nullable

Description of this public retriever. Explains what the retriever does and what it searches. Displayed in public listings and search results.

icon_base64string nullable

Base64 encoded icon/favicon for this public retriever. Data URI format recommended. Max size: ~200KB encoded. Displayed in public listings and as the retriever's icon.

password_secret_namestring nullable

OPTIONAL. Name of organization secret containing password for access protection. If provided, users must send password via X-Retriever-Password header.

include_metadataboolean

Whether to capture and store retriever metadata (stages, collections, capabilities). Recommended: True for better developer experience and debugging. Default: True.

tagsstring[]

Tags for categorizing this retriever. Used for filtering in public listings and gallery views.

categorystring nullable

Primary category for this retriever. Examples: 'sandbox', 'marketplace', 'demo', 'production'.

Example request

{
  "display_name": "Peptide Evidence Search",
  "public_name": "video-search",
  "description": "AI-powered video search using semantic understanding",
  "icon_base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "display_config": {
    "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\n\n- Use quotes for exact phrases\n- 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\n\nOur search uses **machine learning** to understand your queries and find the most relevant products.\n\n## Features\n\n- **Semantic Search**: Understands meaning, not just keywords\n- **Visual Search**: Upload images to find similar products\n- **Smart Filters**: Automatically suggests relevant filters",
        "title": "How it Works"
      },
      {
        "content": "## Tips for Better Results\n\n1. Use descriptive terms (e.g., \"wireless noise-canceling headphones\")\n2. Try different keywords if you don't find what you're looking for\n3. Use filters to narrow down results\n\n*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"
  },
  "rate_limit_config": {
    "description": "Standard tier (default) - 10/min, 100/hour, 1k/day",
    "enabled": true,
    "max_results_per_query": 50,
    "tier": "standard"
  },
  "password_secret_name": "published_retriever_password",
  "tags": [
    "sandbox",
    "demo",
    "video"
  ],
  "category": "sandbox"
}

Response

Successful Response

public_idstring required

Public identifier for this published retriever

retriever_idstring required

ID of the underlying retriever

public_urlstring required

Full public URL to the retriever page

short_urlstring required

Short URL via mxp.co redirect (same as public_url)

public_api_keystring nullable

DEPRECATED: API keys are no longer required for public retriever access. For programmatic SDK access, create a ret_sk_ key via the retrievers/{id}/keys endpoint.

Example response

{
  "public_url": "https://mxp.co/r/video-search",
  "short_url": "https://mxp.co/r/video-search"
}