Managing Playlists Using the CMS API

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:

• Create a playlist
• Update a playlist
• Delete a playlist

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.

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.

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, while v1 playlists will accept tag search string only. Below are some examples with explanations of the videos they will return.

Get videos in a playlist

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

You can retrieve the videos themselves using a Get Videos in Playlist request. Note that a maximum of 100 videos can be returned for one request, so to get more than 100, you will need to page the results using the limit and offset parameters. For example, to get the second 100 you would use:

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.