Videos API

Upload, manage, and retrieve video content programmatically. Supports file uploads, URL imports, browser uploads, and full video lifecycle management.

POST

Upload Video via URL

/videos

Import a video from an external URL. The video will be downloaded and transcoded automatically. Use the upload base URL for this endpoint.

Headers

Parameter	Type	Required	Description
Authorization	`string`	Required	Bearer token. Format: Bearer YOUR_API_KEY
Content-Type	`string`	Required	Must be application/json

Body Parameters

Parameter	Type	Required	Description
url	`string`	Required	Public URL of the video file to import
title	`string`	Optional	Title for the videoDefault: `Untitled`
channelKey	`string`	Optional	Channel key to associate the video with
projectId	`string`	Optional	Project ID to organize the video under
description	`string`	Optional	Video description
tags	`string[]`	Optional	Array of tags for categorization
options	`object`	Optional	Video playback options (autoplay, loop, muted, etc.)

json

{
  "id": "fFL56RU6PjvJPeE",
  "title": "My Imported Video",
  "channelKey": "f8RMr2q4h6yNpv9",
  "status": 1,
  "created": "2024-01-15T10:30:00Z",
  "iframeLink": "https://player.streamvault.one/embed/fFL56RU6PjvJPeE",
  "hlsLink": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/master.m3u8",
  "privateLink": "https://streamvault.one/v/fFL56RU6PjvJPeE",
  "duration": null,
  "image": {
    "xsUrl": "",
    "smUrl": "",
    "mdUrl": "",
    "lgUrl": ""
  }
}

json

{
  "error": "url is required",
  "code": "INVALID_REQUEST"
}

json

{
  "error": "Video upload limit reached for your plan",
  "code": "QUOTA_EXCEEDED",
  "limit": 50,
  "current": 50
}

Try it out

POST/videos

url

title

channelKey

projectId

bash

curl -X POST "https://api.streamvault.one/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/video.mp4",
  "title": "Untitled"
}'

POST

Browser Upload

/videos/browser

Get a tokenized upload URL for direct browser-based uploads using TUS protocol. Returns credentials for chunked resumable upload.

Body Parameters

Parameter	Type	Required	Description
title	`string`	Optional	Title for the videoDefault: `Untitled`
projectId	`string`	Optional	Project ID to organize the video under

json

{
  "video_id": "a1b2c3d4e5",
  "library_id": "12345",
  "tus_endpoint": "https://video.bunnycdn.com/tusupload",
  "auth_signature": "sha256-signature-hash",
  "auth_expiration_time": 1704067200,
  "put_upload_url": "https://video.bunnycdn.com/library/12345/videos/a1b2c3d4e5"
}

Try it out

POST/videos/browser

title

bash

curl -X POST "https://api.streamvault.one/v1/videos/browser" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Untitled"
}'

GET

List Videos

/videos

Retrieve a paginated list of all videos in your account. Supports search, sorting, and pagination.

Query Parameters

Parameter	Type	Required	Description
page	`integer`	Optional	Page number for paginationDefault: `1`
itemsPerPage	`integer`	Optional	Number of results per pageDefault: `100`
search	`string`	Optional	Search videos by title
orderBy	`string`	Optional	Sort order: date, title, durationDefault: `date`
projectId	`string`	Optional	Filter by project ID
status	`integer`	Optional	Filter by status code (0-50)

json

{
  "pager": {
    "page": 1,
    "totalPages": 3,
    "totalResults": 42,
    "sort": "date"
  },
  "videos": [
    {
      "id": "fFL56RU6PjvJPeE",
      "title": "Product Demo",
      "channelKey": "f8RMr2q4h6yNpv9",
      "status": 3,
      "duration": "00:02:30",
      "created": "2024-01-15T10:30:00Z",
      "image": {
        "xsUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg",
        "smUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg",
        "mdUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg",
        "lgUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg"
      },
      "tags": ["demo", "product"],
      "options": {
        "autoplay": false,
        "loop": false,
        "muted": false
      }
    }
  ]
}

Try it out

GET/videos

page

orderBy

bash

curl -X GET "https://api.streamvault.one/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET

Get Video

/videos/{id}

Retrieve detailed information about a single video including playback URLs, metadata, and configuration.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

json

{
  "id": "fFL56RU6PjvJPeE",
  "title": "Product Demo",
  "description": "A walkthrough of our product features",
  "channelKey": "f8RMr2q4h6yNpv9",
  "status": 3,
  "duration": "00:02:30",
  "created": "2024-01-15T10:30:00Z",
  "iframeLink": "https://player.streamvault.one/embed/fFL56RU6PjvJPeE",
  "hlsLink": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/master.m3u8",
  "privateLink": "https://streamvault.one/v/fFL56RU6PjvJPeE",
  "image": {
    "xsUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg",
    "smUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg",
    "mdUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg",
    "lgUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg"
  },
  "captions": [
    { "id": "cap_1", "language": "en", "label": "English", "isDefault": true }
  ],
  "tags": ["demo", "product"],
  "formats": {
    "hls": true,
    "mp4": false,
    "options": { "secureMp4": true }
  },
  "options": {
    "autoplay": false,
    "loop": false,
    "muted": false,
    "controls": true,
    "pip": false
  }
}

json

{
  "error": "Video not found",
  "code": "NOT_FOUND"
}

Try it out

GET/videos/{id}

bash

curl -X GET "https://api.streamvault.one/v1/videos/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET

Get Video Status

/videos/{id}/status

Check the transcoding/processing status of a specific video. Useful for polling after upload.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

json

{
  "id": "fFL56RU6PjvJPeE",
  "status": 2,
  "statusLabel": "Processing",
  "encodeProgress": 65,
  "message": "Transcoding in progress"
}

Status	Value	Description
Na	`0`	Not available
Uploaded	`1`	File uploaded, waiting to process
Processing	`2`	Transcoding in progress
Published	`3`	Ready for playback
Error	`-1`	Transcoding failed
Deleted	`50`	Deleted

Try it out

GET/videos/{id}/status

bash

curl -X GET "https://api.streamvault.one/v1/videos/{id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT

Update Video

/videos/{id}

Update video metadata, options, access controls, and configuration.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

Body Parameters

Parameter	Type	Required	Description
title	`string`	Optional	New title for the video
description	`string`	Optional	New description
tags	`string[]`	Optional	Updated tags array
projectId	`string`	Optional	Move to a different project
options	`object`	Optional	Playback options: autoplay, loop, muted, controls, pip, stickyOnScroll
allowedDomains	`string[]`	Optional	Domains allowed to embed this video
allowedCountries	`string[]`	Optional	ISO country codes allowed to view
blockedCountries	`string[]`	Optional	ISO country codes blocked from viewing
password	`string`	Optional	Set a password for protected playback
requireAuth	`boolean`	Optional	Require viewer authentication
maxViews	`integer`	Optional	Maximum allowed view count
expiresAt	`datetime`	Optional	ISO 8601 expiration timestamp
skinId	`string`	Optional	Player skin ID to apply

json

{
  "id": "fFL56RU6PjvJPeE",
  "title": "Updated Title",
  "description": "Updated description",
  "tags": ["updated", "demo"],
  "status": 3,
  "updated": "2024-01-16T08:00:00Z"
}

Try it out

PUT/videos/{id}

title

description

bash

curl -X PUT "https://api.streamvault.one/v1/videos/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated Title"
}'

DELETE

Delete Video

/videos/{id}

Permanently delete a video and all associated data (captions, chapters, CTAs, analytics).

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

json

{
  "success": true,
  "message": "Video deleted successfully"
}

json

{
  "error": "Video not found",
  "code": "NOT_FOUND"
}

Try it out

DELETE/videos/{id}

bash

curl -X DELETE "https://api.streamvault.one/v1/videos/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST

Copy CTA

/videos/{id}/cta/copy

Copy all call-to-action overlays from one video to one or more target videos.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	Source video ID to copy CTAs from

Body Parameters

Parameter	Type	Required	Description
targetVideoIds	`string[]`	Required	Array of video IDs to copy CTAs to

json

{
  "success": true,
  "copied": 3,
  "targetVideoIds": ["vid_1", "vid_2", "vid_3"]
}

Try it out

POST/videos/{id}/cta/copy

targetVideoIds

bash

curl -X POST "https://api.streamvault.one/v1/videos/{id}/cta/copy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "targetVideoIds": []
}'

POST

Move Videos Between Projects

/videos/change-project

Move one or more videos to a different project.

Body Parameters

Parameter	Type	Required	Description
videoIds	`string[]`	Required	Array of video IDs to move
projectId	`string`	Required	Target project ID

json

{
  "success": true,
  "moved": 2,
  "projectId": "proj_target123"
}

Try it out

POST/videos/change-project

videoIds

projectId

bash

curl -X POST "https://api.streamvault.one/v1/videos/change-project" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "videoIds": [],
  "projectId": ""
}'

GET

Get Original File

/videos/{id}/original-file

Get a temporary signed URL to download the original uploaded video file.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

json

{
  "url": "https://cdn.streamvault.one/original/fFL56RU6PjvJPeE/video.mp4?token=abc&expires=1704067200",
  "expiresAt": "2024-01-15T12:00:00Z"
}

Try it out

GET/videos/{id}/original-file

bash

curl -X GET "https://api.streamvault.one/v1/videos/{id}/original-file" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET

Get Collected Emails

/videos/collected-emails

Retrieve all emails collected via email gates on your videos from the last 365 days.

Query Parameters

Parameter	Type	Required	Description
videoId	`string`	Optional	Filter by specific video ID
channelId	`string`	Optional	Filter by specific channel ID

json

{
  "emails": [
    {
      "email": "viewer@example.com",
      "videoId": "fFL56RU6PjvJPeE",
      "channelId": "ch_abc123",
      "subscribedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150
}

Try it out

GET/videos/collected-emails

videoId

bash

curl -X GET "https://api.streamvault.one/v1/videos/collected-emails" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST

Create Expirable Link

/videos/{id}/expirable-link

Generate a time-limited playback link with optional view count limits and geo-restrictions.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

Body Parameters

Parameter	Type	Required	Description
expiresAt	`datetime`	Required	ISO 8601 expiration timestamp
maxViews	`integer`	Optional	Maximum number of views allowed
allowedCountries	`string[]`	Optional	ISO country codes allowed
blockedCountries	`string[]`	Optional	ISO country codes blocked

json

{
  "id": "link_abc123",
  "token": "f4a8c2e1d3b5a7c9",
  "url": "https://player.streamvault.one/embed/fFL56RU6PjvJPeE?token=f4a8c2e1d3b5a7c9",
  "expiresAt": "2024-02-15T00:00:00Z",
  "maxViews": 100,
  "viewCount": 0
}

Try it out

POST/videos/{id}/expirable-link

expiresAt

maxViews

bash

curl -X POST "https://api.streamvault.one/v1/videos/{id}/expirable-link" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expiresAt": "2024-12-31T23:59:59Z"
}'

PUT

Update Thumbnail

/videos/image/{id}

Upload a new thumbnail image for a video. Accepts JPEG or PNG files up to 5MB.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

Body (multipart/form-data)

Parameter	Type	Required	Description
file	`file`	Required	Image file (JPEG or PNG, max 5MB)

json

{
  "success": true,
  "thumbnailUrl": "https://api.streamvault.one/v1/play/fFL56RU6PjvJPeE/poster.jpg"
}

bash

curl -X PUT "https://api.streamvault.one/v1/videos/image/fFL56RU6PjvJPeE" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/thumbnail.jpg"

POST

Add Captions

/videos/captions/{id}

Upload an SRT or VTT subtitle file for a video.

Path Parameters

Parameter	Type	Required	Description
id	`string`	Required	The unique video identifier

Body Parameters

Parameter	Type	Required	Description
language	`string`	Required	ISO 639-1 language code (e.g. en, es, fr)
label	`string`	Optional	Display label for the caption trackDefault: `English`
srtContent	`string`	Required	SRT or VTT content as string
isDefault	`boolean`	Optional	Set as the default caption trackDefault: `false`

json

{
  "id": "cap_xyz789",
  "videoId": "fFL56RU6PjvJPeE",
  "language": "en",
  "label": "English",
  "isDefault": true
}

Try it out

POST/videos/captions/{id}

language

label

bash

curl -X POST "https://api.streamvault.one/v1/videos/captions/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "language": "en",
  "label": "English",
  "srtContent": "1\n00:00:00,000 --> 00:00:05,000\nHello World",
  "isDefault": true
}'

DELETE

Delete Captions

/videos/captions

Remove a caption track from a video.

Query Parameters

Parameter	Type	Required	Description
videoId	`string`	Required	The video identifier
captionsId	`string`	Required	The caption track identifier

json

{
  "success": true,
  "message": "Caption track deleted"
}

Try it out

DELETE/videos/captions?videoId={videoId}&captionsId={captionsId}

videoId

captionsId

bash

curl -X DELETE "https://api.streamvault.one/v1/videos/captions?videoId={videoId}&captionsId={captionsId}" \
  -H "Authorization: Bearer YOUR_API_KEY"