Getting started
All requests go to this base URL and return JSON:
https://mystorevid.com/v1
- Create a key on the API keys page of your account and copy it right away (it is shown in full only once).
- Send a YouTube link with
POST /videos; you get back a video with statusqueued. - Wait until the status is
ready— either pollGET /videos/{id}, or receive a webhook (recommended). - Use
urls.watch,urls.embedorurls.fileon your site.
Authentication
Send your key in the Authorization header on every request:
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
or in an X-API-Key header. Keys are secret like passwords: call the API only from your own server, never from web-page code or mobile apps that can be decompiled. If a key leaks, revoke it on the keys page and create a new one.
Limits
| Limit | Value |
|---|---|
| All requests | 60 per minute per key |
Add video (POST) | 20 per minute per key |
| Keys | 10 active keys per account |
Above the limit you get 429 with a Retry-After header in seconds.
The video object
{
"id": "vid_8f3a21kq0p",
"title": "Big Buck Bunny",
"status": "ready", // queued | downloading | processing | ready | failed
"progress": 100, // 0–100
"quality": "720p", // requested
"height": 720, // actual
"duration_seconds": 596,
"size_bytes": 167772160,
"source": "youtube",
"source_url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
"created_via": "api",
"urls": { // null until ready
"watch": "https://mystorevid.com/v/vid_8f3a21kq0p",
"embed": "https://mystorevid.com/e/vid_8f3a21kq0p",
"file": "https://mystorevid.com/f/vid_8f3a21kq0p"
},
"embed_html": "<iframe src=… allowfullscreen></iframe>",
"thumbnail": "https://i.ytimg.com/vi/aqz-KE-bpKQ/hqdefault.jpg",
"error": null, // {"code","message"} when status = failed
"created_at": "2026-11-18T18:00:00+00:00",
"updated_at": "2026-11-18T18:01:12+00:00"
}
Add a video
/v1/videos| Field | Type | Description |
|---|---|---|
youtube_url | string · required | A YouTube video link (watch / youtu.be / shorts / live) |
quality | string | 360p, 720p, 1080p or 4K — default 720p. If unavailable we take the closest lower one. |
title | string | Your own title. If omitted we use the YouTube title. |
curl -X POST https://mystorevid.com/v1/videos \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{"youtube_url":"https://youtu.be/aqz-KE-bpKQ","quality":"720p"}'
Response: 202 Accepted with {"data": {…video…}} in status queued. The download runs in the background.
Get a video
/v1/videos/{id}If you poll instead of using webhooks, wait at least 5 seconds between calls.
List videos
/v1/videos?status=ready&page=1&per_page=20status is an optional filter; per_page is 1–100. Response: {"data": [ … ], "meta": {"page", "per_page", "total", "last_page"}}, newest first.
Rename
/v1/videos/{id}Body: {"title": "Lesson one"}
Delete
/v1/videos/{id}Deletes the video and its file for good and frees the storage. A download still running is cancelled. Response: {"data": {"id": "…", "deleted": true}}.
Account
/v1/meThe key owner, plan and end date, storage (limit_bytes, used_bytes, free_bytes) and available qualities. A good first call to check that a key works.
Webhooks
Set an https:// URL on the API keys page and we will POST to it when a video becomes ready or fails:
POST https://your-site.com/hooks/videos
Content-Type: application/json
X-VP-Event: video.ready // video.ready | video.failed | video.test
X-VP-Signature: t=1795020000,v1=5f2c…e91a
{"event": "video.ready", "created_at": "2026-11-18T18:01:12+00:00", "data": {"video": {…video object…}}}
Verify the signature
Compute HMAC-SHA256 of t + "." + body (the raw body exactly as received) with your signing secret whsec_… and compare it to v1. Reject requests whose t is older than 5 minutes.
// PHP
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_VP_SIGNATURE'] ?? ''), $sig);
$ok = isset($sig['t'], $sig['v1'])
&& abs(time() - (int) $sig['t']) < 300
&& hash_equals(hash_hmac('sha256', $sig['t'].'.'.$raw, 'whsec_…'), $sig['v1']);
if (! $ok) { http_response_code(400); exit; }
Answer with any 2xx within 10 seconds. Otherwise we retry twice (after 30 seconds and after 5 minutes). The same event may arrive more than once, so key your handling on data.video.id.
Errors
{"error": {"code": "validation_failed", "message": "The youtube url field is required.", "fields": {"youtube_url": ["…"]}}}
| HTTP | code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, wrong or revoked key |
| 402 | no_subscription | No active plan |
| 403 | account_unverified | Account email not verified yet |
| 404 | not_found | Video not in your account, or unknown path |
| 409 | storage_full | Storage is full |
| 422 | validation_failed / invalid_url | Missing or invalid data; details in fields |
| 429 | rate_limited | Over the limit; wait Retry-After seconds |
| 500 | server_error | Problem on our side; retry later |
If the download itself fails, your request succeeded but the video ends in failed with an error.code such as private, unavailable, members, live, age, no_space, blocked or failed.
Examples
PHP
$ch = curl_init('https://mystorevid.com/v1/videos');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['youtube_url' => 'https://youtu.be/aqz-KE-bpKQ', 'quality' => '720p']),
]);
$video = json_decode(curl_exec($ch), true)['data'];
JavaScript (Node 18+)
const res = await fetch('https://mystorevid.com/v1/videos', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.VP_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ youtube_url: 'https://youtu.be/aqz-KE-bpKQ', quality: '1080p' }),
});
const { data, error } = await res.json();
Python
import os, requests
r = requests.post('https://mystorevid.com/v1/videos',
headers={'Authorization': 'Bearer ' + os.environ['VP_KEY']},
json={'youtube_url': 'https://youtu.be/aqz-KE-bpKQ', 'quality': '720p'})
video = r.json()['data']