On This Page

Overview: CMS API

Product(s)

Video Cloud

Role(s)

API Developer

Task(s)

Manage Videos

Topic(s)

API Overviews

API(s)

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

General Information

Base URL

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 :

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.

Concurrent calls occurs when multiple processes or apps running in parallel are making API requests. Since a request may take more than a second to complete, you may exceed the concurrency limit even though you are not making more 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.

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:

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)

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

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_by parameter explicitly will give you more control over the order of the returned items.

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

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.

Notes:

Any change in video metadata will trigger a video_change event. Changes to assets used by the video will not trigger change events.

In addition to notifications, there are status APIs that allow you to get the status of ingest (ingesting, replacing, or retranscoding) jobs associated with a video.

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.