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 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data @- <<EOF
{
  "public_name": "<string>",
  "display_config": {
    "title": "<string>",
    "inputs": [
      {
        "field_name": "<string>",
        "field_schema": {
          "type": "string",
          "default": "<unknown>",
          "items": "<unknown>",
          "properties": {},
          "examples": [
            "<unknown>"
          ],
          "description": "<string>",
          "enum": [
            "<unknown>"
          ],
          "required": false
        },
        "label": "<string>",
        "placeholder": "Enter search terms...",
        "helper_text": "Describe the aesthetic, outfit, or vibe you're looking for",
        "suggestions": [
          "streetwear urban",
          "clean girl minimal",
          "summer haul bright"
        ],
        "required": true,
        "order": 0
      }
    ],
    "exposed_fields": [
      "<string>"
    ],
    "description": "Search through thousands of products",
    "logo_url": "https://example.com/logo.png",
    "og_image_url": "https://s3.amazonaws.com/mixpeek-server-dev/org123/ns456/public-retriever-og-images/video-search/og.png",
    "markdowns": [
      {
        "title": "<string>",
        "content": "<string>"
      }
    ],
    "theme": {
      "primary_color": "#007AFF",
      "secondary_color": "#FF6B6B",
      "font_family": "system-ui, -apple-system, sans-serif",
      "background_color": "#FFFFFF",
      "text_color": "#000000"
    },
    "layout": {
      "mode": "grid",
      "columns": 3,
      "gap": "16px"
    },
    "components": {
      "show_search": true,
      "show_filters": false,
      "result_layout": "grid",
      "result_card": {
        "layout": "vertical",
        "show_thumbnail": true,
        "thumbnail_aspect_ratio": "16/9",
        "thumbnail_fit": "cover",
        "show_score": false,
        "truncate_title": 60,
        "truncate_description": 120,
        "field_order": [
          "<string>"
        ]
      }
    },
    "field_config": {}
  },
  "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
}
EOF
{
  "public_id": "<string>",
  "retriever_id": "<string>",
  "public_url": "<string>",
  "short_url": "<string>",
  "public_api_key": "<string>"
}

Headers

​
Authorization
string
required

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

​
X-Namespace
string
required

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'

Path Parameters

​
retriever_id
string
required

ID of the retriever to publish

Body

application/json

Request to publish a retriever.

Requires public_name and display_config. Other fields have sensible defaults.

​
public_name
string
required

Public URL-safe name (lowercase, numbers, hyphens only). Must start and end with alphanumeric character. Will be used in URL: apps.mixpeek.com/r/{public_name}

Required string length: 3 - 50
​
display_config
DisplayConfig · object
required

Display configuration defining how the public UI should be rendered. Includes input fields, theme, layout, and exposed result fields.

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

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

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

​
short_url
string
required

Short URL via mxp.co redirect

​
public_api_key
string
required

Public API key for accessing this retriever. IMPORTANT: Save this key - it's needed for all API requests. It's safe to share since it's scoped to this retriever only.