Skip to main content
POST
Search uploaded files
Search your uploaded files using vector similarity and AI reranking.

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 one search_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

  1. Vector similarity search using OpenAI embeddings
  2. Initial ranking by semantic similarity
  3. AI reranking for improved relevance
  4. Rich metadata and signed URLs for file access
  5. Optional per-file AI analysis for people, places, key subjects, and key moments

Request Body

Example Request

Success Response

Authorizations

X-API-Key
string
header
required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json
query
string
required

Search query

Example:

"What did the customer say about pricing?"

namespace_ids
string[]

Optional list of namespace IDs to restrict search scope. If not provided, all namespaces are searched.

include_usage
boolean
default:false

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

status
enum<string>
Available options:
success
data
object
usage
object

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.