curl --request POST \
--url https://api.mixpeek.com/v1/retrievers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"collection_identifiers": [
"product_embeddings"
],
"input_schema": {
"query": {
"description": "Search query",
"required": true,
"type": "text"
}
},
"retriever_name": "product_search",
"stages": [
{
"config": {
"parameters": {
"final_top_k": 20,
"searches": [
{
"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
"query": {
"input_mode": "text",
"value": "{{INPUT.query}}"
},
"top_k": 100
}
]
},
"stage_id": "feature_search"
},
"stage_name": "search",
"stage_type": "filter"
}
]
}
'import requests
url = "https://api.mixpeek.com/v1/retrievers"
payload = {
"collection_identifiers": ["product_embeddings"],
"input_schema": { "query": {
"description": "Search query",
"required": True,
"type": "text"
} },
"retriever_name": "product_search",
"stages": [
{
"config": {
"parameters": {
"final_top_k": 20,
"searches": [
{
"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
"query": {
"input_mode": "text",
"value": "{{INPUT.query}}"
},
"top_k": 100
}
]
},
"stage_id": "feature_search"
},
"stage_name": "search",
"stage_type": "filter"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
collection_identifiers: ['product_embeddings'],
input_schema: {query: {description: 'Search query', required: true, type: 'text'}},
retriever_name: 'product_search',
stages: [
{
config: {
parameters: {
final_top_k: 20,
searches: [
{
feature_uri: 'mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1',
query: {input_mode: 'text', value: '{{INPUT.query}}'},
top_k: 100
}
]
},
stage_id: 'feature_search'
},
stage_name: 'search',
stage_type: 'filter'
}
]
})
};
fetch('https://api.mixpeek.com/v1/retrievers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/retrievers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'collection_identifiers' => [
'product_embeddings'
],
'input_schema' => [
'query' => [
'description' => 'Search query',
'required' => true,
'type' => 'text'
]
],
'retriever_name' => 'product_search',
'stages' => [
[
'config' => [
'parameters' => [
'final_top_k' => 20,
'searches' => [
[
'feature_uri' => 'mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1',
'query' => [
'input_mode' => 'text',
'value' => '{{INPUT.query}}'
],
'top_k' => 100
]
]
],
'stage_id' => 'feature_search'
],
'stage_name' => 'search',
'stage_type' => 'filter'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/retrievers"
payload := strings.NewReader("{\n \"collection_identifiers\": [\n \"product_embeddings\"\n ],\n \"input_schema\": {\n \"query\": {\n \"description\": \"Search query\",\n \"required\": true,\n \"type\": \"text\"\n }\n },\n \"retriever_name\": \"product_search\",\n \"stages\": [\n {\n \"config\": {\n \"parameters\": {\n \"final_top_k\": 20,\n \"searches\": [\n {\n \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"query\": {\n \"input_mode\": \"text\",\n \"value\": \"{{INPUT.query}}\"\n },\n \"top_k\": 100\n }\n ]\n },\n \"stage_id\": \"feature_search\"\n },\n \"stage_name\": \"search\",\n \"stage_type\": \"filter\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/retrievers")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"collection_identifiers\": [\n \"product_embeddings\"\n ],\n \"input_schema\": {\n \"query\": {\n \"description\": \"Search query\",\n \"required\": true,\n \"type\": \"text\"\n }\n },\n \"retriever_name\": \"product_search\",\n \"stages\": [\n {\n \"config\": {\n \"parameters\": {\n \"final_top_k\": 20,\n \"searches\": [\n {\n \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"query\": {\n \"input_mode\": \"text\",\n \"value\": \"{{INPUT.query}}\"\n },\n \"top_k\": 100\n }\n ]\n },\n \"stage_id\": \"feature_search\"\n },\n \"stage_name\": \"search\",\n \"stage_type\": \"filter\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"collection_identifiers\": [\n \"product_embeddings\"\n ],\n \"input_schema\": {\n \"query\": {\n \"description\": \"Search query\",\n \"required\": true,\n \"type\": \"text\"\n }\n },\n \"retriever_name\": \"product_search\",\n \"stages\": [\n {\n \"config\": {\n \"parameters\": {\n \"final_top_k\": 20,\n \"searches\": [\n {\n \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"query\": {\n \"input_mode\": \"text\",\n \"value\": \"{{INPUT.query}}\"\n },\n \"top_k\": 100\n }\n ]\n },\n \"stage_id\": \"feature_search\"\n },\n \"stage_name\": \"search\",\n \"stage_type\": \"filter\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"budget_limits": {
"max_credits": 100,
"max_time_ms": 60000
},
"collection_ids": [
"col_marketing_ads"
],
"input_schema": {
"query_text": {
"description": "Full-text query",
"type": "string"
}
},
"retriever_id": "ret_abc123",
"retriever_name": "executive_ads_search",
"stages": [
{
"config": {
"parameters": {
"field": "metadata.spend",
"operator": "gt",
"value": 1000
},
"stage_id": "attribute_filter"
},
"stage_name": "filter_high_spend",
"stage_type": "filter"
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Create Retriever
Create a new retriever.
A retriever executes a series of stages to find and process documents from one or more collections.
curl --request POST \
--url https://api.mixpeek.com/v1/retrievers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"collection_identifiers": [
"product_embeddings"
],
"input_schema": {
"query": {
"description": "Search query",
"required": true,
"type": "text"
}
},
"retriever_name": "product_search",
"stages": [
{
"config": {
"parameters": {
"final_top_k": 20,
"searches": [
{
"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
"query": {
"input_mode": "text",
"value": "{{INPUT.query}}"
},
"top_k": 100
}
]
},
"stage_id": "feature_search"
},
"stage_name": "search",
"stage_type": "filter"
}
]
}
'import requests
url = "https://api.mixpeek.com/v1/retrievers"
payload = {
"collection_identifiers": ["product_embeddings"],
"input_schema": { "query": {
"description": "Search query",
"required": True,
"type": "text"
} },
"retriever_name": "product_search",
"stages": [
{
"config": {
"parameters": {
"final_top_k": 20,
"searches": [
{
"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
"query": {
"input_mode": "text",
"value": "{{INPUT.query}}"
},
"top_k": 100
}
]
},
"stage_id": "feature_search"
},
"stage_name": "search",
"stage_type": "filter"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
collection_identifiers: ['product_embeddings'],
input_schema: {query: {description: 'Search query', required: true, type: 'text'}},
retriever_name: 'product_search',
stages: [
{
config: {
parameters: {
final_top_k: 20,
searches: [
{
feature_uri: 'mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1',
query: {input_mode: 'text', value: '{{INPUT.query}}'},
top_k: 100
}
]
},
stage_id: 'feature_search'
},
stage_name: 'search',
stage_type: 'filter'
}
]
})
};
fetch('https://api.mixpeek.com/v1/retrievers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/retrievers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'collection_identifiers' => [
'product_embeddings'
],
'input_schema' => [
'query' => [
'description' => 'Search query',
'required' => true,
'type' => 'text'
]
],
'retriever_name' => 'product_search',
'stages' => [
[
'config' => [
'parameters' => [
'final_top_k' => 20,
'searches' => [
[
'feature_uri' => 'mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1',
'query' => [
'input_mode' => 'text',
'value' => '{{INPUT.query}}'
],
'top_k' => 100
]
]
],
'stage_id' => 'feature_search'
],
'stage_name' => 'search',
'stage_type' => 'filter'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/retrievers"
payload := strings.NewReader("{\n \"collection_identifiers\": [\n \"product_embeddings\"\n ],\n \"input_schema\": {\n \"query\": {\n \"description\": \"Search query\",\n \"required\": true,\n \"type\": \"text\"\n }\n },\n \"retriever_name\": \"product_search\",\n \"stages\": [\n {\n \"config\": {\n \"parameters\": {\n \"final_top_k\": 20,\n \"searches\": [\n {\n \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"query\": {\n \"input_mode\": \"text\",\n \"value\": \"{{INPUT.query}}\"\n },\n \"top_k\": 100\n }\n ]\n },\n \"stage_id\": \"feature_search\"\n },\n \"stage_name\": \"search\",\n \"stage_type\": \"filter\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/retrievers")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"collection_identifiers\": [\n \"product_embeddings\"\n ],\n \"input_schema\": {\n \"query\": {\n \"description\": \"Search query\",\n \"required\": true,\n \"type\": \"text\"\n }\n },\n \"retriever_name\": \"product_search\",\n \"stages\": [\n {\n \"config\": {\n \"parameters\": {\n \"final_top_k\": 20,\n \"searches\": [\n {\n \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"query\": {\n \"input_mode\": \"text\",\n \"value\": \"{{INPUT.query}}\"\n },\n \"top_k\": 100\n }\n ]\n },\n \"stage_id\": \"feature_search\"\n },\n \"stage_name\": \"search\",\n \"stage_type\": \"filter\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"collection_identifiers\": [\n \"product_embeddings\"\n ],\n \"input_schema\": {\n \"query\": {\n \"description\": \"Search query\",\n \"required\": true,\n \"type\": \"text\"\n }\n },\n \"retriever_name\": \"product_search\",\n \"stages\": [\n {\n \"config\": {\n \"parameters\": {\n \"final_top_k\": 20,\n \"searches\": [\n {\n \"feature_uri\": \"mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1\",\n \"query\": {\n \"input_mode\": \"text\",\n \"value\": \"{{INPUT.query}}\"\n },\n \"top_k\": 100\n }\n ]\n },\n \"stage_id\": \"feature_search\"\n },\n \"stage_name\": \"search\",\n \"stage_type\": \"filter\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"budget_limits": {
"max_credits": 100,
"max_time_ms": 60000
},
"collection_ids": [
"col_marketing_ads"
],
"input_schema": {
"query_text": {
"description": "Full-text query",
"type": "string"
}
},
"retriever_id": "ret_abc123",
"retriever_name": "executive_ads_search",
"stages": [
{
"config": {
"parameters": {
"field": "metadata.spend",
"operator": "gt",
"value": 1000
},
"stage_id": "attribute_filter"
},
"stage_name": "filter_high_spend",
"stage_type": "filter"
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.
Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.
Body
Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).
Payload for creating a new retriever.
Unique retriever name (REQUIRED).
1Ordered stage configurations (REQUIRED). Each stage is {"stage_name": , "config": {"stage_id": , "parameters": {...}}}. List available stage types + parameters via GET /v1/retrievers/stages, or POST /v1/templates/scaffolds/default for a ready-made retriever.
1Show child attributes
Show child attributes
[
{
"config": {
"parameters": {
"final_top_k": 50,
"searches": [
{
"feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
"query": {
"input_mode": "text",
"text": "{{INPUT.query}}"
},
"top_k": 100
}
]
},
"stage_id": "feature_search"
},
"stage_name": "search"
}
]
Human 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.
Show child attributes
Show child attributes
{
"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).
Show child attributes
Show child attributes
{ "max_credits": 100, "max_time_ms": 60000 }
{ "max_time_ms": 120000 }
Optional retriever tags for search/filters.
Custom key-value metadata stored on the retriever (OPTIONAL). Round-trips on create/get/list and is updatable via PATCH — useful for automation markers like seed/config versions. Previously this field was silently dropped on create (FRUSTRATIONS silent-drop class).
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.
Show child attributes
Show child attributes
{
"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
Response after creating a retriever.
Returns the retriever configuration at top level (flat), consistent with POST /namespaces and POST /collections which also return the created resource directly.
Unique retriever name within namespace (REQUIRED).
1Ordered list of stage configurations (REQUIRED).
1Show child attributes
Show child attributes
Fusion strategy used by this retriever's feature_search stage (e.g. 'learned', 'rrf', 'dbsf'). Null if no feature_search stage.
Mirror of collection_ids under the field name CREATE accepts (collection_identifiers), so a create → read round-trip reads back the field it wrote. Always equal to collection_ids (FRUSTRATIONS 2026-07-16: SDKs/agents re-reading their own write saw collection_identifiers null and concluded the retriever was unscoped).
Stable 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.
Show child attributes
Show child attributes
Execution budget limits for the retriever (OPTIONAL).
Show child attributes
Show child attributes
{ "max_credits": 100, "max_time_ms": 60000 }
{ "max_time_ms": 120000 }
Feature addresses required by stages (OPTIONAL, aids validation).
Show child attributes
Show child attributes
Arbitrary tags to help organise retrievers (OPTIONAL).
Custom key-value metadata (OPTIONAL). Round-trips on create/get/list and is updatable via PATCH — useful for automation markers like seed/config versions.
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).
Advisory notes about the saved retriever. A stage that reads a field none of its target collections' synced schemas contain is named here: it will match nothing until documents carry that field. A collection with no documents yet has no schema and is not checked. Warnings never block creation.
Was this page helpful?