Skip to main content
POST
/
v1
/
public
/
retrievers
/
{public_name}
/
execute
Execute Public Retriever
curl --request POST \
  --url https://api.mixpeek.com/v1/public/retrievers/{public_name}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Public-API-Key: <x-public-api-key>' \
  --data '
{
  "inputs": {},
  "collection_identifiers": [
    "col_marketing_2024",
    "sales_materials"
  ],
  "pagination": {
    "method": "offset",
    "page_size": 10,
    "page_number": 1
  }
}
'
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  },
  "success": false
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Public-API-Key
string
required
​
X-Retriever-Password
string | null

Path Parameters

​
public_name
string
required

Public name of the published retriever

Query Parameters

​
return_urls
boolean
default:true

Whether to return signed URLs for media assets (images, videos, audio). Default: True for public retrievers to enable media rendering. Set to False if you only need metadata without URLs.

Body

application/json

Request payload for executing a retriever.

Executes a predefined retriever with runtime inputs and optional collection overrides. All filtering, pagination, and result shaping is handled by the individual stages based on the inputs provided.

Use Cases: - Execute retriever with default collections - Override collections at query time (by ID or name) - Pass inputs that stages use to determine filtering/pagination behavior

Collection Resolution: - If collection_identifiers not provided: uses retriever defaults - If provided: OVERRIDES retriever defaults - Can contain collection IDs, names, or both - Names are automatically resolved to IDs before execution - Duplicates are automatically deduplicated

Design Philosophy: - Filters, limits, and offsets are NOT top-level request fields - These are handled by stages when they receive inputs - Example: A stage might read {INPUT.top_k} to determine result limit - This keeps the execution model simple and stage-driven

Examples: Default collections: {"inputs": {"query": "AI", "top_k": 50}}

Override collections with mixed IDs and names:
    {"inputs": {"query": "AI", "top_k": 50},
     "collection_identifiers": ["col_123", "marketing", "sales"]}

Different inputs for stage behavior:
    {"inputs": {
        "query": "machine learning",
        "top_k": 100,
        "min_score": 0.7,
        "published_after": "2024-01-01"
     }}
​
inputs
Inputs · object

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}

​
collection_identifiers
string[] | null

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.

Minimum array length: 1
Example:
["col_marketing_2024", "sales_materials"]
​
pagination
OffsetPaginationParams · object

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.

Response

Successful Response