Download OpenAPI specification:Download
The main API for playing content is the Streams API. This gives you the URLs of the manifest (DASH .mpd, or HLS .m3u8), as well as granting a playtoken needed for the license check.
The APIs for issuing playtokens are used when you need to use an API key to authorize a playback. The playtoken can be used by players allowing the bearer to watch content without needing an authtoken.
Returns the details you need to play some content.
Content is encoded with different formats (HLS/DASH) and DRM, so this will return multiple Streams objects and you need to pick the right one for your player.
This will return a playtoken. This is a JWT authorizing you to watch this specific content. You'll need to provide the playtoken to the license server in order to prove you're allowed to watch.
You can either provide an authtoken for a user, or a valid playtoken for the content.
Note: this API can also be called as a POST with an empty body.
slug required | string Example: /film/123 The slug of content to play, i.e. a film, film bonus, or TV episode. |
play_token | string a JWT used to authorize this playback session with the license server | ||||||
Array of objects | |||||||
Array
| |||||||
object or null The last known playback position, if available. | |||||||
| |||||||
ad_tag | string or null a VMAP url to use for this content if ads are configured. | ||||||
will_trigger_watch_window | boolean If true, the watch window will be triggered when a license request is made | ||||||
willTriggerRentalWindow | boolean Deprecated Use | ||||||
watch_window_duration | number or null The duration of the watch window, in minutes. This will be null if there's no watch window or it's not a rental. | ||||||
default_subtitle_language | string or null A hint to the player for picking default subtitles. Currently configured globally for a site. | ||||||
object Playback and content related configurations and feature toggles | |||||||
|
{- "play_token": "eyJhbGciOiJIUz...",
- "streams": [
- {
- "encoding_type": "hd_dash",
- "drm_type": [
- "widevine",
- "playready"
]
}, - {
- "encoding_type": "hls",
- "drm_type": [
- "fairplay"
]
}
], - "ad_tag": "",
- "will_trigger_watch_window": true,
- "watch_window_duration": 1800,
- "default_subtitle_language": "en",
- "config": { }
}
Playable slugs have a playlist associated with them. Currently, this is used for preroll and postroll, but it can theoretically support any arbitrary content on your platform.
A playlist is a series of items to play (e.g. different slugs).
The default playlist for any playable slug (e.g film, bonus or episode) is just a playlist with a single item in it.
Auth is not required, but is recommended so that your playback progress can be taken into account.
Note: this API can also be called as a POST with an empty body.
slug required | string Example: /film/123 The slug to get playlist for, i.e. a film, film bonus, or TV episode. |
title | string Title of the content being watched | ||||||||||||||||
Array of objects | |||||||||||||||||
Array
|
{- "title": "Citizen Kane",
- "items": [
- {
- "id": "preroll-1",
- "title": "Shift72 Presents",
- "skip_policy": "must-view-once",
- "has_watched": true,
- "action": {
- "type": "play",
- "slug": "/film/123/bonus/1"
}
}, - {
- "id": "feature",
- "title": "Citizen Kane",
- "skip_policy": "allowed",
- "has_watched": false,
- "action": {
- "type": "play",
- "slug": "/film/281"
}
}
]
}
Request a playtoken for the current user.
This usually isn't necessary, as the Streams API will issue a playtoken for the user if they use an authtoken.
For regular users, no request parameters are accepted: you get what you get and you don't get upset.
For admin users, the request body can tailor the playtoken a little bit, such as requesting a different expiry, changing the delivery policy (e.g. to reduce DRM strictness to allow all quality levels to be viewed on browsers that would otherwise be limited to SD-ish), and changing whether telemetry should be sent.
slug required | string Example: /film/123 The slug to get token for, i.e. a film, film bonus, or TV episode. |
exp | string <date-time> Expiry timestamp for this playtoken. NOTE this is an ISO8601 timestamp, NOT UNIX TIME. At most 24 hours in future |
uid | string or null Optional: text to show as a watermark over the video. This is applied by players to help discourage or track down screen recording |
olv | string or null Default: "og" Enum: "og" "apple" Optional: the style of overlay to use. |
delpol | string or null Enum: "urn:shift72" "urn:shift72.studio.1" "urn:shift72.studio.2" The delivery policy to use. If not specified, the content or site default will be used.
|
{ }
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwic2x1ZyI6Ii9maWxtLzI4MSIsInVzciI6Ilt1c2VyaWRdIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.l9J2jy0LROLrDTcpqsjUDnOMRhGRs0jVLORxlBWjJbk
Request a playtoken on a user's behalf.
This is used for scenarios where you want to generate a playtoken using an API key for a particular user.
userId required | number Example: 123456 The Shift72 user ID to issue this play token for |
slug required | string Example: /film/123 The slug to get token for, i.e. a film, film bonus, or TV episode. |
exp | string <date-time> Expiry timestamp for this playtoken. Defaults to 24 hours from now. NOTE this is an ISO8601 timestamp, NOT UNIX TIME. At most 24 hours in future. |
uid | string or null Text to show as a watermark over the video. This is applied by players to help discourage or track down screen recording" |
olv | string or null Default: "og" Enum: "og" "apple" The style of overlay to use. |
delpol | string or null Enum: "urn:shift72" "urn:shift72.studio.1" "urn:shift72.studio.2" The delivery policy to use. If not specified, the content or site default will be used.
|
{- "exp": "2019-08-24T14:15:22Z",
- "uid": "string",
- "olv": "og",
- "delpol": "urn:shift72"
}
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwic2x1ZyI6Ii9maWxtLzI4MSIsInVzciI6Ilt1c2VyaWRdIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.l9J2jy0LROLrDTcpqsjUDnOMRhGRs0jVLORxlBWjJbk
Get a playtoken to allow an external user to watch content.
As these tokens are for external users, no ownership, device limits, or region checks will be done. You need to ensure that the recipient is allowed to play this content before giving them a token.
You must provide an expiry time for the token, no more than 24 hours in the future. After a token has expired, attempts to start playback or perform license checks will fail and a new token will be required.
slug required | string Example: /film/123 The slug to get token for, i.e. a film, film bonus, or TV episode. |
usr required | string The user ID to associate with this playtoken. This can be a user ID in an external system. |
exp required | string <date-time> Expiry timestamp for this playtoken. NOTE this is an ISO8601 timestamp, NOT UNIX TIME |
uid | string or null Optional: text to show as a watermark over the video. This is applied by players to help discourage or track down screen recording |
olv | string or null Default: "og" Enum: "og" "apple" Optional: the style of overlay to use. |
delpol | string or null Enum: "urn:shift72" "urn:shift72.studio.1" "urn:shift72.studio.2" Optional: The delivery policy to use. If not specified, the content or site default will be used.
|
additional property | string or boolean or number Additional claims to include in the playtoken. These can be JSON strings, booleans or numbers. It's strongly recommended that you add a vendor prefix to any custom claims so that they don't conflict with any Shift72 issued claims. |
Any of string Additional claims to include in the playtoken. These can be JSON strings, booleans or numbers. It's strongly recommended that you add a vendor prefix to any custom claims so that they don't conflict with any Shift72 issued claims. |
{- "usr": "string",
- "exp": "2019-08-24T14:15:22Z",
- "uid": "string",
- "olv": "og",
- "delpol": "urn:shift72",
- "property1": "string",
- "property2": "string"
}
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwic2x1ZyI6Ii9maWxtLzI4MSIsInVzciI6Ilt1c2VyaWRdIiwiZXhwIjoxNTE2MjM5MDIyLCJpYXQiOjE1MTYyMzkwMjJ9.l9J2jy0LROLrDTcpqsjUDnOMRhGRs0jVLORxlBWjJbk
A user's library is the TVOD content they've bought (e.g. rentals or EST purchases).
The library can also contain plan content if the plan has been flagged as a "library plan". This is useful for hybrid models, such as festival passes where there may be a small number of films that should appear similar to other rentals.
For SVOD sites with large content libraries it's more appropriate for users to discover plan content other ways -- including the full catalogue in their library view would be overwhelming!
Gets the library content and plans for the current user
location | string override the users location, used for plan-as-library content |
Array of objects (LibraryItem) The media items a user owns. This is usually stuff they've rented or bought. Plan content can appear here too, if the plan has been set up as a Library Plan. Recent expired rentals appear in the library too. These can be identified
by The same item can appear multiple times -- e.g. if the user rents an item, and it later is added via a Library Plan. If the same content is in multiple Library Plans, then there will be one library item for each of the plans. Sorting: the library items are sorted so that watchable items will always appear before expired content. There are some heuristics applied so that the most relevant items are near the top of the list (e.g. expiring soon) | |||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||
Array of objects The plans this user has access to. These could be subscriptions, one-off plans (e.g. passes) or plans that were automatically assigned on sign-up or via an integration. | |||||||||||||||||||||||||||||||||||||
Array
|
{- "items": [
- {
- "ownership": "rent",
- "type": "film",
- "slug": "string",
- "title": "string",
- "available_from": "string",
- "available_to": "string",
- "expiry": "string",
- "is_expired": true,
- "watch_window_duration": 0,
- "watch_window_start": "string",
- "watch_window_end": "string",
- "plan_id": 0,
- "playback_progress": {
- "play_position": 0,
- "last_played_at": "string",
- "length": 0,
- "completed": true
}
}
], - "plans": [
- {
- "plan_id": 0,
- "expiry": "string"
}
]
}
A user can request to see their own library, or a privileged user can view others libraries.
user_id required | integer <int32> User ID |
location | string override the users location for plan-as-library content |
Array of objects (LibraryItem) The media items a user owns. This is usually stuff they've rented or bought. Plan content can appear here too, if the plan has been set up as a Library Plan. Recent expired rentals appear in the library too. These can be identified
by The same item can appear multiple times -- e.g. if the user rents an item, and it later is added via a Library Plan. If the same content is in multiple Library Plans, then there will be one library item for each of the plans. Sorting: the library items are sorted so that watchable items will always appear before expired content. There are some heuristics applied so that the most relevant items are near the top of the list (e.g. expiring soon) | |||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||
Array of objects The plans this user has access to. These could be subscriptions, one-off plans (e.g. passes) or plans that were automatically assigned on sign-up or via an integration. | |||||||||||||||||||||||||||||||||||||
Array
|
{- "items": [
- {
- "ownership": "rent",
- "type": "film",
- "slug": "string",
- "title": "string",
- "available_from": "string",
- "available_to": "string",
- "expiry": "string",
- "is_expired": true,
- "watch_window_duration": 0,
- "watch_window_start": "string",
- "watch_window_end": "string",
- "plan_id": 0,
- "playback_progress": {
- "play_position": 0,
- "last_played_at": "string",
- "length": 0,
- "completed": true
}
}
], - "plans": [
- {
- "plan_id": 0,
- "expiry": "string"
}
]
}