API documentation

Send a YouTube link from your site or app, get back a link to the video hosted with us.

Getting started

All requests go to this base URL and return JSON:

https://mystorevid.com/v1
  1. Create a key on the API keys page of your account and copy it right away (it is shown in full only once).
  2. Send a YouTube link with POST /videos; you get back a video with status queued.
  3. Wait until the status is ready — either poll GET /videos/{id}, or receive a webhook (recommended).
  4. Use urls.watch, urls.embed or urls.file on your site.
You need an active plan and free storage for “add video” requests to be accepted.

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

LimitValue
All requests60 per minute per key
Add video (POST)20 per minute per key
Keys10 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

POST/v1/videos
FieldTypeDescription
youtube_urlstring · requiredA YouTube video link (watch / youtu.be / shorts / live)
qualitystring360p, 720p, 1080p or 4K — default 720p. If unavailable we take the closest lower one.
titlestringYour 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

GET/v1/videos/{id}

If you poll instead of using webhooks, wait at least 5 seconds between calls.

List videos

GET/v1/videos?status=ready&page=1&per_page=20

status is an optional filter; per_page is 1–100. Response: {"data": [ … ], "meta": {"page", "per_page", "total", "last_page"}}, newest first.

Rename

PATCH/v1/videos/{id}

Body: {"title": "Lesson one"}

Delete

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

GET/v1/me

The 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": ["…"]}}}
HTTPcodeMeaning
401unauthorizedMissing, wrong or revoked key
402no_subscriptionNo active plan
403account_unverifiedAccount email not verified yet
404not_foundVideo not in your account, or unknown path
409storage_fullStorage is full
422validation_failed / invalid_urlMissing or invalid data; details in fields
429rate_limitedOver the limit; wait Retry-After seconds
500server_errorProblem 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']