Search documentation
Search pages, API reference sections, and guide headings.
Summary
The search API combines semantic retrieval, exact metadata filtering, cross-run search, playground search, and analyst-style SQL execution on run-backed tables.
Semantic search endpoints
VideoVector search combines vector-style semantic retrieval with structured metadata filters. Use the same index and prompt-run outputs for video vector embedding search, hybrid vector and metadata search, SQL media search, and agentic media search through chat sessions.
| Method | Path | Purpose |
|---|---|---|
POST | /api/v2/indexes/{index_id}/search | Text search |
POST | /api/v2/indexes/{index_id}/image-search | Image similarity search |
POST | /api/v2/indexes/{index_id}/multimodal-search | Combined text and image search |
POST | /api/v2/search/multi-run | Search across several runs |
POST | /api/v2/playground/search | Search playground media |
Filter search endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /api/v2/search/filter/{index_id} | Filter completed run results in an index |
POST | /api/v2/search/filter/playground | Filter completed run results in playground media |
SQL search endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /api/v2/search/sql/{index_id}/catalog | Discover queryable tables and limits |
POST | /api/v2/search/sql/{index_id} | Execute SQL |
POST | /api/v2/search/sql/{index_id}/generate | Generate a draft query from instructions |
Example: multimodal search
curl -X POST /api/v2/indexes/idx_archive/multimodal-search \
-H "X-API-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"text_query": "red emergency vehicle",
"image_data": "<base64-image>",
"text_weight": 0.7,
"image_weight": 0.3,
"top_k": 20,
"run_ids": ["run_123"]
}'
Filter condition contract
Filter requests use a list of conditions. Each condition includes:
| Field | Purpose |
|---|---|
field | Canonical metadata leaf path such as scene.people[].emotion |
operator | Comparison operator allowed for the field type |
value | Value to compare against |
type | Field type used for operator validation |
The API combines conditions with AND semantics.
Example: filter by nested fields
curl -X POST /api/v2/search/filter/idx_archive \
-H "X-API-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"run_ids": ["run_123"],
"conditions": [
{
"field": "scene.people[].emotion",
"operator": "equals",
"value": "happy",
"type": "string"
}
],
"page_size": 50
}'
SQL search behavior
The SQL catalog response documents:
- queryable tables
- table-to-index and table-to-run mapping
- field-path columns
- default query scaffolding
- public query limits
POST /api/v2/search/sql/{index_id} accepts:
query- optional
run_ids - optional
index_ids - optional
result_limit
POST /api/v2/search/sql/{index_id}/generate accepts:
instruction- optional
existing_query - optional
run_ids - optional
index_ids
Example: SQL query generation
curl -X POST /api/v2/search/sql/idx_archive/generate \
-H "X-API-Key: sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"instruction": "Show the top 20 scenes where scene.people[].emotion is happy.",
"run_ids": ["run_123"]
}'
SDK equivalents
client.search.textclient.search.imageclient.search.multimodalclient.search.filterclient.search.filter_playgroundclient.search.multi_runclient.search.playground
Chat sessions build on the same retrieval model. Use Chat sessions when the client needs conversational retrieval rather than direct search requests.
Related documentation
Search in VideoVector is built around segment-level prompt output, indexed media context, and scoped conversational retrieval. This page explains the major search modes and the field-path conventions they rely on.
This guide shows how to choose the right public search mode for retrieval, filtering, comparison, conversational review, and analyst-style queries.
Chat sessions provide an agentic retrieval surface on top of search results and prompt-run scope. The API supports session CRUD, turn creation, optional scope narrowing, and streaming turn events over SSE for agent-search experiences.