API Reference
Search API Reference
Complete reference for the /v1/search endpoint. Learn about request parameters, filters, and response fields for both b-roll and knowledge searches.
Guide
API Reference
Built to be operator-readable before you wire in automation.
Read time
8 min read
Quick enough for onboarding, specific enough for implementation.
Focus
Practical API use
Examples, request shape, and the minimum context needed to ship.
01
Endpoint
The search endpoint accepts POST requests with a JSON body containing your search parameters.
POST https://api.cerul.ai/v1/search
Content-Type: application/json
Authorization: Bearer YOUR_CERUL_API_KEY02
Request parameters
All search requests share a common structure. The search_type parameter determines which retrieval system to use.
{
"query": string, // Required: Search query
"search_type": string, // Required: "broll" or "knowledge"
"max_results": number, // Optional: 1-50 (default: 10)
"include_answer": boolean, // Optional: AI summary (default: false)
"filters": { // Optional: Track-specific filters
"min_duration": number,
"max_duration": number,
"source": string
}
}03
B-roll search example
Search for stock footage and b-roll content. Results include direct video URLs from sources like Pexels and Pixabay.
curl "https://api.cerul.ai/v1/search" \
-H "Authorization: Bearer YOUR_CERUL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "business handshake in modern office",
"search_type": "broll",
"max_results": 5,
"filters": {
"min_duration": 3,
"max_duration": 15
}
}'04
Knowledge search example
Search educational and informational video content. Results include timestamps and optional AI-generated answers.
curl "https://api.cerul.ai/v1/search" \
-H "Authorization: Bearer YOUR_CERUL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "sam altman explains the agi timeline",
"search_type": "knowledge",
"max_results": 5,
"include_answer": true,
"filters": {
"speaker": "Sam Altman",
"published_after": "2023-01-01"
}
}'05
Response fields
The response contains an array of results, each with standardized fields and track-specific metadata.
{
"results": [{
"id": string, // Unique result identifier
"score": number, // Relevance score (0.0-1.0)
"title": string, // Video title
"description": string, // Video description
"video_url": string, // Direct MP4 URL
"thumbnail_url": string,// Preview image
"duration": number, // Length in seconds
"source": string, // Content source
// B-roll specific:
"license": string, // Usage license
// Knowledge specific:
"timestamp_start": number,
"timestamp_end": number,
"answer": string // If include_answer: true
}],
"credits_used": number,
"credits_remaining": number,
"request_id": string
}