support Contact Support | system status System Status
Page Contents

    Overview: Social Syndication API

    The Social Syndication API is a publicly accessible API that allows syndications to be created, managed, and used to generate dynamic feeds (such as MRSS feeds) from a VideoCloud video catalog.

    In this document

    Related documents

    Introduction

    The Brightcove Syndication Configuration API is a publicly accessible API that allows syndications to be created, managed, and used to generate dynamic feeds (such as MRSS feeds) from a Video Cloud account's video catalog.

    There is also an associated Syndication Feed API that can be used to retrieve a feed associated with a syndication.

    Availability

    The syndication APIs are available to all Video Cloud customers who have access to the Platform APIs.

    API reference / base URL / headers

    The Configuration API Reference contains all the details about the available operations, fields, and parameters.

    The base URL is:

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

    All requests must be authenticated via an Authorization header:

    Authorization: Bearer {your_access_token}

    See the next section on authentication for information on access tokens.

    For any request that sends a request body, you must also include a Content-Type: application/json header.

    Authentication

    Access to the Configuration API requires specification of a bearer token from the Brightcove OAuth service in the request's Authorization header. The various API methods also require one of the following operations (depending upon the method accessed) to be specified for the credentials in question:

    • video-cloud/social/mrss/read
    • video-cloud/social/mrss/write

    These operations can be configured via the API Authentication section of the Studio Admin Module:

    Social Syndication Permissions
    Social Syndication Permissions

    If you prefer, you can also create credentials via the OAuth API:

    Syndication Resource

    The syndication resource is an object that defines how the syndication will be created. Here is a sample request body for creating a syndication resource:

      {
        "name": "80s music videos syndication",
        "type": "advanced",
        "include_all_content": false,
        "include_filter": "tags:mytag",
        "title": "80s Music Videos",
        "description": "Amateur Tokyo drift!",
        "destination_url": "http://mywebsite.com",
        "keywords": "80s, rock",
        "author": "Rick Astley",
        "category": "Music",
        "album_art_url": "http://my_album_art.jpg",
        "explicit": "no",
        "owner_name": "http://my_album_art.jpg",
        "owner_email": "rick@astley.com",
        "language": "en-us",
        "fetch_sources": true,
        "fetch_digital_master": false,
        "fetch_dynamic_renditions": true,
        "sort": "-created_at",
        "content_type_header": "application/xml"
      }

    The response will add some read-only fields:

      {
        "id": "7f594cd3-4853-4174-aff3-203c3e99e9c2",
        "name": "80s music videos syndication",
        "type": "advanced",
        "include_all_content": false,
        "include_filter": "tags:mytag",
        "title": "80s Music Videos",
        "description": "Amateur Tokyo drift!",
        "syndication_url": "https://social.feeds.brightcove.com/v1/accounts/9999999999999/mrss/accounts/{account_id}/mrss/syndications/7f594cd3-4853-4174-aff3-203c3e99e9c2/feed",
        "destination_url": "http://mywebsite.com",
        "keywords": "80s, rock",
        "author": "Rick Astley",
        "category": "Music",
        "album_art_url": "http://my_album_art.jpg",
        "explicit": "no",
        "owner_name": "http://my_album_art.jpg",
        "owner_email": "rick@astley.com",
        "language": "en-us",
        "fetch_sources": true,
        "fetch_digital_master": false,
        "fetch_dynamic_renditions": true,
        "sort": "-created_at",
        "content_type_header": "application/xml"
        }
    Syndication Resource
    Field Type Read-Only Description
    id String Yes generated when syndication is created
    name String No an internal name for this syndication - required for POST requests
    content_type_header String No If set, overrides the Content-Type header returned by the feed server for this syndication's feed. Otherwise the feed defaults to a syndication type-specific header value
    include_all_content Boolean No If true, all catalog videos are included in this syndication
    include_filter String No Must be specified if include_all_content is false. Value is a CMS API search string using the CMS API video search syntax v2. All syntax rules apply - the only difference is that the search string is entered as the include_filter value rather than a ?query= param.
    type String No The type of feed that will be generated. The universal type allows custom feeds to be generated by an uploaded feed template. Valid values: advanced, google, iphone, ipad, mp4, itunes, roku, source, universal. Required for POST requests
    title String No The title of this feed. This is included inside of the <channel> tag for applicable feed types
    description String No The description of this feed. This is included inside of the <channel> tag for applicable feed types
    syndication_url String Yes The URL of this syndication's MRSS feed
    destination_url String No The URL to be included inside of the <channel> tag for applicable feed types
    keywords String No comma-delimited list, only used for itunes and (potentially) universal feeds
    author String No only used for itunes and (potentially) universal feeds
    owner_name String No only used for itunes and (potentially) universal feeds
    language String No only used for itunes and (potentially) universal feeds - two-letter language code in lower-case, such as "en"
    owner_email String No only used for itunes and (potentially) universal feeds
    category String No only used for itunes and (potentially) universal feeds. To specify a category with a subcategory, separate them by a colon (:) - for example: "Business:Business News". "category": "Music"
    album_art_url String No URL for image, only used for itunes and (potentially) universal feeds
    fetch_sources Boolean No For universal templates, whether to fetch video source metadata - if the template doesn't need this metadata, performance can be improved by specifying false; could be empty if no usable source exists
    fetch_digital_master Boolean No For universal templates, whether to fetch video digital master metadata - if the template doesn't need this metadata, performance can be improved by specifying false; could be empty if no digital master exists
    fetch_dynamic_renditions Boolean No For universal templates, whether to fetch video dynamic rendition metadata - if the template doesn't need this metadata, performance can be improved by specifying false
    sort String No A CMS video sorting specifier indicating the desired feed results return order. CMS-supported values like name, reference_id, created_at, published_at, updated_at, schedule.starts_at, schedule.ends_at, state, plays_total, and plays_trailing_week can be specified. To sort in descending order, preface the value with a minus (-) sign, i.e. -created_at, specified, the feed will be sorted by most recent updated_at date by default.

    See CMS API video search syntax v2 for details on the include_filter property.. All search syntax rules apply - the only difference is that the search string is entered as the include_filter value rather than a ?query= param.

    Operations

    See the API Reference for full details of the operations available:

    The following actions are supported:

    Error messages

    If any API requests fails, an error message will be returned. Error responses will look like the following:

      [
        {
          "error_code" : "Application error code 1",
          "message" : "Application error message 1"
        }, {
          "error_code" : "Application error code 2",
          "message" : "Application error message 2"
        }
      ]

    Create a syndication

    Method: POST

    Endpoint: /accounts/{account_id}/mrss/syndications

    Sample request body:

      {
        "name": "my mp4 feed",
        "type": "mp4"
      }

    Note that the name and type fields are required. Others are optional.

    Update a syndication

    Method: PATCH

    Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}

    Sample request body:

      {
        "name": "my new name"
      }

    Note that the request body for PATCH requests must not include the fields (type, id and syndication_url).

    Delete a syndication

    Method: DELETE

    Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}

    Get all syndications for an account

    Method: GET

    Endpoint: /accounts/{account_id}/mrss/syndications

    Get a specific syndication

    Method: GET

    Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}

    Set the template for a universal syndication

    Method: PUT

    Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}/template

    Sample request body:

      <feed header>My Feed Header</feed header>
      

    The above template would generate a feed similar to:

      <feed header>My Feed Header</feed header>
        <item>
          <title>Title for Video 1</title>
          <video_info>Description for Video 1</video_info>
        </item>
        <item>
          <title>Title for Video 2</title>
          <video_info>Description for Video 2</video_info>
        </item>

    Get the template for a universal syndication

    Method: GET

    Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}/template

    Get the feed associated with a syndication

    The feed url can be obtained from the syndication's syndication_url field, or constructed manually. Note that the Syndication Feed API can also be used to retrieve a feed without authentication.

    Method: GET

    Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}/feed

    Universal Template Language

    Universal syndications allow catalog data to be merged with a custom template to generate any kind of feed desired. The supported template language is Liquid. Feeds for the default syndication types are generated using the same types of templates, You can see the templates provided as samples to help you build custom templates if you need to.

    The sections below identify the syndication, asset, source, and digital master properties you can use, as well as an extension to Liquid added for convenience.

    To see all Video Cloud video metadata fields with descriptions, to go the CMS API Video Fields Reference.

    Top level properties

    Derived from Syndication fields

    • album_art_url
    • author
    • category
    • description
    • destination_url
    • explicit
    • keywords
    • name
    • owner_name
    • owner_email
    • subtitle
    • syndication_id
    • syndication_url
    • title

    Video Cloud account id

    • account_id

    VideoCloud default player page url prefix

    Use like this:

      <media:player url="//default_default/index.html?videoId=">
    • player_url

    URL of the feed's next page

    • next_page

    Collection of video assets retrieved from the catalog (see below for details)

    • assets

    Asset properties

    The resources in the assets collection are derived from the video resources returned by the CMS Get Videos API method, and all of the same properties are supported, including but not limited to the following:

    • created_at
    • description
    • duration
    • id
    • images
    • images.thumbnail
    • images.poster
    • long_description
    • name
    • original_filename
    • published_at
    • schedule
    • state
    • tags
    • text_tracks
    • updated_at

    Asset resources also support the following properties:

    • sources (collection of sources for the video - see the next section for source properties)
    • digital_master (will be empty if no digital master exists - see below for the digital master properties)
    • best_mp4_source (the highest quality MP4 source - may be empty if there are no MP4 sources. Properties will be the same as items returned in the sources)
    • hls_source (returns the HLS source - will be empty if none exists)
    • best_dynamic_rendition_quality (returns the video quality of the video's dynamic rendition with the largest frame size, if dynamic rendition metadata has been fetched for the video. Allowable values are "SD", "HD", "FHD", and "UHD".)

    Source properties

    The resources in the sources collection for an asset are derived from the video source resources returned by the CMS Get Video Sources API method. The following properties are supported:

    • app_name
    • asset_id
    • codec
    • container
    • created_at
    • duration
    • encoding_rate
    • height
    • size
    • src
    • stream_name
    • type
    • uploaded_at
    • width

    Digital master properties

    The digital_master resource for an asset is derived from the digital master resource returned by the CMS Get Digital Master Info API method. The following properties are supported:

    • duration
    • encoding_rate
    • height
    • size
    • url
    • width

    Dynamic rendition properties

    The dynamic_renditions resource for an asset is derived from the dynamic renditions returned by the CMS Get Digital Master Info API method. The following properties are supported:

    • rendition_id
    • frame_height
    • frame_width
    • media_type
    • encoding_rate
    • created_at
    • updated_at
    • size
    • duration
    • audio_configuration
    • language
    • variant

    Extensions to Liquid

    toUTC filter

    We have extended our Liquid parser to support a toUTC filter which will parse most standard ISO-8601 datetime string formats and transform them into standard UTC datetime strings. This format is acceptable to Liquid's date filter, which can then be used to reformat the timestamps into datetime strings in any desired format. For example:

      <pubDate></pubDate>

    This produces an output like the following if asset.published_at has a value of 2019-08-09T13:32:52.031Z::

      <pubDate>Fri, 09 Aug 2019 09:32:52 +0000</pubDate>

    toEpoch filter

    The Liquid parser we use does not support the "%s" token in date filters for converting dates to Unix epoch timestamps. To address this, a toEpoch custom filter is provided that can be used to convert valid date specifications to the epoch format. The filter returns a numeric data value representing milliseconds since the epoch that is suitable for input to mathematical filters. For example:

      <toEpochMillis>now</toEpochMillis>
      <toEpochSeconds>0</toEpochSeconds>
      <thirtyDaysAgo>-2592000000</thirtyDaysAgo>

    produces an output like the following:

      <toEpochMillis>1580917253024</toEpochMillis>
      <toEpochSeconds>1580917253</toEpochSeconds>
      <thirtyDaysAgo>2020-01-06T15:40:53.055Z</thirtyDaysAgo>

    fromEpoch filter

    The fromEpoch filter converts numbers representing milliseconds since the epoch to UTC date strings. The filter will also accept a string containing the epoch value digits as an input. The output can be passed to the date filter for reformatting if necessary.

    For example:

      
      <fromEpochMillis>now</fromEpochMillis>
      <thirtyDaysAgoAltFormat>52067-04-10</thirtyDaysAgo>
      

    produces an output like the following:

      
      <fromEpochMillis>2020-02-05T16:09:37.809Z</fromEpochMillis>
      <thirtyDaysAgoAltFormat>2020-02-05</thirtyDaysAgo>

    Page last updated on 28 Sep 2020