API · v1.
Score videos, search the index, and stream events programmatically. Every endpoint returns the same data shapes the app uses. Agency tier only — 10K calls/mo included, $0.002/call beyond.
Overview
Base URL: https://api.viralvault.studio. All requests are JSON-in / JSON-out. Authenticate with a bearer token (generate one at /account/api). All scores are returned on the index scale where 100 = niche median.
Authentication
curl https://api.viralvault.studio/v1/score \ -X POST \ -H "Authorization: Bearer vv_live_7f3a…" \ -H "Content-Type: application/json" \ -d '{"url": "https://tiktok.com/@maya/video/74938201"}'
Rate limits
60 requests per minute per token, burstable to 120 over short windows. X-RateLimit-Remaining headers tell you what's left. Hitting the limit returns HTTP 429 with a Retry-After header.
POST · /v1/score
Score a single TikTok by URL or ID. Returns Creator Score, Niche Score, dual_high flag, and the video metadata.
// Response { "video_id": "v_7f3a9e2c", "creator_score": 742, "niche_score": 521, "dual_high": true, "tier": "viral", "format": "controversial-reframe", "creator": { "handle": "maya", "followers": 184000 }, "computed_at": "2026-05-22T14:18:00Z" }
GET · /v1/videos/{id}
Fetch the full record (scores + metadata + format ascription) for a previously-scored video.
GET · /v1/search
Paginated search over the index. Filter by niche, min/max score, days, format, hook type, dual_high.
GET · /v1/trending
Top outliers + niche heat list, per window (24h, 7d, 30d).
GET · /v1/formats
List Format clusters in a niche, optionally filtered by state (rising / peaking / saturated).
Webhooks
Subscribe to video.scored, format.inflected, watchlist.dual_high. Signatures via HMAC-SHA256 in the X-VV-Signature header.
// Sample event payload { "event": "watchlist.dual_high", "creator_handle": "maya", "video_id": "v_7f3a9e2c", "creator_score": 742, "niche_score": 521, "detected_at": "2026-05-22T14:18:00Z" }