Skip to Content

API Reference

Complete reference for the VidNavigator Developer API

Welcome to VidNavigator API

The VidNavigator Developer API provides transcription, analysis, and structured data extraction across YouTube, TikTok, Instagram, X/Twitter, Facebook, Vimeo, Loom, Dailymotion, Snapchat, and uploaded files. It also supports global YouTube and TikTok discovery (TikTok videos by keyword and TikTok LIVE rooms broadcasting now) plus semantic search over indexed YouTube channel content and uploaded files.

OpenAPI Specification

View the complete OpenAPI 3.0 specification

Get Started

Quick start guide for making your first API call

Authentication

All API endpoints require authentication using an API key passed in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Get your API key from the VidNavigator Developer Dashboard.

Base URL

The API is available at:

https://api.vidnavigator.com/v1

Long Videos and Async Jobs

The speech-to-text endpoints run for as long as the media is long, so each one has an async twin. Synchronous calls are limited to 10 minutes of media and reject longer media with 400 video_too_long; the async endpoints have no duration cap and work for short videos too.

Synchronous (≤ 10 min)Async (any length)
POST /transcribePOST /transcribe/async → GET /transcribe/{task_id}
POST /watchPOST /watch/async → GET /watch/{task_id}
POST /extract/videoPOST /extract/video/async → GET /extract/video/{task_id}
POST /tweet/statementPOST /tweet/statement/async → GET /tweet/statement/{task_id}

The async endpoint returns 202 with a task_id immediately. Poll the check_status_url (free), or get called back through a webhook — set a default endpoint in Studio → API or pass webhook_url per request.

Async Jobs

Submit, poll and migrate from synchronous calls

Webhooks

Payload, signature verification and retries

Error Handling

The API uses standard HTTP status codes and returns structured error responses:

{
  "status": "error",
  "error": "error_type",
  "message": "Human readable error message",
  "docs_url": "https://docs.vidnavigator.com/..."
}

Actionable errors also carry a docs_url pointing to the page that explains how to fix them. See Errors for every error code.

Common Error Codes

Status CodeError TypeDescription
400missing_parameter, invalid_parameter, …Invalid request parameters
400video_too_longMedia longer than 10 minutes sent to a synchronous endpoint — use the async endpoint
401—Missing or invalid API key
402limit_exceededCredit limit exceeded or no active subscription
403access_deniedInsufficient permissions
404video_not_found, task_not_found, …Resource not found
429rate_limit_exceeded, too_many_active_jobsRate limit exceeded, or too many async jobs running
500internal_server_errorServer error

API Categories

Transcripts

Extract transcripts from YouTube, TikTok, Instagram, X/Twitter, Facebook, Vimeo, Loom, Snapchat, and more

File Management

Upload, manage, and organize audio/video files with namespaces

AI Analysis

Analyze video content with AI for insights and summaries

Data Extraction

Extract structured data from transcripts using custom schemas

Video Search

Discover videos with global YouTube and TikTok search, and TikTok LIVE rooms broadcasting now

Semantic Search

Search indexed YouTube channel content and uploaded files using vector similarity

On this page