StreamVault API

Upload, transcode, stream and manage video programmatically. All access over HTTPS, JSON in/out. Build powerful video integrations in minutes.

Get Started → Get API Key

Overview

Introduction

The StreamVault REST API lets you upload, manage and stream video at scale. All data is sent and received as JSON. Timestamps are UNIX epoch integers (seconds).

Base URL https://api.streamvault.link

HLS Streaming

Auto-transcode to 360p–4K adaptive bitrate with AES-128 encryption.

AI Subtitles

Whisper-powered transcription in 11 languages. VTT delivered over API.

Webhooks

HMAC-signed events for video.ready, transcription.complete, and more.

All responses include Content-Type: application/json. Errors always return { "error": "..." }.

Security

Authentication

StreamVault supports two auth methods. All endpoints require Authorization header + X-Workspace-Id.

Bearer Token (JWT)

Header Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Workspace X-Workspace-Id: ws_a1b2c3d4e5

Obtain via POST /auth/login. Expires in 15 min — use POST /auth/refresh.

API Key Pro+

Header Authorization: Bearer sv_live_a1b2c3d4e5f6...

Workspace X-Workspace-Id: ws_a1b2c3d4e5

Keys start with sv_live_. Shown once at creation — save securely.

Reference

Errors & Rate Limits

Conventional HTTP status codes. Errors always carry a human-readable error field.

Status	Meaning
200	Success
201	Resource created
202	Accepted — async job queued
400	Bad request — missing/invalid parameters
401	Unauthenticated — invalid/expired token
403	Forbidden — insufficient plan or role
404	Resource not found
429	Rate limit exceeded
503	Service unavailable

Upload endpoints: 10 req/min per IP. Webhooks retry with exponential backoff — 3 attempts, up to 1 hour.

Videos

Video Management

POST /api/upload Upload a video — triggers HLS transcoding ▼

Send as multipart/form-data. Max: 10 GB. Async — poll or use webhooks.

Request body (multipart/form-data)

Field	Type		Description
video	file	required	MP4, MKV, MOV, AVI, WebM
title	string	required	Display title
description	string	optional	Long description
folder_id	string	optional	Target folder
visibility	string	optional	`public` · `private` · `password`

curl -X POST https://api.streamvault.link/api/upload \
  -H "Authorization: Bearer sv_live_YOUR_KEY" \
  -H "X-Workspace-Id: ws_YOUR_WORKSPACE" \
  -F "video=@/path/to/movie.mp4" \
  -F "title=My Awesome Video" \
  -F "visibility=public"

import requests

url = "https://api.streamvault.link/api/upload"
hdrs = {"Authorization": "Bearer sv_live_YOUR_KEY", "X-Workspace-Id": "ws_YOUR_WORKSPACE"}
with open("/path/to/movie.mp4", "rb") as f:
    r = requests.post(url, headers=hdrs, files={"video": f}, data={"title": "My Awesome Video"})
print(r.json())

const form = new FormData();
form.append('video', fs.createReadStream('/path/to/movie.mp4'));
form.append('title', 'My Awesome Video');

const res = await fetch('https://api.streamvault.link/api/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sv_live_YOUR_KEY', 'X-Workspace-Id': 'ws_YOUR_WORKSPACE' },
  body: form,
});

Response

{
  "id":           "vid_a1b2c3",
  "title":        "My Awesome Video",
  "status":       "queued",
  "workspace_id": "ws_YOUR_WORKSPACE",
  "created_at":   1714500000
}

200Upload accepted. Status: queued → transcoding → ready

400Missing video/title or exceeds 10 GB

403Quota exceeded

GET /api/videos List videos (paginated) ▼

Query parameters

Param	Type	Default	Description
page	integer	`1`	Page number
limit	integer	`20`	Results per page (max 100)
search	string	—	Full-text search
folder_id	string	—	Filter by folder
status	string	—	`ready` · `processing` · `error`

curl "https://api.streamvault.link/api/videos?page=1&limit=20" \
  -H "Authorization: Bearer sv_live_YOUR_KEY" \
  -H "X-Workspace-Id: ws_YOUR_WORKSPACE"

GET /api/videos/{id} Get a single video ▼

curl https://api.streamvault.link/api/videos/vid_a1b2c3 \
  -H "Authorization: Bearer sv_live_YOUR_KEY" \
  -H "X-Workspace-Id: ws_YOUR_WORKSPACE"

200Full video object with embedConfig and AI fields

404Video not found

PATCH /api/videos/{id} Update metadata, visibility, or schedule publishing ▼

Request body

Field	Type		Description
title	string	optional	New title
description	string	optional	New description
visibility	string	optional	`public` · `private` · `password`
folder_id	string\|null	optional	Move to folder (null to remove)

DELETE /api/videos/{id} Delete video and all files permanently ▼

Permanently deletes HLS segments, thumbnails, and transcriptions. Cannot be undone.

200{"success":true}

404Video not found

POST /api/videos/bulk Bulk delete, move, or change visibility (up to 200) ▼

Request body

Field	Type		Description
ids	string[]	required	Video IDs (max 200)
action	string	required	`delete` · `move` · `visibility`

Playback

Playback & Delivery

GET /api/videos/{id}/token Get 15-min signed HLS playback token ▼

Append ?token=TOKEN to HLS URLs. Auto-renews 2 min before expiry.

{ "token": "sv_tok_ab12cd34...", "ttl": 900, "renewAfter": 780 }

POST /api/videos/{id}/download-link Generate signed download URL (10 min) Pro+ ▼

{ "url": "https://cdn.streamvault.link/originals/vid_a1b2c3.mp4?...", "ttl": 600 }

POST /api/videos/{id}/retry Retry a failed transcoding job ▼

200{"queued":true}

409Video not in error state

Organization

Folders & Playlists

GET /api/folders List all folders ▼

[{ "id": "fld_x1", "name": "Marketing", "video_count": 14 }]

POST /api/folders Create a folder ▼

Field	Type		Description
name	string	required	Folder name
parent_id	string\|null	optional	Parent for nesting

GET /api/playlists List playlists ▼

curl https://api.streamvault.link/api/playlists \
  -H "Authorization: Bearer sv_live_YOUR_KEY" \
  -H "X-Workspace-Id: ws_YOUR_WORKSPACE"

POST /api/playlists Create a playlist ▼

Field	Type		Description
title	string	required	Playlist title
video_ids	string[]	optional	Initial videos

AI & Subs

AI & Transcriptions

POST /api/videos/{id}/transcribe Transcribe audio with Whisper Pro+ ▼

Async. Listen for transcription.complete webhook. Supports: en, es, fr, de, it, pt, nl, pl, ru, ja, zh.

202Job queued

403Pro plan required

GET /api/videos/{id}/transcription.vtt Download WebVTT subtitles ▼

Returns VTT with Content-Type: text/vtt. Available after transcription completes.

GET /api/videos/{id}/analytics Video analytics (views, watch time, engagement) ▼

Param	Type	Description
start_date	string	YYYY-MM-DD
end_date	string	YYYY-MM-DD

Webhooks

GET /api/webhooks List configured webhooks ▼

curl https://api.streamvault.link/api/webhooks \
  -H "Authorization: Bearer sv_live_YOUR_KEY" \
  -H "X-Workspace-Id: ws_YOUR_WORKSPACE"

POST /api/webhooks Create a webhook endpoint ▼

Field	Type		Description
url	string	required	HTTPS endpoint URL
events	string[]	required	Events to subscribe
secret	string	optional	HMAC secret (auto-generated if omitted)

Available events

video.ready video.error video.deleted transcription.complete transcription.error

Payloads signed with HMAC-SHA256. Verify X-StreamVault-Signature header.

Workspaces

Workspaces & API Keys

GET /api/workspaces List your workspaces ▼

curl https://api.streamvault.link/api/workspaces \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/workspaces/{id}/apikeys Create API key Pro+ ▼

Field	Type		Description
name	string	required	Display name
permissions	string[]	optional	`read`, `write`

The API key is shown once. Save it immediately — you won't see it again.

System

GET /health Health check (no auth required) ▼

{
  "status": "healthy",
  "timestamp": 1714500000,
  "services": { "database": "ok", "storage": "ok", "queue": "ok" }
}