Migrating from the Media API to the CMS API

This topic provides guidance on migrating your apps from the Media API to the CMS API. There are several good reasons why you should migrate to the CMS API.

  • The CMS API provides cacheless read access to your video and playlist data, so you always get the latest data
  • The CMS API provides functionality and data that are not available via the Media API
  • We are actively working on enhancing the functionality and performance of the CMS API, while the Media API is in maintenance mode, and no further enhancements are planned
  • The Brightcove OAuth service used by the CMS API provides a greater level of security and more granular access control

Video Fields

The table below lists video fields that are different in CMS API responses from those in the Media API. Note that only those fields that are different are listed - video fields not listed are the same for both APIs.

Media API Field CMS API Field Type Can be updated in CMS API? Description
accountId account_id String no
adKeys ad_keys String yes key/value pairs for ad requests
captioning text_tracks Array of HTML5-style text tracks yes WebVTT assets; more details here
   id String no
   src String yes address of the track file (URL)
   srclang String yes language of the track, e.g. "en"
   label String yes a user-readable title
   kind String yes how the track is meant to be used: "subtitles", "captions", "descriptions", "chapters", "metadata"
   mimetype_ String yes mime type of the track file, e.g. "text/vtt"
   assetid_ String no null if asset is remote
   sources Array no
     src String yes address of the track file (URL)
   default Boolean yes indicates that the track should be enabled by default. Should only be true on one track.
creationDate created_at Number, milliseconds from epoch no
cuePoints cue_points Array of Maps yes
   cuepoints.0.id_ String yes
   cuepoints.0.force stop Boolean yes
   cuepoints.0.metadata_ _String yes code point only_
   cuepoints.0.name_ String yes
   cuepoints.0.time_ Float yes
   cuepoints.0.type_ String yes
customFields custom_fields Map of field-value pairs (Strings) yes
dashManifestUrl dash manifestid String no Was an URL, is now an ID
dashRenditions n/a See sources
digitalMaster digital masterid String no Was an object; is now an ID
economics economics String enum yes FREE, AD_SUPPORTED
FLVURL n/a See sources
geo Map of property-value pairs yes
geoFilteredCountries    geo.countries Array of country code Strings yes
geoFilterExclude    geo.excludecountries_ Boolean yes
geoRestricted    geo.restricted Boolean yes
geoFiltered n/a
hdsManifestUrl n/a See sources
HDSRenditions n/a See sources
HLSURL n/a See sources
id id String no Was a Long, is now a String
IOSRenditions n/a See sources
itemState state String enum yes ACTIVE, INACTIVE, PENDING, DELETED
lastModifiedDate updated_at Number, milliseconds from epoch no
length duration Number, milliseconds no
link Map of property-value pairs yes
linkUrl    link.url String yes
linkText    link.text String yes
logoOverlay n/a
longDescription long_description String yes
name name String yes
playsTotal n/a
playsTrailingWeek n/a
publishedDate n/a
referenceId reference_id String yes
renditions n/a See sources
schedule Map of property-value pairs yes
endDate    schedule.endsat_ String in ISO-8601 date format yes
startDate    schedule.startsat_ String in ISO-8601 date format yes
sharing Map of property-value pairs no
sharedByExternalAccount    sharing.byexternal acct Boolean no
   sharing.byid_ String no pub ID that originated the share
   sharing.sourceid_ String no video ID of the original video (sharer's copy)
sharedToExternalAccount    sharing.toexternal acct Boolean no
   sharing.byreference_ Boolean no
shortDescription description String yes
smooth clientmanifest_id String no
smoothManifestUrl smooth servermanifest_id String no Was a URL, is now an ID
smoothRenditions n/a See sources
tags tags Array of tags (Strings) yes
images Map of property-value pairs no
thumbnail    images.thumbnail Map no
     images.thumbnail.assetid_ String no
     images.thumbnail.src String URL no
     images.thumbnail.sources Array of Maps no
       images.thumbnail.sources.assetid_ String no
thumbnailUrl        images.thumbnail.sources.src String URL no
       images.thumbnail.sources.height Number no
       images.thumbnail.sources.width Number no
videoStill    images.poster Map no
     images.poster.assetid_ String no
     images.poster.src String URL no
     images.poster.sources Array of Maps no
       images.poster.sources.assetid_ String no
videoStillUrl        images.poster.sources.src String URL no
       images.poster.sources.height Number no
       images.poster.sources.width Number no
original_filename String no Will be null for remote asset videos
version n/a See the etag header on the request reponse
videoFullLength n/a See sources
WMVRenditions n/a See sources
n/a complete Boolean no
n/a folder_id String no Mongo-type ID of folder to which the video belongs

Methods

The table below shows Media API methods and the equivalent operation in CMS (or Dynamic Ingest) API

Media API CMS API Verb + Endpoint
Video Methods
search_videos GET /accounts/account_id/videos + search
find_modified_videos GET /accounts/{account_id}/videos?sort=%2Dupdated_at
find_video_by_id GET /accounts/{account_id}/videos/{video_id}
find_videos_by_ids GET /accounts/{account_id}/videos/{video_id1,video_id2,...}
find_video_by_reference_id GET /accounts/{account_id}/videos/ref:{reference_id}
find_videos_by_reference_ids /accounts/{account_id}/videos/ref:{reference_id} (iterate over reference ids)
find_all_videos GET /accounts/account_id/videos
find_related_videos GET /accounts/account_id/videos + search (search according to the relationships you want)
create_video POST /accounts/account_id/videos + Dynamic Ingest API
update_video PATCH /accounts/{account_id}/videos/{video_id}
delete_video DELETE /accounts/{account_id}/videos/{video_id}
add_captioning Use Dynamic Ingest - Text Tracks
add_image Dynamic Ingest - Images
add_logo_overlay Either use the Player Overlay Plugin or burn-in logos through a custom Ingest Profile
delete_captioning PATCH /accounts/{account_id}/videos/{video_id}
get_upload_status GET /accounts/{account_id}/videos/{video_id} (status is included in the response)
remove_logo_overlay No equivalent - see notes on add_logo-overlay above
share_video not yet implemented
unshare_video not yet implemented
Playlist Methods
find_all_playlists GET /account/{account_id}/playlists
find_playlist_by_id GET /account/{account_id}/playlists/{playlist_id}
find_playlist_by_reference_id GET /account/{account_id}/playlists/ref:{reference_id}
find_playlists_by_ids GET /account/{account_id}/playlists/{playlist_id1,playlist_id2,...}
find_playlists_by_reference_ids GET /account/{account_id}/playlistsq=reference_id:refId1%2Breference_id:refId2
find_playlists_for_player_id no equivalent
create_playlist POST /account/{account_id}/playlists
update_playlist PATCH /account/{account_id}/playlists/{playlist_id}
delete_playlist DELETE /account/{account_id}/playlists/{playlist_id}