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.

Notes on usage

General Information

Base URL

The base URL for the CMS API is:

https://cms.api.brightcove.com/v1

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:

https://cms.api.brightcove.com/v1/accounts/{account_id}

Authentication

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 details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

Operations

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/read
    video-cloud/video/create
    video-cloud/video/update
    video-cloud/video/delete
    video-cloud/video/all
    video-cloud/video/assets/read
    video-cloud/video/assets/create
    video-cloud/video/assets/update
    video-cloud/video/assets/delete

  • Playlist data:

    video-cloud/playlist/read
    video-cloud/playlist/create
    video-cloud/playlist/update
    video-cloud/playlist/delete
    video-cloud/playlist/all

  • 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 queries 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.

Methods

Currently the API supports the following request types:

  • GET
  • POST
  • PATCH
  • PUT
  • DELETE

Parameters

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 details
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 Using the CMS API: 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=type:ACTIVATED_OLDEST_TO_NEWEST
  • q=type:ALPHABETICAL
  • 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 offsetis the number of items to skip. For example, for a search like this:

/videos?q=updated_at:2014-01-01..2014-06-30&limit=25&offset=50

This will return videos 51-75 of the total result set, assuming the total result set has at least 75 videos.

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

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
  • schedule_ends_at
  • state
  • plays_total[1-2]
  • plays_trailing_week[1-2]

Notes

  • [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 page_size (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_by 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.

Assets

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 /assets can be used to add and update remote assets. 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.

Notifications

You can receive notifications when video_change events occur in your video library. 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.

Firewalls

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 http://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.

Related topics