This page has moved - you will be directed to the new location in 1 second. Please update your bookmarks!

API docs by Redocly

Playback API Reference (1.0.0)

Download OpenAPI specification:Download

**Note: this the reference for the Playback API v1 - almost all accounts have been migrated to the Playback API v2. Unless you know that you account is still on v1, you should use the Playback API v2 reference Reference for the Brightcove Playback API, used for client-side access video and playlist information.

Customers using IP Restriction must use https://edge-elb.api.brightcove.com/playback/v1 instead of the standard URL (Use edge-elb.api... vs the normal edge.api...). To learn how to restrict playback for all the players in an account, see the Restricting Video Playback Using IP Address document.

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 General Documentation.

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

Videos

Operations for retrieving videos.

Get Video by ID or Reference ID

Gets a video object based on a video ID or 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
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.

BCOV-Policy
required
string

: {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key.

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 .. 100 ]
Default: 20

The number of videos to return

offset
integer >= null
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
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.

BCOV-Policy
required
string

: {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key.

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
[]

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.

path Parameters
account_id
required
string

Video Cloud account ID

playlist_id
required
string

Video Cloud playlist ID

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

The number of videos to return

offset
integer >= null
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
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.

BCOV-Policy
required
string

: {policy_key} (there are 3 ways to authenticate — use one of these three headers). You need to use a search-enabled Policy Key.

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
{}
Page last updated on 07 Jul 2023