> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Videos
> Search for videos using AI analysis and ranking with optional filters.
**Process:**
1. Enhanced search with prompt engineering to find relevant videos
2. AI analysis of video content and transcripts
3. Intelligent ranking based on query relevance
4. Structured results with rich metadata
Search for videos using AI-powered semantic search with intelligent ranking and filtering.
## Overview
Find the most relevant videos using natural language queries. Our AI analyzes video content, transcripts, and metadata to deliver precisely ranked results.
## Billing
Video search consumes `search_request` usage. 1 credit covers 10 searches across YouTube or your own uploaded files.
### Search Process
1. **Enhanced Query Processing**: AI expands and optimizes your search query
2. **Content Analysis**: Deep analysis of video transcripts and metadata
3. **Intelligent Ranking**: Results ranked by relevance, not just keyword matching
4. **Rich Results**: Detailed video information with explanations
### Search Options
AI-powered query expansion and optimization (recommended)
Filter results by publication date range
Limit results by maximum video duration
Prioritize relevance, popularity, or brevity
## Example Usage
```bash cURL theme={null}
curl -X POST "https://api.vidnavigator.com/v1/search/video" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What are the best practices for React development?",
"use_enhanced_search": true,
"start_year": 2020,
"end_year": 2024,
"focus": "relevance",
"duration": 1800
}'
```
```python Python theme={null}
import requests
url = "https://api.vidnavigator.com/v1/search/video"
headers = {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"query": "What are the best practices for React development?",
"use_enhanced_search": True,
"start_year": 2020,
"end_year": 2024,
"focus": "relevance",
"duration": 1800
}
response = requests.post(url, headers=headers, json=data)
results = response.json()
for video in results['data']['results']:
print(f"Title: {video['title']}")
print(f"Relevance Score: {video['relevance_score']}")
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.vidnavigator.com/v1/search/video', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'What are the best practices for React development?',
use_enhanced_search: true,
start_year: 2020,
end_year: 2024,
focus: 'relevance',
duration: 1800
})
});
const results = await response.json();
```
## Response Example
```json theme={null}
{
"status": "success",
"data": {
"results": [
{
"title": "React Best Practices 2024: Clean Code & Performance",
"description": "Complete guide to writing maintainable React code...",
"url": "https://youtube.com/watch?v=example123",
"thumbnail": "https://img.youtube.com/vi/example123/maxresdefault.jpg",
"channel": "React Mastery",
"duration": "15:30",
"views": 125000,
"published_date": "2024-01-15",
"relevance_score": 0.95,
"explanation": "This video directly addresses React best practices with focus on clean code and performance optimization.",
"key_topics": ["React hooks", "Performance optimization", "Code organization"]
}
],
"query": "What are the best practices for React development?",
"total_found": 1,
"explanation": "Found videos discussing React development best practices, focusing on recent content and high relevance."
}
}
```
## Use Cases
Find educational content on specific topics or technologies
Build curated lists of videos for courses or documentation
Analyze what content exists in your industry or niche
Identify trending topics and popular content creators
## OpenAPI
````yaml POST /search/video
openapi: 3.0.3
info:
title: VidNavigator Developer API
description: >-
The VidNavigator Developer API provides programmatic access to video
analysis, transcription, and search capabilities.
## Authentication
All endpoints require API key authentication via the `X-API-Key` header:
```
X-API-Key: YOUR_API_KEY
```
## Rate Limits
Check the documentation for the rate limits for each endpoint.
## Error Handling
The API uses standard HTTP status codes and returns error responses in JSON
format:
```json
{
"status": "error",
"error": "error_type",
"message": "Human readable error message"
}
```
version: 1.0.0
contact:
name: VidNavigator Support
url: https://vidnavigator.com/support
email: support@vidnavigator.com
license:
name: Proprietary
url: https://vidnavigator.com/terms
servers:
- url: https://api.vidnavigator.com/v1
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Transcripts
description: Extract transcripts from online videos
- name: TikTok
description: Scrape TikTok profile metadata and per-video stats
- name: Files
description: Manage uploaded audio/video files
- name: Analysis
description: AI-powered content analysis
- name: Extraction
description: >-
Extract structured data from video and file transcripts using custom
schemas
- name: Namespaces
description: Organize uploaded files into namespaces (folders)
- name: Search
description: Search videos and files using AI
- name: System
description: System health and information
- name: Tweet Analysis
description: Extract structured claims and metadata from X/Twitter tweets
paths:
/search/video:
post:
tags:
- Search
summary: Search for videos
description: |-
Search for videos using AI analysis and ranking with optional filters.
**Process:**
1. Enhanced search with prompt engineering to find relevant videos
2. AI analysis of video content and transcripts
3. Intelligent ranking based on query relevance
4. Structured results with rich metadata
operationId: searchVideos
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
description: Search query
example: What are the best practices for React development?
use_enhanced_search:
type: boolean
default: true
description: Whether to use enhanced search
start_year:
type: integer
description: Filter by start year
example: 2020
end_year:
type: integer
description: Filter by end year
example: 2024
focus:
type: string
enum:
- relevance
- popularity
- brevity
default: relevance
description: Search focus
duration:
type: integer
description: Maximum duration in seconds
example: 600
responses:
'200':
description: Search completed successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
data:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/VideoSearchResult'
query:
type: string
total_found:
type: integer
explanation:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/PaymentRequired'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
VideoSearchResult:
type: object
properties:
title:
type: string
url:
type: string
format: uri
description:
type: string
thumbnail:
type: string
format: uri
channel:
type: string
published_date:
type: string
description: Publication date
duration:
type: number
description: Duration in seconds
views:
type: integer
likes:
type: integer
relevance_score:
type: number
description: AI relevance score (0-1)
transcript_summary:
type: string
people:
type: array
items:
type: object
properties:
name:
type: string
context:
type: string
places:
type: array
items:
type: object
properties:
name:
type: string
context:
type: string
key_subjects:
type: array
items:
type: object
properties:
name:
type: string
description:
type: string
timestamp:
type: number
relevant_text:
type: string
query_relevance:
type: string
responses:
BadRequest:
description: Bad request - invalid parameters
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
message:
type: string
PaymentRequired:
description: Usage limit exceeded - upgrade required
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- limit_exceeded
message:
type: string
InternalServerError:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- internal_server_error
message:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key authentication. Include your VidNavigator API key in the
X-API-Key header.
````