support Contact Support | system status System Status
Page Contents

    Managing Playlists Using the CMS API

    This topic describes how to create, update, or delete playlists using the CMS API.

    Introduction

    Sample Playlist

    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.

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

    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.

    Page last updated on 28 Sep 2020