Overview: CMS API

API reference

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

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
or
video-cloud/video/all
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:
video-cloud/playlist/read
video-cloud/playlist/create
video-cloud/playlist/update
video-cloud/playlist/delete
or
video-cloud/playlist/all
Notifications:
- video-cloud/notifications/all (for 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

The CMS API is intended for integrations and publishing workflows. You cannot make client-side calls to this API from a public web page, as doing so would involve exposing your client credentials for the API (for that reason, the API is not CORS-enabled). You can make calls from a client-side (web) app, provided that you route the API calls through a server-side proxy. Brightcove Learning Services provides several sample apps that use this approach, and a guide to building this kind of app.

If you are going to be retrieving all your videos or large sets of videos, be sure to see the note on large data sets.

Avoid hard-coded URLS

URLs for thumbnails, posters, video files, and other media should never be hard-coded in your pages or applications. The CMS API will always return the current URLs for media files, but the URLs themselves are subject to change. You should use the CMS API ( or Playback API ) requests to retrieve these URLs each time the page loads, or cache them for no more than six hours.

Caching video and image URLs

You can cache URLs for videos and images to improve page performance, but the cache must be refreshed regularly. If you cache the URLs you retrieve to improve the performance of your pages, be sure to refresh the cache by repeating the API calls at least once every six hours.

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 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`

Search videos

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=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.

Note the search term playable:true/false that you can use to return only videos that are playable (or not):

        https://cms.api.brightcove.com/v1/accounts/:account_id/videos?q=%2Bplayable:true

This query requires that returned videos be playable (not deactivated, not scheduled, and not lacking playable renditions).

If you are searching for videos that are not playable, use q=%2Bplayable:false.

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:

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

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

Note: limit and offset do not work when you are requesting the videos belonging to a playlist - this request will always return all videos in the playlist.

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:

Make a count request to get the total number of videos in your result set.
```
      /accounts/578380111111/counts/videos?q=tags:nature
```
Use the limit and offset parameters to return groups of data from your result set.
```
      /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
```
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]

Prefix the field name with a minus sign ( sort= -field_name) for descending order.

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]

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)

Prefix the field name with a minus sign ( sort= -field_name) for descending order.

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:

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

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

Notifications

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.

video-change events are triggered by automated system processes as well as user actions, so these events will not always corresponds to changes you made to video properties in Studio or via the APIs.

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