Search Files
Search through user’s uploaded files using vector similarity with AI reranking.
Namespace filtering: Pass namespace_ids to restrict the search to files in specific namespaces. If omitted, all namespaces are searched.
Process:
- Vector similarity search using text embeddings
- Initial ranking by semantic similarity
- AI reranking for improved relevance
- Rich metadata and signed URLs for file access
- Optional per-file AI analysis for people, places, key subjects, and key moments
Each result includes the namespace_ids and resolved namespaces the file belongs to.
Billing: one search_request per call. The AI analysis pass (per-file + overall aggregation) bills analysis_request as ceil(total_tokens / 15000) units (minimum 1 when analysis ran). Set include_usage=true to receive the per-charge breakdown — the consolidated analysis_request entry carries a nested tokens object.
Overview
This endpoint searches through your uploaded file library using OpenAI embeddings for semantic similarity, followed by AI reranking for improved relevance. Results include rich metadata, signed URLs, and optional per-file analysis.Billing
File search consumes onesearch_request per call. If the AI analysis pass runs (per-file + overall aggregation), it also bills analysis_request as ceil(total_tokens / 15000) units (minimum 1 when analysis ran).
Set include_usage: true to receive a usage block with the per-charge breakdown — the consolidated analysis_request entry carries a nested tokens object.
Search Process
- Vector similarity search using OpenAI embeddings
- Initial ranking by semantic similarity
- AI reranking for improved relevance
- Rich metadata and signed URLs for file access
- Optional per-file AI analysis for people, places, key subjects, and key moments
Request Body
Example Request
Success Response
Authorizations
API key authentication. Include your VidNavigator API key in the X-API-Key header.
Body
Search query
"What did the customer say about pricing?"
Optional list of namespace IDs to restrict search scope. If not provided, all namespaces are searched.
When true, the response includes a usage block listing every meter charged during this request, the total credits deducted, and the user's remaining balance.
Response
Search completed successfully
success Per-call usage disclosure. Returned only when the caller passes include_usage=true in the request body. Lists every meter that fired during this request and the credits actually deducted. Multiple charges of the same meter inside one request are consolidated into a single entry (their quantities and credits are summed). When a charge was waived through a cache-hit sponsorship (e.g. NGO), it carries waived: true + credits_saved, and a top-level waived.credits_saved summary appears.
For endpoints that involve LLM analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the consolidated analysis_request charge entry carries a nested tokens object reporting the LLM input/output token tally for the request.

