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.
Set include_usage=true to receive the usage block, with the request's token counts.
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 is a semantic (vector) search over already indexed content and consumes one search_request per call. 1 credit covers 1,000 semantic searches. 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
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query |
namespace_ids | string[] | No | Restrict search to specific namespaces. If omitted, searches all files. |
Example Request
curl -X POST "https://api.vidnavigator.com/v1/search/file" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What did the customer say about pricing?"
}'Success Response
{
"status": "success",
"data": {
"results": [
{
"id": "file_abc123",
"name": "client-call-march.mp4",
"duration": 1800,
"size": 52428800,
"type": "video/mp4",
"status": "completed",
"created_at": "2026-03-10T14:00:00Z",
"file_url": "https://storage.example.com/signed-url...",
"namespace_ids": ["64a1b2c3d4e5f6789abc0002"],
"namespaces": [
{ "id": "64a1b2c3d4e5f6789abc0002", "name": "Client Calls" }
],
"relevance_score": 0.92,
"timestamps": [245.5, 890.2],
"relevant_text": "The customer mentioned the pricing was competitive but wished for a monthly option.",
"query_answer": "The customer found pricing competitive but requested monthly billing.",
"transcript_summary": "A 30-minute client call discussing product features, pricing, and onboarding timeline.",
"people": [
{ "name": "John Smith", "context": "Client representative" }
],
"key_subjects": [
{ "name": "Pricing", "description": "Discussion about pricing tiers and billing options" }
]
}
],
"query": "What did the customer say about pricing?",
"total_found": 1,
"explanation": "Found 1 file matching your query about customer pricing feedback."
}
}API reference
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
application/json- body
query*stringSearch query
namespace_ids?array<string>Optional list of namespace IDs to restrict search scope. If not provided, all namespaces are searched.
include_usage?booleanWhen true, the response includes the usage block of this request.
falseSearch completed successfully
application/json- response
status?"success""success"data?usage?Per-call usage, returned only when the request sets include_usage=true: the charges of this request, one entry per service_type, and the total credits deducted. A waived charge carries waived: true and credits_saved, with a top-level waived.credits_saved summary.
For endpoints that run an AI analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the analysis_request entry carries a nested tokens object with the request's token counts.
curl -X POST 'https://api.vidnavigator.com/v1/search/file' \ -H 'Content-Type: application/json' \ -d '{ "query": "What did the customer say about pricing?"}'{ "status": "success", "data": { "results": [ { "id": "string", "name": "string", "duration": 0, "size": 0, "type": "string", "status": "completed", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "original_file_date": "2019-08-24T14:15:22Z", "file_url": "https://storage.example.com/path/to/file?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=...", "namespace_ids": [ "string" ], "namespaces": [ { "id": "string", "name": "string" } ], "relevance_score": 0, "timestamps": [ 0 ], "relevant_text": "string", "query_answer": "string", "transcript_summary": "string", "people": [ { "name": "string", "context": "string" } ], "places": [ { "name": "string", "context": "string" } ], "key_subjects": [ { "name": "string", "description": "string" } ] } ], "query": "string", "total_found": 0, "explanation": "string" }, "usage": { "charges": [ { "service_type": "standard_request", "quantity": 0, "credits": 0, "waived": true, "credits_saved": 0, "tokens": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 } } ], "total_credits": 0, "waived": { "credits_saved": 0 } }}