v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Public Retriever API

Get Public Retriever 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):

curl -X GET "https://api.mixpeek.com/v1/public/retrievers/video-search/config"

Example (recommended):

curl -X GET "https://api.mixpeek.com/v1/marketplace/catalog/video-search/config"
get/v1/public/retrievers/{public_name}/config

Path parameters

public_namestring required

Public name of the published retriever

Public name of the published retriever

Response

Successful Response

public_namestring required

Public name of the retriever

public_api_keystring nullable

DEPRECATED: API keys are no longer required for public access. The execute endpoint can be called without authentication.

password_protectedboolean required

Whether this retriever requires password authentication

Example response

{
  "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"
  },
  "retriever_metadata": {
    "stages": [
      {
        "stage_name": "feature_filter",
        "stage_type": "filter"
      },
      {
        "stage_name": "llm_filter",
        "stage_type": "filter"
      }
    ],
    "collections": [
      {
        "collection_id": "col_abc123",
        "collection_name": "Products",
        "feature_extractor": {
          "name": "multimodal_extractor",
          "version": "v1"
        }
      }
    ],
    "capabilities": {
      "multi_stage_pipeline": true,
      "stage_count": 2,
      "supports_image_search": true,
      "supports_text_search": true
    }
  }
}