Overview: CMS API

In this topic, you will get an overview of the CMS API. The CMS API provides uncached read access to the data. This is important for time-sensitive publishing workflows because you make changes to videos and playlists using the CMS API and quickly read the data to verify that is correct.

API reference

Also see the API Reference.

General Information

Base URL

The base URL for the CMS API is:


Account path

In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:



Authentication for requests requires an Authorization header :

        Authorization: Bearer {access_token}

The access_token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For more details,see the Brightcove OAuth Overview.

The easiest way to create client credentials is through the Brightcove Studio admin pages. For detailed instructions, see Managing API Authentication Credentials


When you request client credentials, you will need to specify the type of account access or operations that you want. The following is a list of the currently supported operations for the CMS API :

  • Video data:

    video-cloud/video/assets/delete (Only needed if you want to delete digital masters - note that you cannot get this permission when create credentials in Studio. It must be done through the OAuth API or the Sample App created by Brightcove Learning Services.)

  • Playlist data:


  • Notifications:

Rate limiting

This CMS API provides uncached read access to the data. This is important for time-sensitive publishing workflows because you make changes to videos and playlists using the CMS API and quickly read the data to verify that is correct.

The CMS API is not appropriate for high scale runtime usage (such as accessing videos on a high traffic public web page). For high traffic applications, you must use a cached interface such as : the Playback API , Gallery, Players, or the Native SDK's.

To ensure the performance of the Video Cloud system, no more than 20 concurrent calls to the CMS API are allowed per account. Access frequency should be less than 10 requests per second.

If multiple applications will be integrating to the CMS API for an account, then these applications should have back-off and retry logic to handle instances where concurrency limits or rate limits are reached.

If either the rate or concurrency limit is exceeded, a 429 - TOO_MANY_REQUESTS error will be returned.

Reference id conflicts

To insure the uniqueness of reference ids, the CMS API locks the id for up to 3 minutes after any operation on the video it is assigned to. This can result in 409 errors being returned when you attempt to retry a request that fail too quickly, or when you try to reuse a reference id too soon after deleting the video it was previously assigned to. See the Error Message Reference for more details.

Video asset limit

There is a limit of 1,000 assets per video. Assets include renditions, audio tracks, text tracks, and images, as well as the digital master. Renditions and images rarely total more than 10-15 assets, so even if you had separate audio tracks and text tracks for 150 different languages, you would still have less than 350 assets.

Notes on usage


Currently the API supports the following request types:

  • GET
  • POST
  • PUT


Note that all parameters are optional. Except where noted, they apply to GET requests for videos and playlists.

GET Request Parameters
Parameter Description
q Query string for searches - see Search syntax for more information
limit Number of videos to return - must be an integer between 1 and 100. Default: 20
offset Number of videos to skip (for paging results). Must be a positive integer. Default: 0
sort A string that specifies the field to sort by. Start with - to sort descending. If a value for q is provided, then the default sort is by "score" (relevance of the search results to the original query). If no value for q is provided, then the default sort is by updated_at descending. The following fields are valid for sort: name, reference_id, created_at, published_at, updated_at, schedule_starts_at, schedule_ends_at, state, plays_total, and plays_trailing_week

Brightcove's CMS API provides a programmatic way to search for videos in your Video Cloud library.

To perform basic and complex searches on your video data, you will use the q parameter:

        https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q={search terms}

For details on how to search for videos, see the Search Videos document.

For playlists, the supported values for the search string are more limited. You can currently search by type, name, description, and reference_id. Here are some example valid searches:

  • q=type:EXPLICIT
  • q=bears+otters (name, description, or reference ID must contain either "bears" or "otters")
  • q=%2Bname:bears+type:EXPLICIT (name must contain "bears")

See Search Playlists for more details.

Paging results

Use the limit parameter to specify how many items you want to return on a request - up to 100. You can then use the offset parameter to page through result sets that are larger than the limit. The offset is the number of items to skip.

For example, the following search returns videos 51-75 of the total result set, assuming the total result set has at least 75 videos:


The limit and offset parameters can be used for both videos and playlists.

Paging best practice

Because there may be concurrent modification operations going on with the CMS API, it is recommended to follow these steps when paging through your result set:

  1. Make a count request to get the total number of videos in your result set.
  2. Use the limit and offset parameters to return groups of data from your result set.
  3. Note that some pages may have fewer than 20 videos. You will know you have reached the end of the result set when you have asked for as many videos as in the first count request.

To summarize, keep retrieving pages until you get a video count equal the original count request, since this number should err on the side of overestimation. Ask for:

      count / page-size + 1 page

Sorting video results

Use the parameter sort=field_name to specify how the results should be sorted - you can sort both video and playlists. You can sort on the following video fields: [1-1]

  • name
  • reference_id
  • created_at
  • published_at
  • updated_at
  • schedule_starts_at (note: this is the sort field - the search field is schedule.starts_at )
  • schedule_ends_at (note: this is the sort field - the search field is schedule.ends_at )
  • state
  • plays_total [1-2]
  • plays_trailing_week [1-2]


  • [1-1] If you do not provide a sort value for a video search call, the results will be sorted by relevance. If you do not provide a sort value for a GET videos call, the results will be sorted by updated_at descending.
  • [1-2] You can sort on plays_total or plays_trailing_week, but these fields are not included in the results

Sorting playlist results

You can sort playlists on the following fields:

  • name
  • updated_at (default)

All videos and large data sets

If you are retrieving all the videos in your account, or a large number of videos, there are some things you must be aware of:

  1. You may be tempted to use the largest allowed limit (100), but it's better to retrieve videos in batches of 25 or less to minimize the possibility of API requests timing out
  2. As you are paging through large data sets, it is possible that the video data may be updated during the operation, which could cause items to shift in responses:
    • You might see an item repeated on successive pages
    • An item might be missed, as it has shifted to a previous response set

    To account for the first possibility, your app should de-dupe the complete item list after you have finished retrieving videos. To handle the second possibility, you need to compare the total number of items retrieved (after de-duping) to the number you were expecting, and then rerun the requests, sorting the results by last_modified_date (descending) - you shouldn't need to retrieve more than one batch to pick up missed items.

  3. You can decrease the likelihood of the scenarios in the previous item by sorting the returned results appropriately. The default sorting by relevance for searches is based on a complex algorithm that looks combinations of keywords, tags, and custom field values. If you are searching for videos based on multiple keywords, tags, and/or custom fields, sort by relevance is exactly what you want. However, if you are just trying to retrieve all or a large set of your videos, setting the sort parameter explicitly will give you more control over the order of the returned items.

Video operations

Video operations include:

  • Get a count of videos or search results
  • Get all videos
  • Get one or more videos by id or reference id
  • Create, retrieve, update, and delete videos
  • Search for videos
  • Get video sources, images, and the digital master information
  • Get the playlists that a video belongs to
  • Remove the video from all playlists

Details of the video operations can be found in the API Reference.

Playlist operations

Playlist operations include:

  • Get a count of playlists
  • Get all playlists
  • Create, update, and delete playlists
  • Get a count of videos in a playlist
  • Get the videos in a playlist

Details of the playlist operations can be found in the API Reference.


Asset operations allow you to manage assets including renditions, manifests, images, and text tracks. To ingest assets, you must use the Dynamic Ingest API. The POST and PATCH operations for the CMS API /assets can be used to add and update remote assets. CMS API GET operations will work for both ingested and remote assets.

  • Add, update, or delete renditions
  • Add, update, or delete a metadata for the digital master
  • Add, update, or delete manifests for segmented video types such as HLS
  • Add, update, or remove poster and thumbnail images
  • Add, update, or remove WebVTT text tracks or DFXP captions

Details of the asset operations can be found in the API Reference.

Custom field operations

There is currently one custom field operation:

  • Get all custom fields for an account

Details of the custom field operations can be found in the API Reference.

Folder operations

Folder operations allow you to:

  • Get a list of folders
  • Create, update, and delete folders
  • Get a list of videos in a folder
  • Add a video to a folder
  • Remove a video from a folder

Details of the folder operations can be found in the API Reference.


You can receive notifications when video-change events occur in your video library or master-video-change notifications when a shared video updates its assets automatically after the master video updates it. Notifications will be sent to the URL you specify, which should point to an application capable of handling HTTP POST requests.

Notification failures

The notification system treats any 4xx or 5xx return from the customer server as a retriable failure. Failing callbacks will be retried up to 20 times, with an exponentially increasing delay between subsequent callbacks. The first few retries will happen within minutes of the initial callback attempt. If the callback continues failing, and we get all the way out to the 20th retry, the retry delay will be a few days.


In case your organization has a strict policy regarding sources of incoming traffic through your firewall, we allow all AWS East region IPs. This is subject to change, so all AWS IPs should be whitelisted. See https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html for more information.

Notification operations

The operations currently available for notifications are:

  • Create subscriptions
  • Get one or all subscriptions
  • Delete a subscription

Details of the notification operations can be found in the API Reference.