Skip to main content
POST
/
v1
/
retrievers
/
{retriever_id}
/
publish
Publish Retriever
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/publish \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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": {
    "enabled": true,
    "tier": "standard",
    "requests_per_minute": 2,
    "requests_per_hour": 2,
    "requests_per_day": 2,
    "max_results_per_query": 100,
    "enable_ip_limits": false,
    "max_requests_per_ip_hour": 2
  },
  "password_secret_name": "published_retriever_password",
  "include_metadata": true,
  "tags": [
    "<string>"
  ],
  "category": "sandbox"
}
EOF
{
  "public_id": "<string>",
  "retriever_id": "<string>",
  "public_url": "<string>",
  "short_url": "<string>",
  "public_api_key": "<string>"
}

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

​
authorization
string
​
X-Namespace
string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
retriever_id
string
required

ID of the retriever to publish

Body

application/json

Request to publish a retriever.

Either public_name (slug) or display_name (human-readable) is required. If only display_name is provided, a slug is auto-generated from it. If display_config is not provided, the retriever's stored display_config will be used.

​
display_name
string | null

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.

Maximum string length: 100
Example:

"Peptide Evidence Search"

​
public_name
string | null

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.

Required string length: 3 - 50
Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
Example:

"video-search"

​
description
string | null

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

Maximum string length: 500
Example:

"AI-powered video search using semantic understanding"

​
icon_base64
string | null

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.

Maximum string length: 300000
Example:

"data:image/png;base64,iVBORw0KGgoAAAANS..."

​
display_config
DisplayConfig · object

Display configuration defining how the public UI should be rendered. Includes input fields, theme, layout, and exposed result fields. If not provided, uses the retriever's stored display_config.

Example:
{
  "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
RateLimitConfig · object

Rate limiting configuration for public endpoint. Defaults to STANDARD tier (10/min, 100/hour, 1k/day). Use ELEVATED tier for trusted public apps (30/min, 500/hour, 5k/day). Use ENTERPRISE tier for monitored deployments (100/min, 2k/hour, 20k/day). Custom limits override tier defaults.

Examples:
{
  "description": "Standard tier (default) - 10/min, 100/hour, 1k/day",
  "enabled": true,
  "max_results_per_query": 50,
  "tier": "standard"
}
{
  "description": "Elevated tier - 30/min, 500/hour, 5k/day",
  "enable_ip_limits": true,
  "enabled": true,
  "max_requests_per_ip_hour": 100,
  "max_results_per_query": 100,
  "tier": "elevated"
}
{
  "description": "Enterprise tier - 100/min, 2k/hour, 20k/day",
  "enable_ip_limits": true,
  "enabled": true,
  "max_requests_per_ip_hour": 500,
  "max_results_per_query": 200,
  "tier": "enterprise"
}
{
  "description": "Custom limits overriding standard tier",
  "enabled": true,
  "max_results_per_query": 100,
  "requests_per_hour": 200,
  "requests_per_minute": 20,
  "tier": "standard"
}
​
password_secret_name
string | null

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

Example:

"published_retriever_password"

​
include_metadata
boolean
default:true

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

​
tags
string[]

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

Examples:
["sandbox", "demo", "video"]
["marketplace", "adtech"]
​
category
string | null

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

Maximum string length: 50
Example:

"sandbox"

Response

Successful Response

Response after successfully publishing a retriever.

​
public_id
string
required

Public identifier for this published retriever

​
retriever_id
string
required

ID of the underlying retriever

​
public_url
string
required

Full public URL to the retriever page

Example:

"https://mxp.co/r/video-search"

​
short_url
string
required

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

Example:

"https://mxp.co/r/video-search"

​
public_api_key
string | null

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.