Overview: Social Syndication API

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

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="/{{account_id}}/default_default/index.html?videoId={{asset.id}}">
      

• 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>{{asset.published_at | toUTC | date: "%a, %d %b %Y
          %H:%M:%S %Z"}}</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" | toEpoch }}</toEpochMillis>
          <toEpochSeconds>{{"now" | toEpoch | divided_by : 1000 }}</toEpochSeconds>
          <thirtyDaysAgo>{{'now' | toEpoch | minus:2592000000 | fromEpoch }}</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" | toEpoch | fromEpoch }}</fromEpochMillis>
          <thirtyDaysAgoAltFormat>{{1580917253024 | fromEpoch | date:"%Y-%m-%d" }}</thirtyDaysAgo>
        
      

produces an output like the following:

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