CDNShark Documentation

Video Libraries & Playback Tokens API

A video library stores and transcodes your videos (on-demand HLS), and delivers them through its own CDN hostname. Uploading videos is done in the portal, on the library's page (portal_url). Playback tokens then give viewers signed, expiring links.

List libraries

GET /api/video/libraries (streams:read). Returns {"data": [library, ...]}. Each library includes its bucket, and bucket.id is the bucket_id used for playback tokens. Needs an active paid service.

Create a library

POST /api/video/libraries (streams:write) with {"name": "Courses"}. Needs an active paid service and a plan that includes Stream.

{
  "data": {
    "id": 12, "name": "Courses", "slug": "courses",
    "bucket_name": "stream-u17-courses-a1b2c3",
    "cdn_url": "stream-u17-courses-a1b2c3.cdn.cdnshark.com",
    "cdn_base_url": "https://stream-u17-courses-a1b2c3.cdn.cdnshark.com",
    "portal_url": "https://.../cp/video-transcode/libraries/12",
    "status": "active"
  }
}

Videos in a library play only through signed URLs, such as playback tokens.

Delete a library

DELETE /api/video/libraries/{id} (streams:write). Deletes the library's videos, storage and playback tokens.

Playback tokens

A playback token is a signed link to one video that stops working at expires_at. The CDN edge checks the signature and the expiry on every request, without calling back to us.

Create

POST /api/video/playback-token (streams:write)

Field	Required	Notes
bucket_id	yes	The library's bucket id (from the libraries list).
vod_path	yes	Path of the video's HLS master playlist inside the library, for example vod/courses/intro-lesson/master.m3u8: the video's stream URL in the portal without the hostname. 404 if it does not exist.
expires_in_hours	yes	1 to 8760.
max_views, ip_whitelist	no	Stored with the token and shown in its logs. Enforcement at the edge is currently the signature and the expiry only.

Returns 201 {"id", "token", "playback_url", "expires_at", "max_views", "signature"}. Give playback_url to any HLS player.

Other token calls

Method	Path	Permission	What it does
GET	/api/video/playback-tokens	streams:read	All your tokens.
GET	/api/video/playback-token/{id}	streams:read	One token, with playback_url, is_expired, is_revoked, views_count.
POST	/api/video/playback-token/{id}/refresh	streams:write	Body {"expires_in_hours": 24}. Sets a new expiry and returns a new playback_url.
DELETE	/api/video/playback-token/{id}	streams:write	Marks the token revoked.
GET	/api/video/playback-token/{id}/logs	streams:read	Access log. Query limit (max 1000, default 100) and offset.

Links are verified by signature at the edge. A URL already handed out therefore keeps working until its own expires_at, even after a refresh or a revoke. Use short expiries for anything sensitive.

Transcoding fires the video.uploaded, video.transcode.complete and video.transcode.failed webhooks. See Webhooks API.