Contact Support | 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 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.

    Sample Search Strings - v1 Playlists
    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)
    Sample Search Strings - v2 Playlists
    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 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:

    https://cms.api.brightcove.com/v1/accounts/{account_id}/playlists/videos?limit=100&offset=100

    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.


    Page last updated on 19 Aug 2021