Skip to main content
POST
/
search
/
file
Search uploaded files
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>"
  ]
}
'
{
  "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>"
  }
}
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 search_request usage. 1 credit covers 10 searches across YouTube or your own uploaded files.

​
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

ParameterTypeRequiredDescription
querystringYesSearch query
namespace_idsstring[]NoRestrict 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."
  }
}

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.

Response

Search completed successfully

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