Introduction
Playlists allow you to group a set of related videos together so that they can be loaded into a player and watched as a group. The CMS API contains a set of write methods you can use to create, update, or delete playlists:
Authentication
Requests to the CMS API require an authorization header which contain your access tokens. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.
GET playlists
Before we get into creating playlists, let's see how we can retrieve data for existing playlists in your Video Cloud account.
Request
https://cms.api.brightcove.com/v1/accounts/{account_id}/playlists
Response
(We set the limit on this request to 1 to keep the response small.)
[
{
"id": "5282200243001",
"account_id": "1752604059001",
"created_at": "2017-01-15T15:30:09.847Z",
"description": "Do not delete",
"favorite": true,
"name": "Playlist for Alltime Views Sample",
"reference_id": null,
"type": "EXPLICIT",
"updated_at": "2017-01-15T17:49:07.633Z",
"video_ids": [
"4825279519001",
"4845831078001",
"4825296720001",
"4454620115001",
"5141730843001",
"4793962133001",
"4454620113001",
"4511340777001",
"5045678909001"
]
}
]
Playlist types
There is one EXPLICIT (manual) playlist type for which you specify the videos to be included as an array of video ids. There are also seven smart playlist types - the smart playlist types differ in how they order a set of videos that are selected dynamically using a search string. The table below shows all the playlist types.
| Type | Description |
|---|---|
EXPLICIT |
A manual playlist. The included videos and the order of their appearance are defined by an array of video ids. |
ACTIVATED_OLDEST_TO_NEWEST |
A smart playlist in which the selected videos are ordered by activation date (ascending). |
ACTIVATED_NEWEST_TO_OLDEST |
A smart playlist in which the selected videos are ordered by activation date (descending). |
ALPHABETICAL |
A smart playlist in which the selected videos are presented in alphabetical order by name. |
PLAYS_TOTAL |
A smart playlist in which the selected videos are ordered by the number of all-time plays (descending). |
PLAYS_TRAILING_WEEK |
A smart playlist in which the selected videos are ordered by the number of plays in the previous week (descending). |
START_DATE_OLDEST_TO_NEWEST |
A smart playlist in which the selected videos are ordered by the scheduled start date (ascending). |
START_DATE_NEWEST_TO_OLDEST |
A smart playlist in which the selected videos are ordered by the scheduled start date (descending). |
Search field
For all the smart playlist types, the collection of videos is assembled dynamically based on the search field value for the playlist. The search field value must be a valid search string value for the CMS API. This validation depends on the search_syntax value (either v1 [default] or v2) set for the playlist; v2 playlists will allow search v2 syntax
| Search String | Description |
|---|---|
+tags:bird |
Returns videos that have the tag "bird" |
+tags:bird,woodland |
Returns videos that have both the tags "bird" and "woodland" |
tags:bird,woodland |
Returns videos that have either of the tags "bird" or "woodland" (note: leaving the + sign out of the search string makes the difference) |
| Search String | Description |
|---|---|
+tags:bird |
Returns videos that have the tag "bird" |
+name:bird |
Returns videos that have "bird" in the title |
(+custom_fields:bird)%20AND%20(NOT%20tags:woodland) |
Returns videos that have the value "bird" for some custom field, but do NOT have the tag "woodland" |
Get count of videos
You can get a count of the videos in a playlist (either smart or manual) using the counts endpoint:
https://cms.api.brightcove.com/v1/accounts/account_id/playlists/playlist_id/videos
Create a playlist
To create a new playlist, you make a POST request to:
https://cms.api.brightcove.com/v1/accounts/{account_id}/playlists
Request body
You can include many (but not all!) of the video metadata fields in your request. You must include at least a name and type for the playlist. Below are two examples, one creating an EXPLICIT playlist, the second creating a smart playlist of type ACTIVATED_NEWEST_TO_OLDEST, including videos that have two tags:
For EXPLICIT playlist
{
"type": "EXPLICIT",
"name": "My manual playlist",
"video_ids": [
"5289680419001",
"5289693763001",
"5289680417001",
"5288472314001"
]
}
For smart v1 playlist
{
"type": "ACTIVATED_NEWEST_TO_OLDEST",
"name": "My smart playlist",
"search": "+tags:bird-tags:sea"
}
For smart v2 playlist
{
"type": "ACTIVATED_NEWEST_TO_OLDEST",
"name": "My smart playlist",
"search": "+name:bird",
"search_syntax": "v2"
}
See the API Reference for all fields that can be used in creating playlists.
Update a playlist
Updating a playlist is very similar to creating one. The only differences are the request method ( PATCH instead of POST) and the playlist id appended to the URL. The fields for the request body are exactly the same.
Request URL
https://cms.api.brightcove.com/v1/accounts/account_id/playlists/playlist_id
Find the complete details in the API Reference.
Delete a playlist
To delete a playlist, make a request using the DELETE method to:
https://cms.api.brightcove.com/v1/accounts/account_id/playlists/playlist_id
(This is the same URL used to update a playlist.)
Find the complete details in the API Reference.