curl --request POST \
--url https://api.vidnavigator.com/v1/search/file \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "What did the customer say about pricing?",
"namespace_ids": [
"<string>"
],
"include_usage": false
}
'import requests
url = "https://api.vidnavigator.com/v1/search/file"
payload = {
"query": "What did the customer say about pricing?",
"namespace_ids": ["<string>"],
"include_usage": False
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What did the customer say about pricing?',
namespace_ids: ['<string>'],
include_usage: false
})
};
fetch('https://api.vidnavigator.com/v1/search/file', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vidnavigator.com/v1/search/file",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What did the customer say about pricing?',
'namespace_ids' => [
'<string>'
],
'include_usage' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vidnavigator.com/v1/search/file"
payload := strings.NewReader("{\n \"query\": \"What did the customer say about pricing?\",\n \"namespace_ids\": [\n \"<string>\"\n ],\n \"include_usage\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/search/file")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What did the customer say about pricing?\",\n \"namespace_ids\": [\n \"<string>\"\n ],\n \"include_usage\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vidnavigator.com/v1/search/file")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What did the customer say about pricing?\",\n \"namespace_ids\": [\n \"<string>\"\n ],\n \"include_usage\": false\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"results": [
{
"id": "<string>",
"name": "<string>",
"duration": 123,
"size": 123,
"type": "<string>",
"status": "completed",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"original_file_date": "2023-11-07T05:31:56Z",
"file_url": "https://storage.googleapis.com/bucket/path/to/file?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Signature=...",
"namespace_ids": [
"<string>"
],
"namespaces": [
{
"id": "<string>",
"name": "<string>"
}
],
"relevance_score": 123,
"timestamps": [
123
],
"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": 123,
"explanation": "<string>"
},
"usage": {
"charges": [
{
"service_type": "standard_request",
"quantity": 123,
"credits": 123,
"waived": true,
"credits_saved": 123,
"tokens": {
"prompt_tokens": 123,
"completion_tokens": 123,
"total_tokens": 123
}
}
],
"total_credits": 123,
"waived": {
"credits_saved": 123
}
}
}{
"status": "error",
"error": "<string>",
"message": "<string>"
}{
"status": "error",
"error": "limit_exceeded",
"message": "<string>"
}{
"status": "error",
"error": "metadata_fetch_failed",
"message": "<string>"
}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.
curl --request POST \
--url https://api.vidnavigator.com/v1/search/file \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "What did the customer say about pricing?",
"namespace_ids": [
"<string>"
],
"include_usage": false
}
'import requests
url = "https://api.vidnavigator.com/v1/search/file"
payload = {
"query": "What did the customer say about pricing?",
"namespace_ids": ["<string>"],
"include_usage": False
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'What did the customer say about pricing?',
namespace_ids: ['<string>'],
include_usage: false
})
};
fetch('https://api.vidnavigator.com/v1/search/file', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vidnavigator.com/v1/search/file",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'What did the customer say about pricing?',
'namespace_ids' => [
'<string>'
],
'include_usage' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vidnavigator.com/v1/search/file"
payload := strings.NewReader("{\n \"query\": \"What did the customer say about pricing?\",\n \"namespace_ids\": [\n \"<string>\"\n ],\n \"include_usage\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/search/file")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"What did the customer say about pricing?\",\n \"namespace_ids\": [\n \"<string>\"\n ],\n \"include_usage\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vidnavigator.com/v1/search/file")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"What did the customer say about pricing?\",\n \"namespace_ids\": [\n \"<string>\"\n ],\n \"include_usage\": false\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"results": [
{
"id": "<string>",
"name": "<string>",
"duration": 123,
"size": 123,
"type": "<string>",
"status": "completed",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"original_file_date": "2023-11-07T05:31:56Z",
"file_url": "https://storage.googleapis.com/bucket/path/to/file?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Signature=...",
"namespace_ids": [
"<string>"
],
"namespaces": [
{
"id": "<string>",
"name": "<string>"
}
],
"relevance_score": 123,
"timestamps": [
123
],
"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": 123,
"explanation": "<string>"
},
"usage": {
"charges": [
{
"service_type": "standard_request",
"quantity": 123,
"credits": 123,
"waived": true,
"credits_saved": 123,
"tokens": {
"prompt_tokens": 123,
"completion_tokens": 123,
"total_tokens": 123
}
}
],
"total_credits": 123,
"waived": {
"credits_saved": 123
}
}
}{
"status": "error",
"error": "<string>",
"message": "<string>"
}{
"status": "error",
"error": "limit_exceeded",
"message": "<string>"
}{
"status": "error",
"error": "metadata_fetch_failed",
"message": "<string>"
}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 onesearch_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?"
}'
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?",
"namespace_ids": ["64a1b2c3d4e5f6789abc0002"]
}'
import requests
url = "https://api.vidnavigator.com/v1/search/file"
headers = {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"query": "What did the customer say about pricing?",
"namespace_ids": ["64a1b2c3d4e5f6789abc0002"]
}
response = requests.post(url, headers=headers, json=data)
results = response.json()
const response = await fetch('https://api.vidnavigator.com/v1/search/file', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'What did the customer say about pricing?',
namespace_ids: ['64a1b2c3d4e5f6789abc0002']
})
});
const results = await response.json();
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."
}
}
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 Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes

