Authorizations
Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.
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 sk_live_abc123def456"
"Bearer sk_test_xyz789"
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'
"ns_abc123def456"
"production"
"my-namespace"
Path Parameters
Retriever ID or name.
Body
Request to execute a retriever.
Runtime inputs for the retriever mapped to the input schema. Keys must match the retriever's input_schema field names. Values depend on field types (text, vector, filters, etc.). REQUIRED unless all retriever inputs have defaults.
Stages read these inputs to determine their behavior:
- Search stages: Read 'query', 'embedding', 'top_k'
- Filter stages: Read filter criteria from inputs
- Sort stages: Read sort preferences from inputs
- All stages: Can use template expressions like '{{INPUT.query}}' or '{{inputs.query}}' Template namespaces support both uppercase (INPUT, DOC, CONTEXT, STAGE) and lowercase (inputs, doc, context, stage) formats. All formats work identically.
Common input keys:
- 'query': Text search query
- 'embedding': Pre-computed vector for search
- 'top_k': Number of results to return
- 'min_score': Minimum relevance threshold
- Any custom fields defined in input_schema
Example: {"query": "machine learning", "top_k": 50, "min_score": 0.7}
{
"query": "artificial intelligence",
"top_k": 25
}{
"min_score": 0.7,
"query": "customer feedback",
"top_k": 50
}{
"category": "blog",
"embedding": [0.1, 0.2, 0.3],
"top_k": 10
}OPTIONAL. List of collection identifiers to search. Can contain collection IDs, collection names, or both mixed together. When provided, OVERRIDES the retriever's default collections. When NOT provided, uses the retriever's default collections.
Identifier Resolution:
- IDs (start with 'col_'): Used directly
- Names: Automatically resolved to IDs before execution
- Mixed: Both IDs and names can be provided together
- Deduplication: Duplicate IDs are automatically removed
Use cases:
- Search specific collections: ["col_123", "marketing_2024"]
- Mix IDs and names: ["col_archived", "current_blog_posts"]
- Override retriever defaults: Specify different collections per query
Note: All identifiers must exist in the namespace or request will fail.
1["col_marketing_2024", "sales_materials"]["product_catalog", "col_archived_products"]["blog_posts", "case_studies", "whitepapers"]Pagination strategy configuration. Defaults to cursor-based pagination with limit=20. Supported methods: OFFSET, CURSOR, SCROLL, KEYSET. Each method has different tradeoffs for performance and use cases. Offset-based pagination using page number sizing.
- OffsetPaginationParams
- CursorPaginationParams
- ScrollPaginationParams
- KeysetPaginationParams
Response
Successful Response
Response from retriever execution.
REQUIRED. Unique identifier for this execution run. Use this ID to track execution status, retrieve execution details, or query execution history. Format: 'exec_' prefix followed by alphanumeric token.
"exec_abc123def456"
"exec_xyz789"
REQUIRED. Execution status indicating current state. Common values: 'completed', 'failed', 'processing', 'pending'. Check this field to determine if execution succeeded or requires retry.
"completed"
"failed"
"processing"
REQUIRED. Final document results after retriever completion. Contains documents that passed through all retriever stages. Each document may include: document_id, payload (full document data), score (relevance score), metadata (collection-specific fields), and any fields added by enrichment/join stages. Empty array indicates no documents matched the query criteria. Note: Legacy format may use 'final_results' instead of 'documents'.
[
{
"document_id": "doc_123",
"payload": {
"metadata": { "category": "AI" },
"text": "Sample content"
},
"score": 0.95
},
{
"document_id": "doc_456",
"payload": {
"metadata": { "category": "ML" },
"text": "Another document"
},
"score": 0.88
}
]REQUIRED. Pagination metadata structure. Format varies by pagination method: Offset pagination: {total, limit, offset, has_next, has_previous}, Cursor pagination: {cursor, has_next, page_size}, Keyset pagination: {next_cursor, has_next}. Use this to navigate through result pages.
{
"has_next": true,
"limit": 10,
"offset": 0,
"total": 100
}{
"cursor": "abc123",
"has_next": false,
"page_size": 20
}REQUIRED. Per-stage execution statistics including timing, document counts, cache hit rates, and stage-specific metrics. Use this to understand retriever performance and identify bottlenecks.
REQUIRED. Budget usage snapshot for this execution. Contains: credits_used (credits consumed), credits_remaining (remaining budget), time_used_ms (execution time), and budget limits. Use this to track resource consumption and enforce budget limits.
{
"credits_remaining": 99.5,
"credits_used": 0.5,
"time_used_ms": 150
}OPTIONAL. Retriever-level error message if execution failed. Only present when status='failed'. Contains human-readable error description to help diagnose the failure. Check stage_statistics for stage-specific errors.
"Retriever execution failed: Collection not found"
"Budget exceeded: Maximum credits limit reached"