API docs by Redocly

Playback API Reference (2.0.0)

Download OpenAPI specification:Download

Reference for the Brightcove Playback API, used for client-side access video and playlist information.

The raw API JSON response is not suitable for the player. Use the player.catalog.transformVideoResponse() function to convert each video object in the response into a format compatible with the player. This includes duration times and https image compatibility. For details, see the Player Catalog document.

For additional in-depth guides to features of the API, see the Overview.

**NOTE: this is version 2 of the Playback API - almost all Brightcove accounts are on this version, but a very few are still on version 1. All version 1 functionality works with version 2. Version 2 offers some new functionality as noted below. The base url is the same for both versions - requests are directed to the correct version based on the account settings.

Base URL: https://edge.api.brightcove.com/playback/v1

Videos

Operations for retrieving videos. Version 2 of the API only

Get Video by ID or Reference ID

Gets a video object based on a video ID or reference ID. To get a video using the reference_id, use: https://edge.api.brightcove.com/playback/v1/accounts/{account_id}/videos/ref:{reference_id}`

Note that you can specify multiple video ids in a comma-delimited list, but only one reference_id.

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
ad_config_id
string
config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Response samples

Content type
application/json
{}

Get Videos

Gets a page of video objects. The Playback API allows you to programmatically search for videos in your Video Cloud library. For more information on the search syntax, see CMS/Playback API: Videos Search.

Notes:

  • When performing a search, you need to use a search-enabled Policy Key. For information on getting policy keys, see the Policy API Overview or the Policy Keys documents. In general, search-enabled Policy Keys should only be stored on a server and not in a browser player or mobile app, since they can be used to list all playable videos. For some accounts this may not be applicable if you do not care if all of your playable videos can be discovered.

  • The maximum number of videos (highest count value) returned is 1000, even if there are more matching videos in the account. The count value is an estimate and should not be relied on as the exact number to be returned. If all results are desired then keep paging until it no longer returns a full page, or use the CMS api.

  • Only currently playable videos are included in the results list. It is recommended to do a similar query with the CMS api to see why some videos are excluded. Any geo-restricted videos that are denied for the particular requestor are omitted from the results. As long as some videos are allowed the request is considered successful. An errors field is added to the result with a summary explaining why videos were omitted.

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
q
string

search string - see search guide for details

limit
integer [ 1 .. 1000 ]
Default: 20

The number of videos to return

offset
integer >= 0
Default: 0

The number of videos to skip - used to page multiple sets of videos. Note that the maximum number of videos that can be returned by the Playback API is 1000. To return more than 1000 videos, you must use the CMS API.

sort
string
Default: "-updated_at"
Enum: "name" "reference_id" "created_at" "published_at" "updated_at" "schedule_starts_at" "schedule_ends_at" "state" "plays_total" "plays_trailing_week"

Field to sort results by; if absent and there is a search string, results are sorted by relevance — note that plays_total and plays_trailing_week are not included in the response - note: to sort in descending order, preface the sort field name with a minus (-) sign

ad_config_id
string
config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Response samples

Content type
application/json
[]

Static URLs

Operations for retrieving static URLs for video manifests. This gives you the flexibility to manage your content in your own CMS, and deliver it using a custom security schema.

Static URL requests are for version 2 of the API only.

This is important for customers who have existing architecture that does not allow a Playback API call before needing the manifest url(s). The player can also use this feature, reducing playback start time by eliminating one call.

See Static URL Delivery for more information.

Get an HLS Manifest with static URLs

Gets an HLS manifest with static URLs for the renditions and other assets. Note that the URLs carry a token, and are good for the TTL of the token. Version 2 of the API only

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
bcov_auth
required
string

The value is a JWT (JSON Web Token) - see Static URL Delivery and Creating a JSON Web Token

config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Get a DASH Manifest with static URLs

Gets a DASH manifest with static URLs for the renditions and other assets. Note that the URLs carry a token, and are good for the TTL of the token. Version 2 of the API only

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
bcov_auth
required
string

The value is a JWT (JSON Web Token) - see Static URL Delivery and Creating a JSON Web Token

config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Get an HLS VMAP with static URLs

Gets an HLS VMAP with static URLs for the renditions and other assets. Note that the URLs carry a token, and are good for the TTL of the token. Also, VMAPS can only be retrieved if the JWT includes an ssai claim - see Creating a JSON Web Token. Version 2 of the API only

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
bcov_auth
required
string

The value is a JWT (JSON Web Token) - see Static URL Delivery and Creating a JSON Web Token

config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Get an DASH VMAP with static URLs

Gets an DASH VMAP with static URLs for the renditions and other assets. Note that the URLs carry a token, and are good for the TTL of the token. Also, VMAPS can only be retrieved if the JWT includes an ssai claim - see Creating a JSON Web Token. Version 2 of the API only

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
bcov_auth
required
string

The value is a JWT (JSON Web Token) - see Static URL Delivery and Creating a JSON Web Token

config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Get the highest bitrate MP4 rendition

Gets the MP4 rendition of the video that has the highest bitrate Version 2 of the API only

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
bcov_auth
required
string

The value is a JWT (JSON Web Token) - see Static URL Delivery and Creating a JSON Web Token

config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Get the lowest bitrate MP4 rendition

Gets the MP4 rendition of the video that has the lowest bitrate Version 2 of the API only

path Parameters
account_id
required
string

Video Cloud account ID

video_id
required
string

Video Cloud video ID

query Parameters
bcov_auth
required
string

The value is a JWT (JSON Web Token) - see Static URL Delivery and Creating a JSON Web Token

config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Playlists

Operations for retrieving playlists.

Get Playlist by ID or Reference ID

Gets a playlist object for an account, based on playlist ID or reference ID. Note that playlists may contain up to 1000 videos. By default, only the first 20 are returned. You can use the limit and offset parameters to control how many (up to 1000) and which videos are returned for a request

path Parameters
account_id
required
string

Video Cloud account ID

playlist_id
required
string

Video Cloud playlist ID

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 20

The number of videos to return

offset
integer >= 0
Default: 0

The number of videos to skip - used to page multiple sets of videos. Note that the maximum number of videos that can be returned by the Playback API is 1000. To return more than 1000 videos, you must use the CMS API.

ad_config_id
string
config_id
string

include and set equal to the delivery rules id in order to have the delivery rules applied

header Parameters
Authorization
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

BCOV-Policy
required
string

BCOV-Policy {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key if you are using the q parameter.

Accept
required
string

application/json;pk=policy_key (there are 3 ways to authenticate — use one of these three headers) See Policy API Overview or Policy Keys for information on getting policy keys

Responses

Response samples

Content type
application/json
{}