Execute Public Retriever

Execute a published retriever (public endpoint).

Authentication:

• API key is OPTIONAL for public retrievers
• Supports: no key, prk_ keys (deprecated), or ret_sk_ keys
• If password-protected, requires X-Retriever-Password header

Rate Limiting:

• Subject to per-retriever rate limits (per minute/hour/day)
• May also have IP-based rate limits

Response:

• Only returns fields specified in exposed_fields configuration
• Internal metadata is stripped from results
• Includes execution_id for interaction tracking
• Presigned URLs returned by default (return_presigned_urls=true) for media rendering

Example (no API key - recommended for public access):

curl -X POST "https://api.mixpeek.com/v1/public/retrievers/video-search/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query": "red car"},
    "pagination": {"method": "offset", "page_number": 1, "page_size": 10}
  }'

Example with ret_sk_ key (for SDK/programmatic access):

curl -X POST "https://api.mixpeek.com/v1/public/retrievers/video-search/execute" \
  -H "X-Public-API-Key: ret_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query": "red car"},
    "pagination": {"method": "offset", "page_number": 1, "page_size": 10}
  }'

POST /v1/public/retrievers/{public_name}/execute

Execute Public Retriever

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/public/retrievers/{public_name}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Simple query",
  "inputs": {
    "query": "artificial intelligence trends",
    "top_k": 25
  }
}
'

400

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "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 | null

X-Retriever-Password · string | null

Path Parameters

public_name · string · required

Public name of the published retriever

Query Parameters

return_presigned_urls · boolean · default: true

Generate fresh presigned download URLs for all blobs with S3 storage. Default: True for public retrievers to enable media rendering. Set to False if you only need metadata without URLs.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request payload for executing a retriever.

Executes a predefined retriever with runtime inputs. The retriever uses the collections it was created with - collection overrides are not supported at execution time to ensure feature_uri and schema validation integrity.

All filtering, pagination, and result shaping is handled by the individual stages based on the inputs provided.

Use Cases: - Execute retriever with its configured collections - Pass inputs that stages use to determine filtering/pagination behavior

Design Philosophy: - Retrievers are validated at creation time against their collections - Feature URIs, input schemas, and stage configs are tightly coupled to collections - 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

Examples: Simple query: {"inputs": {"query": "AI", "top_k": 50}}

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.

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

Template Syntax (Jinja2):

Namespaces (uppercase or lowercase):

• INPUT / input: Query inputs (e.g., {{INPUT.query}})
• DOC / doc: Document fields (e.g., {{DOC.payload.title}})
• CONTEXT / context: Execution context
• STAGE / stage: Stage configuration
• SECRET / secret: Vault secrets (e.g., {{SECRET.api_key}})

Accessing Data:

• Dot notation: {{DOC.payload.metadata.title}}
• Bracket notation: {{DOC.payload['special-key']}}
• Array index: {{DOC.items[0]}}, {{DOC.tags[2]}}
• Array first/last: {{DOC.items | first}}, {{DOC.items | last}}

Array Operations:

• Iterate: {% for item in DOC.tags %}{{item}}{% endfor %}
• Extract key: {{DOC.items | map(attribute='name') | list}}
• Join: {{DOC.tags | join(', ')}}
• Length: {{DOC.items | length}}
• Slice: {{DOC.items[:5]}}

Conditionals:

• If: {% if DOC.status == 'active' %}...{% endif %}
• If-else: {% if DOC.score > 0.8 %}high{% else %}low{% endif %}
• Ternary: {{'yes' if DOC.enabled else 'no'}}

Built-in Functions: max, min, abs, round, ceil, floor, utc_now, time_ago Time Functions: {{utc_now()}} returns current UTC as ISO-8601, {{time_ago(minutes=5)}} returns UTC minus duration Custom Filters: slugify (URL-safe), bool (truthy coercion), tojson (JSON encode), regex_search(pattern, group=0, ignore_case=false) (first match, or '')

S3 URLs: Internal S3 URLs (s3://bucket/key) are automatically presigned when accessed via DOC namespace.

Examples:

{
  "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
}

filters · Filters · object | null

Optional ad-hoc filters applied at execution time. Merged (AND) with any filters already defined in the retriever's stages. Uses the standard LogicalOperator format: {"AND": [{"field": "brand", "operator": "eq", "value": "Acme"}]}. Supports operators: eq, ne, in, nin, gt, gte, lt, lte, contains, exists, is_null.

Example:

{
  "AND": [
    {
      "field": "brand",
      "operator": "eq",
      "value": "Acme"
    }
  ]
}

pagination · OffsetPaginationParams · object

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}

OffsetPaginationParams

CursorPaginationParams

ScrollPaginationParams

KeysetPaginationParams

Show child attributes

limit · integer | null · deprecated

Shorthand for the pagination page size: the most documents this response returns. A top-level 'page_size' is accepted as the same value. Prefer 'pagination' (for example {"method": "cursor", "limit": 100}). When 'pagination' is absent, this value sizes the default cursor pagination of the final result set, and the response's pagination cursor fetches the next page. When both are sent and disagree, 'pagination' wins and a top-level response warning names the conflict. Sending 'limit' and 'page_size' with different values is refused.

Required range: 1 <= x <= 500

Example:

null

stream · boolean · default: false

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 uses text/event-stream content type
• Each stage completion emits a StreamStageEvent
• Events include: stage_start, stage_complete, stage_error, execution_complete
• Clients receive intermediate results and statistics as stages execute
• Useful for progress tracking, debugging, and partial result display

When stream=False (default):

• Response returns after all stages complete
• Returns a single RetrieverExecutionResponse with final results
• Lower overhead for simple queries

Use streaming when:

• You want to show real-time progress to users
• You need to display intermediate results
• Pipeline has many stages or long-running operations
• Debugging or monitoring pipeline performance

Example streaming client (JavaScript):

const eventSource = new EventSource('/v1/retrievers/ret_123/execute?stream=true');
eventSource.onmessage = (event) => {
  const stageEvent = JSON.parse(event.data);
  if (stageEvent.event_type === 'stage_complete') {
    console.log(`Stage ${stageEvent.stage_name} completed`);
    console.log(`Documents: ${stageEvent.documents.length}`);
  }
};

Example streaming client (Python):

import requests
response = requests.post('/v1/retrievers/ret_123/execute',
                        json={'inputs': {...}, 'stream': True},
                        stream=True)
for line in response.iter_lines():
    if line.startswith(b'data: '):
        event = json.loads(line[6:])
        print(f"Stage {event['stage_name']}: {event['event_type']}")

Examples:

false

true

expand · string[] | null

OPTIONAL. List of fields containing document IDs to resolve inline. Referenced documents are fetched and attached under an '_expanded' key in each result document. Supports dot-notation for nested fields (e.g., 'items.product_id'). Max 50 unique references per request. Depth is limited to 1 (no recursive expansion).

Example:

["customer_id"]

skip_cache · boolean · default: false

OPTIONAL. Bypass stage result cache for this execution. When True, all stages execute fresh without cache lookup. Useful after corpus updates, retriever config changes, or engine deploys. Results are still written to cache for future requests.

Examples:

false

true

return_presigned_urls · boolean · default: false

Generate presigned URLs for S3-backed blobs and url-shaped fields in result documents. Also accepted as a return_presigned_urls query parameter; if either source is true, presigning is enabled.

Examples:

false

true

return_vectors · boolean · default: false

Include vector embeddings in result documents. Also accepted as a return_vectors query parameter; if either source is true, vectors are returned.

Examples:

false

true

write_token · string | null

OPTIONAL. Pass the write_token returned by a prior direct upsert (options.write_token=true) to get read-your-writes consistency: the read is routed to the primary shard, where your just-written document is immediately searchable, instead of an eventually-consistent replica that can lag several seconds behind. Omit for normal (eventual) reads.

consistency · ReadConsistencyOption · object | null

OPTIONAL. The read consistency for this execution. Omit to use the deployment default. A write_token always reads strong.

Show child attributes

Response

200

application/json

Successful Response