Skip to main content
POST
/
v1
/
retrievers
/
{retriever_id}
/
execute
Execute Retriever (Auto-Optimized)
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {},
  "pagination": {
    "method": "offset",
    "page_size": 10,
    "page_number": 1
  },
  "stream": false
}
'
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  },
  "success": false
}

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

​
X-Namespace
string

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'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
retriever_id
string
required

Retriever ID or name. Pipeline will be automatically optimized before execution.

Query Parameters

​
return_presigned_urls
boolean
default:false
​
return_vectors
boolean
default:false

Body

application/json

Execution request with inputs, filters, pagination, and optional stream parameter. Set stream=true to receive real-time stage updates via Server-Sent Events.

​
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 Custom Filters: slugify (URL-safe), bool (truthy coercion), tojson (JSON encode)

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
}
​
pagination
OffsetPaginationParams · object

Offset-based pagination using page number sizing.

​
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

Response

Execution results with documents, pagination, statistics, and optimization details. When stream=true, returns Server-Sent Events. When stream=false, returns JSON response.