Create Retriever
Create a new retriever.
A retriever executes a series of stages to find and process documents from one or more collections.
Documentation Index
Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Headers
REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
"Bearer YOUR_API_KEY"
"Bearer YOUR_STRIPE_API_KEY"
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'. Falls back to ?namespace= query parameter if the header is omitted.
"ns_abc123def456"
"production"
"my-namespace"
Body
Payload for creating a new retriever.
Unique retriever name (REQUIRED).
1Ordered stage configurations (REQUIRED).
1Human readable retriever description (OPTIONAL).
Visibility level: PRIVATE (owner only), PUBLIC (any valid API key), MARKETPLACE (requires subscription). Defaults to PRIVATE.
private, public, marketplace Associated marketplace listing ID when visibility is MARKETPLACE (OPTIONAL).
Whether this retriever requires an active subscription to access (marketplace only).
Collection identifiers (names or IDs) queried by the retriever (OPTIONAL). Identifiers can be collection names (e.g., 'my_collection') or collection IDs (e.g., 'col_abc123'). The system will resolve names to IDs automatically. Can be empty for inference-only pipelines (e.g., LLM query analysis without document retrieval). Also accepts 'collection_ids' as an alias for backward compatibility.
["my_collection", "products"]["col_abc123", "col_def456"][]Input schema properties keyed by field name (OPTIONAL). Can be empty for static retrievers with hardcoded stage parameters. Each field can include: type, description, required, default, and examples. The 'examples' field (list) provides sample values that will be shown to users when the retriever is published with include_metadata=true.
{
"category": {
"description": "Filter by category",
"examples": ["electronics", "clothing"],
"required": false,
"type": "string"
},
"query": {
"description": "Search query text",
"examples": ["red sports car", "sunset over ocean"],
"required": true,
"type": "text"
}
}Budget limits for execution (OPTIONAL).
{ "max_credits": 100, "max_time_ms": 60000 }{ "max_time_ms": 120000 }Optional retriever tags for search/filters.
Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever.
{
"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"
}Response
Successful Response
Full retriever definition persisted in MongoDB.
Unique retriever name within namespace (REQUIRED).
1Ordered list of stage configurations (REQUIRED).
1Stable retriever identifier (REQUIRED).
Detailed description of retriever behaviour (OPTIONAL).
Collections queried by the retriever. Can be empty for query-only inference mode.
JSON Schema describing expected user inputs (REQUIRED). Properties must use RetrieverInputSchemaField which supports all bucket types plus document_reference.
Execution budget limits for the retriever (OPTIONAL).
{ "max_credits": 100, "max_time_ms": 60000 }{ "max_time_ms": 120000 }Feature addresses required by stages (OPTIONAL, aids validation).
Arbitrary tags to help organise retrievers (OPTIONAL).
Display configuration for public retriever UI rendering (OPTIONAL). Defines how the search interface should appear when the retriever is published, including input fields, theme, layout, exposed result fields, and field formatting. This configuration is used as the default when publishing the retriever.
Version number that increments on each update (REQUIRED).
x >= 1Creation timestamp in UTC (REQUIRED).
Last update timestamp in UTC (REQUIRED).
Identifier of the user who created the retriever (OPTIONAL).
Identifier of the user who last updated the retriever (OPTIONAL).