For Developers
Developer API
Integrate reverse video search into your own product. Find every copy of a video across 50+ platforms — programmatically, with a single HTTP call.
Getting started
- The API is available on every premium plan — searches consume your plan's credits at the same rates as dashboard searches.
- Generate your token in Dashboard → Account → Developer API. It is shown once — store it securely.
- Pass the token on every request: Authorization: Bearer rvs_…
- Rate limits are per token, not per IP — 30/min on
/search, 120/min on/jobs, 60/min on/account. A429includesretry_afterplus the standardRetry-AfterandX-RateLimit-*headers. - Always send Accept: application/json so errors come back as JSON rather than HTML.
Search modes
All five modes the web app offers are available over the API. Text modes take a JSON body; file modes take multipart/form-data.
| Mode | Sends | What it does |
|---|---|---|
| upload | video_file | Analyse a video file you hold — the most accurate mode. Large files are queued automatically. |
| screenshot | screenshot_files[] | Trace 1–5 still frames back to their source video. |
| url | query | Analyse a public video URL (YouTube, TikTok, Instagram, X/Twitter, Facebook…). |
| keyword | query | Find videos matching a text query. |
| transcript | query | Find the video a spoken excerpt came from. |
POST/api/v1/search
Synchronous for text modes, screenshots, and videos under the async threshold — expect 20–90 seconds. Videos above the threshold return 202 immediately with a job to poll.
Request — text modes (keyword / url / transcript)
| Field | Type | Description |
|---|---|---|
| mode | string, required | keyword, url, or transcript |
| query | string, required | Keyword (3–200), public video URL (valid http/https, ≤2048), or transcript excerpt (10–5000) |
| platform | string, optional | all (default), youtube, tiktok, vimeo, facebook, twitter, instagram |
curl -X POST https://rvlstaging.reverse-videosearch.com/api/v1/search \
-H "Authorization: Bearer rvs_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"mode":"url","query":"https://www.tiktok.com/@user/video/123"}'
Request — video upload (mode=upload)
| Field | Type | Description |
|---|---|---|
| mode | string, required | upload |
| video_file | file, required | MP4, MOV, AVI, MKV, WebM or MPEG. Size cap comes from your plan — read it from /api/v1/account. |
curl -X POST https://rvlstaging.reverse-videosearch.com/api/v1/search \
-H "Authorization: Bearer rvs_YOUR_TOKEN" \
-H "Accept: application/json" \
-F "mode=upload" \
-F "video_file=@/path/to/clip.mp4"
Large files. Anything over your account's async_threshold_mb is accepted for background processing and returns 202:
{
"status": "queued",
"job_uuid": "9f1c…",
"status_url": "https://rvlstaging.reverse-videosearch.com/api/v1/jobs/9f1c…",
"file_size_mb": 182.4,
"estimated_credits": 14
}
Poll status_url until is_final is true. Credits for a queued job are charged when the job finishes, not when it is accepted.
Request — screenshots (mode=screenshot)
| Field | Type | Description |
|---|---|---|
| mode | string, required | screenshot |
| screenshot_files[] | file[], required | 1–5 images (JPG, PNG, WebP, GIF, BMP). Analysed concurrently; results are merged and de-duplicated. |
curl -X POST https://rvlstaging.reverse-videosearch.com/api/v1/search \
-H "Authorization: Bearer rvs_YOUR_TOKEN" \
-H "Accept: application/json" \
-F "mode=screenshot" \
-F "screenshot_files[]=@frame1.jpg" \
-F "screenshot_files[]=@frame2.png"
Response
{
"status": "success",
"mode": "url",
"results": [
{
"titles": ["Example repost title"],
"link": "https://www.youtube.com/watch?v=...",
"platform": "youtube",
"channel": "Some Channel",
"first_seen": "20240311",
"similarity_score": 0.92,
"match_type": "exact",
"found_at_seconds": 42.0,
"audio_match": true,
"is_ai_generated": false
}
],
"total_frames": 12,
"credits_charged": 24,
"time_taken": "38.2 s"
}
Credit costs
| Mode | Cost |
|---|---|
| keyword | 2 credits |
| transcript | 3 credits |
| screenshot | 2 credits per image (10 for the max of 5) |
| url / upload | 2 credits per analysed frame — min 6, max 16 |
Nothing is charged when a search fails: credits are deducted only after results are returned. Queued uploads are billed when the job completes (a failed job costs 1 credit).
Error codes
| Status | Meaning |
|---|---|
| 202 | Large upload accepted — poll status_url |
| 401 | Missing, malformed, revoked or invalid token |
| 402 | Insufficient credits |
| 403 | No active premium plan |
| 404 | Job not found (or not yours) |
| 405 | Wrong HTTP method for the endpoint |
| 413 | Body exceeded the server's upload limit before it reached the app |
| 422 | Validation error — bad mode, query, file type or size; or a video that could not be decoded (do not retry these) |
| 429 | Rate limit exceeded — see retry_after |
| 502 | Search engine temporarily unavailable — safe to retry |
GET/api/v1/jobs/{uuid}
Status of a queued upload. While running, the response carries progress fields only; once job_status is completed the full result set is included inline.
curl https://rvlstaging.reverse-videosearch.com/api/v1/jobs/9f1c… \
-H "Authorization: Bearer rvs_YOUR_TOKEN" \
-H "Accept: application/json"
{
"status": "success",
"job_uuid": "9f1c…",
"job_status": "completed", // pending | processing | completed | failed | cancelled
"is_final": true, // stop polling when true
"poll_after_seconds": null, // suggested wait while still running
"credits_used": 14,
"total_frames": 7,
"results": [ /* same shape as a sync search */ ],
"original_source": { … }
}
GET/api/v1/jobs lists your recent jobs (?limit=, default 25, max 100).
GET/api/v1/account
Plan, credit balance and the exact limits that apply to your token. Read this before sending a large file rather than discovering a limit mid-upload.
{
"plan": { "name": "Standard", "is_unlimited": false, "renews_at": "2026-08-29T…" },
"credits": { "used": 120, "limit": 600, "remaining": 480, "period": "monthly" },
"limits": {
"upload_max_mb": 500, // null = unlimited on your plan
"screenshot_max_mb_each": 500,
"screenshot_max_files": 5,
"async_threshold_mb": 50, // above this, uploads are queued
"requests_per_minute": 30
}
}
Notes
- Exact matches carry visual frame-level proof (
match_type: "exact").found_at_secondsmarks where your clip appears inside the matched video;audio_matchmeans the soundtrack fingerprint agreed. - AI flags (
is_ai_generated,ai_confidence) are heuristic annotations, not conclusive proof. - Uploads are transient. Files are analysed and deleted — we do not retain your video. Queued uploads are removed as soon as the job finishes.
- Screenshot batches are all-or-nothing. If any image in the batch fails, the request returns an error and no credits are charged.
- Jobs are scoped to the token's account — another account's
job_uuidreturns404. - Every error response uses the same
{"status":"error","message":…}envelope, including framework-level ones (429/404/405), so you can parse failures uniformly. - Questions, higher limits, or a bulk/enterprise plan? Contact us.