> ## 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. # Execute Adhoc Retriever > Execute a retriever ad-hoc without persisting the configuration. This endpoint allows you to execute a retriever without saving it to the database. Useful for one-time queries, testing configurations, or temporary searches. Caching: this route does not use the retriever-level execute cache, so ``cache_status`` is always ``disabled`` and there is no ``skip_cache`` parameter. That does NOT mean every response is freshly computed. Individual stages keep their own caches, which this route cannot switch off, so a stage may serve a cached result and report ``cache_hit: true`` under ``stage_statistics.stages[*]`` on a response whose top-level ``cache_status`` reads ``disabled``. The two fields describe different caches. If you need a guaranteed fresh execution, persist the retriever (``POST /retrievers``) and call ``/retrievers/{id}/execute`` with ``skip_cache``, which this route lacks and which does reach the stages. Streaming Execution (stream=True): Response uses Server-Sent Events (SSE) format with Content-Type: text/event-stream. Each stage emits events as it executes, formatted as: data: {json}\n\n Event Types (StreamEventType): - stage_start: Emitted when a stage begins (includes stage_name, stage_index, total_stages) - stage_complete: Emitted when a stage finishes (includes documents, statistics, budget_used) - stage_error: Emitted if a stage fails (includes error message) - execution_complete: Final event with complete results and pagination - execution_error: Emitted if entire execution fails StreamStageEvent Fields: - event_type: Type of event - execution_id: Unique execution identifier - stage_name/stage_index/total_stages: Stage progress info - documents: Intermediate results (stage_complete only) - statistics: Stage metrics (duration_ms, input_count, output_count, efficiency) - budget_used: Cumulative consumption (credits_used, time_elapsed_ms, tokens_used) Response Headers: - Content-Type: text/event-stream - Cache-Control: no-cache - Connection: keep-alive - X-Execution-Mode: adhoc Standard Execution (stream=False, default): - Returns ExecuteRetrieverResponse after all stages complete - Includes X-Execution-Mode: adhoc header - execution_metadata.retriever_persisted = False Use Cases: - One-time queries without saving retriever configuration - Testing stage configurations before persisting - Dynamic retrieval with varying parameters - Real-time progress tracking with streaming ## OpenAPI ````yaml post /v1/retrievers/execute openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/retrievers/execute: post: tags: - Adhoc Retrievers summary: Execute Adhoc Retriever description: >- Execute a retriever ad-hoc without persisting the configuration. This endpoint allows you to execute a retriever without saving it to the database. Useful for one-time queries, testing configurations, or temporary searches. Caching: this route does not use the retriever-level execute cache, so ``cache_status`` is always ``disabled`` and there is no ``skip_cache`` parameter. That does NOT mean every response is freshly computed. Individual stages keep their own caches, which this route cannot switch off, so a stage may serve a cached result and report ``cache_hit: true`` under ``stage_statistics.stages[*]`` on a response whose top-level ``cache_status`` reads ``disabled``. The two fields describe different caches. If you need a guaranteed fresh execution, persist the retriever (``POST /retrievers``) and call ``/retrievers/{id}/execute`` with ``skip_cache``, which this route lacks and which does reach the stages. Streaming Execution (stream=True): Response uses Server-Sent Events (SSE) format with Content-Type: text/event-stream. Each stage emits events as it executes, formatted as: data: {json}\n\n Event Types (StreamEventType): - stage_start: Emitted when a stage begins (includes stage_name, stage_index, total_stages) - stage_complete: Emitted when a stage finishes (includes documents, statistics, budget_used) - stage_error: Emitted if a stage fails (includes error message) - execution_complete: Final event with complete results and pagination - execution_error: Emitted if entire execution fails StreamStageEvent Fields: - event_type: Type of event - execution_id: Unique execution identifier - stage_name/stage_index/total_stages: Stage progress info - documents: Intermediate results (stage_complete only) - statistics: Stage metrics (duration_ms, input_count, output_count, efficiency) - budget_used: Cumulative consumption (credits_used, time_elapsed_ms, tokens_used) Response Headers: - Content-Type: text/event-stream - Cache-Control: no-cache - Connection: keep-alive - X-Execution-Mode: adhoc Standard Execution (stream=False, default): - Returns ExecuteRetrieverResponse after all stages complete - Includes X-Execution-Mode: adhoc header - execution_metadata.retriever_persisted = False Use Cases: - One-time queries without saving retriever configuration - Testing stage configurations before persisting - Dynamic retrieval with varying parameters - Real-time progress tracking with streaming operationId: execute_adhoc_retriever_v1_retrievers_execute_post parameters: - name: return_presigned_urls in: query required: false schema: type: boolean default: false title: Return Presigned Urls - name: return_vectors in: query required: false schema: type: boolean default: false title: Return Vectors requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdhocExecuteRequest' responses: '200': description: Successful Response content: application/json: schema: {} '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] NamespaceHeader: [] components: schemas: AdhocExecuteRequest: properties: collection_identifiers: items: type: string type: array title: Collection Identifiers description: >- Collection identifiers (names or IDs) to query. Can be collection names or IDs. Names are automatically resolved. Can be empty for query-only inference mode (e.g., LLM query analysis without documents). Also accepts 'collection_ids' as an alias for backward compatibility. examples: - - my_collection - - col_abc123 - products - [] input_schema: additionalProperties: $ref: '#/components/schemas/RetrieverInputSchemaField-Input' description: >- Schema definition for this input field. Defines type, description, examples, and validation rules. Supports all bucket types (string, number, image, etc.) plus document_reference. Frontend uses this to render the appropriate input component (text input, image upload, dropdown, etc.) type: object title: Input Schema description: >- OPTIONAL. Input schema defining expected inputs. Each key is an input name, value is a RetrieverInputSchemaField. Omit it (or pass {}) for a stages-only execute whose stages carry hardcoded query values — no dynamic inputs needed. examples: - query: description: Search query required: true type: text - query: required: true type: text top_k: required: false type: integer stages: items: $ref: '#/components/schemas/StageConfig-Input' type: array minItems: 1 title: Stages description: >- REQUIRED. Ordered list of stage configurations. At least one stage is required for execution. inputs: additionalProperties: true type: object title: Inputs description: >- OPTIONAL. Input values matching the input_schema. These values are passed to stages for parameterization. Omit it (or pass {}) when the stages carry hardcoded query values. examples: - query: machine learning - query: AI trends top_k: 50 budget_limits: anyOf: - $ref: '#/components/schemas/BudgetLimits' - type: 'null' description: OPTIONAL. Budget limits for execution. pagination: anyOf: - oneOf: - $ref: '#/components/schemas/OffsetPaginationParams' - $ref: '#/components/schemas/CursorPaginationParams' - $ref: '#/components/schemas/ScrollPaginationParams' - $ref: '#/components/schemas/KeysetPaginationParams' discriminator: propertyName: method mapping: cursor: $ref: '#/components/schemas/CursorPaginationParams' keyset: $ref: '#/components/schemas/KeysetPaginationParams' offset: $ref: '#/components/schemas/OffsetPaginationParams' scroll: $ref: '#/components/schemas/ScrollPaginationParams' - type: 'null' title: Pagination description: >- OPTIONAL. Pagination for the result page, same contract as the by-id execute request (cursor/offset/keyset/scroll). When omitted, the page defaults to the pipeline's declared breadth (final_top_k, or the widest explicit per-search top_k when final_top_k is unset), falling back to 10 when the stages declare no breadth. Previously this field did not exist and a supplied value was silently ignored (BACKE-3445). examples: - null - limit: 50 method: cursor limit: anyOf: - type: integer maximum: 100 minimum: 1 - type: 'null' title: Limit description: >- DEPRECATED alias for the pagination page size, honored only when 'pagination' is absent — mirrors the by-id execute request. Previously silently ignored on adhoc bodies (BACKE-3445). deprecated: true examples: - null - 50 stream: type: boolean title: Stream description: >- Enable streaming execution to receive real-time stage updates via Server-Sent Events (SSE). NOT REQUIRED - defaults to False for standard execution. When stream=True: - Response Content-Type: text/event-stream - Events emitted: stage_start, stage_complete, stage_error, execution_complete, execution_error - Each event is formatted as: data: {json}\n\n - StreamStageEvent contains: event_type, execution_id, stage_name, stage_index, total_stages, documents (intermediate), statistics, budget_used When to use streaming: - Progress tracking for multi-stage pipelines - Displaying intermediate results as stages complete - Real-time budget and performance monitoring - Debugging pipeline execution When to skip streaming: - Single-stage or fast pipelines (<100ms) - No need for intermediate results - Minimizing overhead is critical default: false examples: - false - true type: object required: - stages title: AdhocExecuteRequest description: >- Request to execute a retriever ad-hoc without persistence. This combines retriever creation parameters with execution inputs to allow one-time retrieval without saving the retriever configuration. Use Cases: - One-time queries without polluting retriever registry - Testing retriever configurations before persisting - Dynamic retrieval with varying stage configurations - Temporary search operations Behavior: - Retriever is NOT saved to database - Execution history is logged but marked as ad-hoc - Response includes X-Execution-Mode: adhoc header - execution_metadata.retriever_persisted = False Streaming Execution (stream=True): When streaming is enabled, the response uses Server-Sent Events (SSE) format with Content-Type: text/event-stream. Each stage emits events as it executes: Event Types: - stage_start: Emitted when a stage begins execution - stage_complete: Emitted when a stage finishes with results - stage_error: Emitted if a stage encounters an error - execution_complete: Emitted after all stages finish successfully - execution_error: Emitted if the entire execution fails Each event is a StreamStageEvent containing: - event_type: The type of event - execution_id: Unique execution identifier - stage_name: Human-readable stage name - stage_index: Zero-based stage position - total_stages: Total number of stages - documents: Intermediate results (for stage_complete) - statistics: Stage metrics (duration_ms, input_count, output_count, etc.) - budget_used: Cumulative resource consumption (credits, time, tokens) Response Headers (streaming): - Content-Type: text/event-stream - Cache-Control: no-cache - Connection: keep-alive - X-Execution-Mode: adhoc Example streaming request: ```python response = requests.post( '/v1/retrievers/execute', json={ 'collection_identifiers': ['my_collection'], 'input_schema': {'query': {'type': 'text', 'required': True}}, 'stages': [...], 'inputs': {'query': 'machine learning'}, 'stream': True }, stream=True ) for line in response.iter_lines(): if line.startswith(b'data: '): event = json.loads(line[6:]) print(f"{event['event_type']}: {event.get('stage_name')}") ``` Standard Execution (stream=False, default): Returns a single ExecuteRetrieverResponse with final documents, pagination, and aggregate statistics after all stages complete. Examples: Simple ad-hoc search: { "collection_identifiers": ["col_123"], "input_schema": {"query": {"type": "text", "required": True}}, "stages": [{ "stage_name": "search", "stage_type": "filter", "config": { "stage_id": "feature_search", "parameters": { "searches": [{ "feature_uri": "mixpeek://text_extractor@v1/embedding", "query": { "input_mode": "text", "text": "{{INPUT.query}}" }, "top_k": 100 }], "final_top_k": 10 } } }], "inputs": {"query": "machine learning"}, "stream": false } ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError RetrieverInputSchemaField-Input: properties: type: $ref: '#/components/schemas/RetrieverInputSchemaFieldType' default: anyOf: - {} - type: 'null' title: Default items: anyOf: - $ref: '#/components/schemas/RetrieverInputSchemaField-Input' - type: 'null' properties: anyOf: - additionalProperties: $ref: '#/components/schemas/RetrieverInputSchemaField-Input' type: object - type: 'null' title: Properties examples: anyOf: - items: {} type: array - type: 'null' title: Examples description: >- OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible. description: anyOf: - type: string - type: 'null' title: Description enum: anyOf: - items: {} type: array - type: 'null' title: Enum required: anyOf: - type: boolean - type: 'null' title: Required default: false additionalProperties: true type: object required: - type title: RetrieverInputSchemaField description: >- Schema field definition for retriever input parameters. Identical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType which includes additional reference types like document_reference. This allows retrievers to accept: 1. Metadata inputs (strings, numbers, dates, etc.) 2. File inputs (images, videos, documents for search) 3. Reference inputs (document_reference for "find similar" queries) StageConfig-Input: properties: stage_name: type: string minLength: 1 title: Stage Name description: Human-readable stage instance name (REQUIRED). stage_type: anyOf: - $ref: '#/components/schemas/StageType' - type: 'null' description: >- Functional category of the stage. Optional for creation requests; auto-inferred from `stage_id` when omitted. config: additionalProperties: true type: object title: Config description: >- Stage implementation parameters (REQUIRED). Must include `stage_id` key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under `parameters`. Optional `pre_filters` and `post_filters` are placed as SIBLINGS of `parameters` (NOT nested inside). Pre-filters require payload indexes on the filtered fields. batch_size: anyOf: - type: string - type: 'null' title: Batch Size description: >- Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted. description: anyOf: - type: string - type: 'null' title: Description description: User-facing description of the stage (OPTIONAL). on_error: anyOf: - type: string - type: 'null' title: On Error description: >- Behavior when this stage fails. 'skip' continues execution with results from previous stages (graceful degradation). 'error' (default) fails the entire retriever. Useful for optional enrichment or multi-modal stages where one modality may not apply (e.g., face search on logo-only images). output_alias: anyOf: - type: string - type: 'null' title: Output Alias description: >- Optional alias to persist this stage's results in the execution context. When set, results are stored in CONTEXT. in addition to replacing current_results. Downstream stages can reference them via {{CONTEXT.}} in templates. Useful for multi-stage pipelines where later stages should not overwrite earlier results (e.g., face search + logo search producing independent result sets). type: object required: - stage_name - config title: StageConfig description: >- Configuration for a single stage within a retriever. Stages support dynamic configuration through template expressions using Jinja2 syntax. IMPORTANT - Template Syntax: - Use DOUBLE curly braces: {{INPUT.query}} (correct) - Single curly braces will NOT work: {INPUT.query} (wrong - not substituted) - Namespace names are CASE-INSENSITIVE: {{INPUT.query}}, {{inputs.query}}, {{input.query}} all work identically Template Namespaces (case-insensitive): - INPUT / inputs / input: User-provided query parameters and inputs - DOC / doc: Current document fields (for per-document logic) - CONTEXT / context: Execution state (budget, timing, retriever metadata) - STAGE / stage: Previous stage outputs (for cascading logic) Examples: Correct: {{INPUT.query_text}}, {{inputs.query}}, {{DOC.content_type}} Correct: {{CONTEXT.budget_remaining}}, {{context.budget_remaining}} Wrong: {INPUT.query} - single braces won't be substituted examples: - config: parameters: final_top_k: 25 searches: - feature_uri: >- mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1 query: input_mode: text value: '{{INPUT.query_text}}' top_k: 100 stage_id: feature_search description: Feature search stage with uppercase template namespace stage_name: semantic_search stage_type: filter - batch_size: '{{20 * inputs.page_size}}' config: parameters: field: metadata.price operator: gt value: '{{inputs.min_price}}' stage_id: attribute_filter description: Attribute filter with lowercase template namespace stage_name: price_filter stage_type: filter - config: parameters: batch_size: '{{CONTEXT.budget_remaining > 50 ? 200 : 50}}' criteria: '{{inputs.quality_criteria}}' field: '{{DOC.media_type == ''image'' ? ''image_url'' : ''video_url''}}' stage_id: llm_filter description: Mixed case templates in same stage stage_name: llm_filter stage_type: filter - config: parameters: final_top_k: 10 searches: - feature_uri: >- mixpeek://web_scraper@v1/jinaai__jina_embeddings_v2_base_code query: input_mode: text value: '{{INPUT.query}}' top_k: 50 pre_filters: AND: - field: doc_type operator: eq value: code stage_id: feature_search description: Feature search with pre_filters (sibling of parameters, NOT inside) stage_name: search_code_blocks stage_type: filter BudgetLimits: properties: max_credits: anyOf: - type: number minimum: 0 - type: 'null' title: Max Credits description: Maximum credits allowed for a single execution (OPTIONAL). max_time_ms: anyOf: - type: integer minimum: 0 - type: 'null' title: Max Time Ms description: >- Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL). type: object title: BudgetLimits description: User-defined limits for time and credits during execution. examples: - max_credits: 100 max_time_ms: 60000 - max_time_ms: 120000 OffsetPaginationParams: properties: method: type: string const: offset title: Method description: Constant identifying offset pagination (REQUIRED). default: offset page_size: type: integer maximum: 500 minimum: 1 title: Page Size description: 'Number of documents per page (REQUIRED). Default: 10.' default: 10 page_number: type: integer minimum: 1 title: Page Number description: '1-based page index to retrieve (REQUIRED). Default: 1.' default: 1 type: object title: OffsetPaginationParams description: |- Offset-based pagination using page number sizing. Best for: Traditional page UIs with page number navigation How it works: - Uses page numbers (1, 2, 3...) and page size - Calculates offset as: (page_number - 1) * page_size - Simple and familiar for users - Can jump to any page directly Tradeoffs: - Can have "page drift" if data changes between requests - Example: Items added/deleted causes duplicates or gaps - Less efficient for large offsets (database must skip N rows) Use when: - Building traditional page-numbered UIs - Users need to jump to specific pages - Result set is relatively stable - Working with smaller datasets Example: Page 1: {"method": "offset", "page_size": 25, "page_number": 1} Page 2: {"method": "offset", "page_size": 25, "page_number": 2} CursorPaginationParams: properties: method: type: string const: cursor title: Method description: Constant identifying cursor pagination (REQUIRED). default: cursor limit: type: integer maximum: 500 minimum: 1 title: Limit description: >- Maximum number of documents to return per page (REQUIRED). Default: 10. default: 10 cursor: anyOf: - type: string - type: 'null' title: Cursor description: >- Opaque base64 cursor from previous response (OPTIONAL). null for first page, then use cursor from response.pagination.cursor type: object title: CursorPaginationParams description: >- Cursor-based pagination referencing last seen position. Best for: Infinite scroll UIs, mobile apps, real-time feeds How it works: - First request: cursor=null - Response includes next cursor token - Next request: pass cursor from previous response - Stateless: no server-side state - Consistent: no duplicates/gaps even with concurrent writes Use when: - Building infinite scroll interfaces - Users scroll through results sequentially - You need consistency across pages - You don't need to jump to arbitrary pages Example flow: 1. Request: {"method": "cursor", "limit": 20, "cursor": null} 2. Response: {"documents": [...], "pagination": {"cursor": "abc123", "has_next": true}} 3. Request: {"method": "cursor", "limit": 20, "cursor": "abc123"} ScrollPaginationParams: properties: method: type: string const: scroll title: Method description: Constant identifying scroll pagination (REQUIRED). default: scroll limit: type: integer maximum: 1000 minimum: 1 title: Limit description: >- Number of documents to fetch per scroll page (REQUIRED). Default: 100. default: 100 scroll_id: anyOf: - type: string - type: 'null' title: Scroll Id description: >- Server-issued scroll session identifier (OPTIONAL). null for first request, then use scroll_id from response scroll_ttl: type: integer maximum: 3600 minimum: 60 title: Scroll Ttl description: >- Seconds to keep scroll context alive (REQUIRED). Default: 300 (5 minutes). default: 300 type: object title: ScrollPaginationParams description: >- Scroll-style pagination maintaining server-side context for TTL. Best for: Bulk exports, batch processing, iterating through all results How it works: - Server maintains a snapshot of results - First request: scroll_id=null, returns scroll_id - Subsequent requests: use scroll_id from response - Context expires after scroll_ttl seconds - Consistent view of data (point-in-time snapshot) Tradeoffs: - Requires server-side state (memory/cache) - TTL means sessions can expire - Not suitable for long-lived sessions - Good for background jobs, not user-facing UIs Use when: - Exporting large datasets - Batch processing all results - Background jobs iterating through results - You need consistent point-in-time view Example flow: 1. Request: {"method": "scroll", "limit": 100, "scroll_id": null} 2. Response: {"documents": [...], "scroll_id": "xyz789", "has_next": true} 3. Request: {"method": "scroll", "limit": 100, "scroll_id": "xyz789"} KeysetPaginationParams: properties: method: type: string const: keyset title: Method description: Constant identifying keyset pagination (REQUIRED). default: keyset limit: type: integer maximum: 500 minimum: 1 title: Limit description: >- Maximum number of documents to return per page (REQUIRED). Default: 10. default: 10 after: anyOf: - additionalProperties: true type: object - type: 'null' title: After description: >- Last seen keyset marker from previous response (OPTIONAL). Must include all sort fields. Example: {'score': 0.73, 'id': 'doc_20'}. null for first page, then use next_cursor from response type: object title: KeysetPaginationParams description: >- Stateless keyset pagination relying on last seen sort key. Best for: High-performance pagination, large result sets, stable sorting How it works: - Uses actual field values as pagination markers - Database can use indexes efficiently (WHERE score < 0.73) - No offset calculation or server state - Requires deterministic sort order (e.g., score DESC, id ASC) - Most efficient pagination method Requirements: - Results must be sorted consistently - Sort fields must be in the "after" marker - Example: sorted by (score DESC, id ASC) → after: {score: 0.73, id: "doc_20"} Advantages: - No server-side state (truly stateless) - Consistent even with concurrent writes - Database can use indexes (fast for large datasets) - No offset performance degradation Use when: - You have stable, deterministic sort fields - Working with large result sets (10k+ docs) - Maximum performance is critical - You need infinite scroll with best efficiency Example flow: 1. Request: {"method": "keyset", "limit": 20, "after": null} 2. Response: {"documents": [...], "next_cursor": {"score": 0.85, "id": "doc_20"}} 3. Request: {"method": "keyset", "limit": 20, "after": {"score": 0.85, "id": "doc_20"}} ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError RetrieverInputSchemaFieldType: type: string enum: - string - number - integer - float - boolean - object - array - date - datetime - text - image - audio - video - pdf - excel - document_reference title: RetrieverInputSchemaFieldType description: >- Supported data types for retriever input schema fields. Retriever input schemas define what parameters users can provide when executing a retriever. This includes all bucket schema types plus additional reference types. Types fall into three categories: 1. **Metadata Types** (JSON types): - Standard JSON-compatible types - Examples: string, number, boolean, date - Inherited from BucketSchemaFieldType 2. **File Types** (blobs): - Users can upload files/content as search inputs - Examples: text, image, video, pdf - Inherited from BucketSchemaFieldType 3. **Reference Types** (structured metadata): - Special types for referencing existing documents - Examples: document_reference - Only available in retriever input schemas (NOT in bucket schemas) **DOCUMENT_REFERENCE Usage**: Accept document reference for "find similar" queries. Example - Find similar products retriever: { "reference_product": { "type": "document_reference", "description": "Find products similar to this one", "required": true } } Execution input: { "inputs": { "reference_product": { "collection_id": "col_products", "document_id": "doc_item_123" } } } The system will use the pre-computed features from doc_item_123 to find similar documents without re-processing. StageType: type: string enum: - filter - sort - reduce - apply - enrich title: StageType description: >- Categorisation of stage behaviour within a retrieval flow. These functional categories describe how stages transform the document stream: - FILTER: N → ≤N documents (subset, same schema) - SORT: N → N documents (same docs, different order, same schema) - REDUCE: N → 1 document (aggregation, new schema) - APPLY: N → N or N*M documents (enrichment/expansion, expanded/new schema) - ENRICH: N → N documents (enrichment with computed fields) securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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 header returns 403; an invalid or revoked key returns 401. NamespaceHeader: type: apiKey in: header name: X-Namespace description: >- 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`. ````