Skip to Content

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:

  1. Vector similarity search using text 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

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.

POST
/search/file

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

  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."
  }
}

API reference

Authorization

ApiKeyAuth
headerX-API-Key<token>

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

Request Body

application/json
  1. body
query*string

Search query

namespace_ids?array<string>

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

include_usage?boolean

When true, the response includes the usage block of this request.

Defaultfalse

Response Body

Search completed successfully

application/json
  1. response
status?"success"
Value in"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.

Example Request
curl -X POST 'https://api.vidnavigator.com/v1/search/file' \  -H 'Content-Type: application/json' \  -d '{  "query": "What did the customer say about pricing?"}'
Example Response
{  "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    }  }}

On this page