Update Published Retriever
Update published retriever configuration.
Allows updating display config, rate limits, exposed fields, and password protection. The public API key and public name cannot be changed (unpublish and republish instead).
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.
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
ID of the retriever
Body
Request to update a published retriever configuration.
Update the display configuration
{
"components": {
"result_card": {
"field_order": ["title", "description", "price"],
"layout": "vertical",
"show_thumbnail": true
},
"result_layout": "grid",
"show_search": true
},
"description": "Search through our product catalog",
"exposed_fields": [
"title",
"description",
"price",
"image_url"
],
"field_config": {
"price": {
"format": "number",
"format_options": {
"decimals": 2,
"label": "Price",
"prefix": "$"
}
},
"title": {
"format": "text",
"format_options": {
"label": "Product Name",
"truncate_chars": 60
}
}
},
"inputs": [
{
"field_name": "query",
"field_schema": {
"description": "Search query",
"examples": ["wireless headphones", "laptop"],
"type": "string"
},
"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"
},
{
"content": "This product search is powered by AI technology that understands what you're looking for, even if you don't use the exact keywords.\n\n[Learn more about our technology](https://example.com/docs)",
"title": "About"
}
],
"theme": {
"font_family": "Inter, sans-serif",
"primary_color": "#007AFF"
},
"title": "Product Search"
}Update rate limiting configuration
{
"description": "Standard tier (default) - 10/min, 100/hour, 1k/day",
"enabled": true,
"max_results_per_query": 50,
"tier": "standard"
}Update or remove password protection (set to empty string to remove)
Activate or deactivate the published retriever
Response
Successful Response
Published retriever model stored in MongoDB.
Uses retriever_id as the primary identifier. Published state is tracked by the existence of this document.
Key Design Decisions:
- retriever_id is the primary identifier (1:1 with Retriever)
- public_id is auto-generated for external/shareable references
- public_api_key is stored in plain text (it's public by design)
- internal_id and namespace_id are automatic from provider
- display_config is a structured Pydantic model (not Dict)
- retriever_metadata is optional technical info (separate from display)
ID of the underlying retriever being published. This is the primary identifier - one retriever can only be published once.
Name of the underlying retriever (denormalized for performance). Populated during publishing to avoid extra lookups during execution.
Public URL-safe slug for the retriever (e.g., 'video-search'). Used in the public URL: apps.mixpeek.com/r/{public_name}
3 - 50Structured configuration for how to render the public search UI. Includes input fields, theme, layout, and exposed result fields. Frontend uses this to dynamically build the interface.
Public-facing identifier for this published retriever. Auto-generated with 'pub_' prefix. Used in public URLs and references.
Public API key for this retriever (stored in plain text). Scoped to this retriever only. Auto-generated with 'prk_' prefix. Safe to share - it's read-only and limited to this retriever.
Rate limiting configuration for the public endpoint
OPTIONAL. Name of organization secret containing password for access protection. If set, users must provide password via X-Retriever-Password header.
"published_retriever_password"
Whether the published retriever is active and accessible
OPTIONAL. Technical metadata explaining how the retriever works. Includes: stages, collections, extractors, capabilities. Only populated if include_metadata=True during publishing.
Organization internal ID (automatically added by provider)
Namespace ID (automatically added by provider)
Timestamp when published (automatically added by provider)
Timestamp when last updated (automatically added by provider)