Managing Playlists Using the CMS API

This topic describes how to create, update, or delete 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.

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"
        ]
      }
    ]

Note that you can also add search criteria to get a specific set of playlists, and use the /counts/playlists endpoint to get a count of how many playlists there are in the account. See the API Reference to see all options.

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.

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 for a tag search string for the CMS API. Below are some examples with explanations of the videos they will return.

Sample Search Strings
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)

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 playlist

    {
      "type": "ACTIVATED_NEWEST_TO_OLDEST",
      "name": "My smart playlist",
      "search": "+tags:bird-tags:sea"
    }

Note that all playlists have a limit of 100 videos, but you can set that limit lower for smart playlists by using the limit field.

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.

Note that you cannot change an EXPLICIT playlist to another type, or change another type of playlist to EXPLICIT.

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.