Client APIs
At its core, SyncTV is an API driven service. The APIs themselves are easy enough for developers to understand, but understanding the ecosystem is a little trickier. We've created the following tutorials to help you get your head around it.

Topics:

  • Media

This document describes the API for creating, reading, updating and deleting media.

Note:
Each call to the SyncTV V2 API described in this section requires an MD5 hash signature.
See the Authorization (User) API for details on generating the MD5 hash signature.
Actions

Url:

  • [GET] /api/v2/media.[xml|json]
  • [GET] /api/v2/containers/:container_id/media.[xml|json]

Returns a list of all media.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following example returns a list of all media.
[GET] https://service_name.synctv.com/api/v2/media.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) offset — Used for pagination of response data (default: 25 items per response). Specifies the offset of the next block of data to receive.
  • (Boolean) active — Filters response by active state (e.g. active=true).
  • (String) sort_order — Defines the sort order of the response. (e.g. sort_order=order_number). Or can be multi-sort (e.g. sort_order[]=order_number&sort_order[]=id. When multi-sorting the url placement determines which is dominant).
  • (String) id — The unique identifier of the media.
  • (String) name — The name attribute of the media.
  • (String) order_number — The order number of the media.
  • (String) available — Timestamp for when the media is available to be purchased.
  • (String) expires — Timestamp when media is no longer available to be purchased.
  • (String) ownerships_count — The media's current ownership count. (Note: This is field is not unique thus not a stable sort. Additional ordering is required to be used with pagination.)
  • (String) created_at — Timestamp for when the media was first created.
  • (String) published_at — Timestamp for when the media was first published.
  • (String) avg_rating — The average user rating (see Activities).
  • (String) avg_price — The average media price, depending offers available for media (see Bundles, Ownership Policy API).
  • (Boolean) sort_descending — Reverse order of sort_order sorting, make it descending.
  • (DateTime) available_on — Filters response by specified available_on timestamp (e.g. available_on=2012-02-15T02:06:56Z).
  • (DateTime) available_begin_date — Filters response to include only items with available_on >= specified timestamp (e.g. available_begin_date=2012-02-15T02:06:56Z).
  • (DateTime) available_end_date — Filters response to include only items with available_on <= specified timestamp (e.g. available_end_date=2012-02-15T02:06:56Z).
  • (DateTime) expire_begin_date — Filters response to include only items with expires_on >= specified timestamp (e.g. expire_begin_date=2012-02-15T02:06:56Z).
  • (DateTime) expire_end_date — Filters response to include only items with expires_on <= specified timestamp (e.g. expire_end_date=2012-02-15T02:06:56Z).
  • (String) named_like — Filters response to include items that contain the specified value in the name field (e.g. named_like=lost).
  • (String) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (String) external_id — Filters response based on the value of the external_id field.
  • (String) key — Filters response based on the meta_data key.
  • (String) value — Filters response based on the meta_data value.
  • (Array) ids — Filters response to within a set of media ids (e.g. ids[]=1&ids[]=2...)..
  • (Integer) clip_id — Filters response to return sub media associated with media id passed as this parameter (e.g. clip_id=2)
  • (Array) any_of_available_platform_ids — Filters response based on the value of available_platform_id field (e.g. any_of_available_platform_ids[]=1&any_of_available_platform_ids[]=2...).
  • (Array) any_of_available_platform_type_ids — Filters response based on the value of the available_platform_id field (e.g. any_of_available_platform_type_ids[]=1&any_of_available_platform_type_ids[]=2...).
  • (String) with_definition — Filters response by definition (e.g. with_definition=hd or with_definition=sd).
  • (Array) any_of_audio_languages — Filters response by audio_languages (e.g. any_of_audio_languages[]="eng"&any_of_audio_languages[]="chn").
  • (Array) all_of_audio_languages — Filters response by audio_languages returning media with exactly the supplied language codes (e.g. all_of_audio_languages[]="eng"&all_of_audio_languages[]="chn").
  • (Array) fields — Filters response by which fields are rendered for each response object. This can include optional fields, like 'bundles' (e.g. fields[]=id&fields[]=bundles).
  • (Array) add_fields — Filters response by which fields are added in addition to the default fields for each response object (e.g. add_fields[]=bundles).
  • (Array) remove_fields — Filters response by which fields are removed from response object (e.g. remove_fields[]=external_id).
  • (Boolean) with_favorites — DEPRECATED: with_favorites is deprecated and may be removed from future releases, use any_of_activity_types instead. Filters response by all favorited medias (e.g. with_favorites=true).
  • (DateTime) created_at_greater — Filters response to include only items with created_at >= specified timestamp (e.g. created_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) created_at_less — Filters response to include only items with created_at <= specified timestamp (e.g. created_at_less=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_greater — Filters response to include only items with updated_at >= specified timestamp (e.g. updated_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_less — Filters response to include only items with updated_at <= specified timestamp (e.g. updated_at_less=2012-02-15T02:06:56Z).
  • (DateTime) published_at_greater — Filters response to include only items with published_at >= specified timestamp (e.g. published_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) published_at_less — Filters response to include only items with published_at <= specified timestamp (e.g. published_at_less=2012-02-15T02:06:56Z).
  • (Array) any_of_activity_types — Filters response to include only items that have recorded account activities of type "favorite", "rating" or "media_view" (e.g. any_of_activity_types[]=favorite).
  • (Array) none_of_activity_types — Filters response to include only items that don't have any recorded account activities of type "favorite", "rating" or "media_view" (e.g. none_of_activity_types[]=media_view).
Example Response
XML JSON

<response>
  <medias>
    <media>
      <id>1</id>
      <name>Media-1</name>
      <description>this is a description</description>
      <active>true</active>
      <order_number nil="true"/>
      <available_platform_ids/>
      <audio_languages/>
      <subtitle_languages/>
      <duration>600</duration>
      <hd>false</hd>
      <container_ids/>
      <media_type nil="true"/>
      <meta_data/>
      <available_at nil="true"/>
      <expires_at nil="true"/>
      <created_at>2014-05-01T21:23:54Z</created_at>
      <updated_at>2014-05-01T21:23:55Z</updated_at>
      <images/>
      <external_id nil="true"/>
      <published_at>2013-07-01T21:23:35Z</published_at>
      <avg_rating>0.0</avg_rating>
      <properties>
      </properties>
    </media>
    <media>
      <id>2</id>
      <name>Media-2</name>
      <description>this is a description</description>
      <active>true</active>
      <order_number nil="true"/>
      <available_platform_ids/>
      <audio_languages/>
      <subtitle_languages/>
      <duration>600</duration>
      <hd>false</hd>
      <container_ids/>
      <media_type nil="true"/>
      <meta_data/>
      <available_at nil="true"/>
      <expires_at nil="true"/>
      <created_at>2014-05-01T21:23:55Z</created_at>
      <updated_at>2014-05-01T21:23:55Z</updated_at>
      <images/>
      <external_id nil="true"/>
      <published_at>2013-07-01T21:23:35Z</published_at>
      <avg_rating>0.0</avg_rating>
      <properties>
      </properties>
    </media>
  </medias>
</response>
Response Fields:
  • (Integer) media[id]
    The unique identifier of the media.
  • (String) media[name]
    The name of the media.
  • (String) media[description]
    The description of the media.
  • (Boolean) media[active]
    The active state of the media ('true' or 'false').
  • (Integer) media[order_number]
    The order number for the media.
  • (String) media[available_platform_ids]
    The platform IDs this media is available on. Available means that the media is active, inside an active bundle, the current date is within bundle start and end dates, is part of an active ownership policy and has active platform view rules that apply.
  • (Array) media[audio_languages]
    The audio language(s) the media is available in.
  • (Integer) media[duration]
    The duration of the media in seconds.
  • (Boolean) media[hd]
    Whether or not the media is available in HD (e.g. True is HD, False is not).
  • (Integer) media[media_type][id]
    The id of the media's associated media_type.
  • (String) media[media_type][name]
    The name of the associated media_type.
  • (Hash) media[meta_data]
    The metadata for the media; represented by (key, value) pairs.
  • (DateTime) media[available_at]
    The timestamp for when the media becomes available.
  • (DateTime) media[expires_at]
    The timestamp for when the media expires.
  • (DateTime) media[created_at]
    The timestamp for when the media was created.
  • (DateTime) media[updated_at]
    The timestamp for when the media was last updated.
  • (DateTime) media[published_at]
    The timestamp for when the media was published.
  • (Array) media[images]
    The Image formats and paths associated with a given piece of media.
  • (String) media[external_id]
    The external ID value for the media.

Url:

  • [GET] /api/v2/media/:medium_id/media/clips.[xml|json]

Returns a list of media linking other clips of media (e.g. previews, extras, and trailers).

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following example returns a list of all media clips associated with media 1.
[GET] https://service_name.synctv.com/api/v2/media/1/media/clips.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Boolean) active — Filters response by active state (e.g. active=true).
  • (String) sort_order — Defines the sort order of the response. (e.g. sort_order=order_number).
  • (String) id — The unique identifier of the media.
  • (String) name — The name attribute of the media.
  • (String) order_number — The order number of the media.
  • (String) available — Timestamp for when the media is available to be purchased.
  • (String) expires — Timestamp for when the media expires and is no longer available for purchasing.
  • (String) ownerships_count — The media's current ownership count.
  • (String) created_at — Timestamp for when the media was first created.
  • (String) published_at — Timestamp for when the media was first published.
  • (DateTime) available_on — Filters response by specified available_on timestamp (e.g. available_on=2012-02-15T02:06:56Z).
  • (DateTime) available_begin_date — Filters response to include only items with available_on >= specified timestamp (e.g. available_begin_date=2012-02-15T02:06:56Z).
  • (DateTime) available_end_date — Filters response to include only items with available_on <= specified timestamp (e.g. available_end_date=2012-02-15T02:06:56Z).
  • (DateTime) expire_begin_date — Filters response to include only items with expires_on >= specified timestamp (e.g. expire_begin_date=2012-02-15T02:06:56Z).
  • (DateTime) expire_end_date — Filters response to include only items with expires_on <= specified timestamp (e.g. expire_end_date=2012-02-15T02:06:56Z).
  • (String) named_like — Filters response to include items that contain the specified value in the name field (e.g. named_like=lost).
  • (Array) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (String) external_id — Filters response based on the value of the external_id field.
  • (String) key — Filters response based on the meta_data key.
  • (String) value — Filters response based on the meta_data value.
  • (Array) ids — Filters response to within a set of media ids (e.g. ids[]=1&ids[]=2...)..
  • (Integer) clip_id — Filters response to return sub media associated with media id passed as this parameter (e.g. clip_id=2)
  • (Array) any_of_available_platform_ids — Filters response based on the value of available_platform_id field (e.g. any_of_available_platform_ids[]=1&any_of_available_platform_ids[]=2...).
  • (Array) any_of_available_platform_type_ids — Filters response based on the value of the available_platform_id field (e.g. any_of_available_platform_type_ids[]=1&any_of_available_platform_type_ids[]=2...).
  • (String) with_definition — Filters response by definition (e.g. with_definition=hd or with_definition=sd).
  • (Array) any_of_audio_languages — Filters response by audio_languages (e.g. any_of_audio_languages[]="eng"&any_of_audio_languages[]="chn").
  • (Array) all_of_audio_languages — Filters response by audio_languages returning media with exactly the supplied language codes (e.g. all_of_audio_languages[]="eng"&all_of_audio_languages[]="chn").
  • (DateTime) created_at_greater — Filters response to include only items with created_at >= specified timestamp (e.g. created_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) created_at_less — Filters response to include only items with created_at <= specified timestamp (e.g. created_at_less=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_greater — Filters response to include only items with updated_at >= specified timestamp (e.g. updated_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_less — Filters response to include only items with updated_at <= specified timestamp (e.g. updated_at_less=2012-02-15T02:06:56Z).
  • (DateTime) published_at_greater — Filters response to include only items with published_at >= specified timestamp (e.g. published_at_greater=2012-02-15T02:06:56Z).
  • (DateTime) published_at_less — Filters response to include only items with published_at <= specified timestamp (e.g. published_at_less=2012-02-15T02:06:56Z).
Example Response
XML JSON

<response>
  <medias>
    <media>
      <id>1</id>
      <name>Media-3</name>
      <description>this is a description</description>
      <active>true</active>
      <order_number nil="true"/>
      <available_platform_ids/>
      <audio_languages/>
      <subtitle_languages/>
      <duration>600</duration>
      <hd>false</hd>
      <container_ids/>
      <media_type nil="true"/>
      <meta_data/>
      <available_at nil="true"/>
      <expires_at nil="true"/>
      <created_at>2014-05-01T21:23:58Z</created_at>
      <updated_at>2014-05-01T21:23:58Z</updated_at>
      <images/>
      <external_id nil="true"/>
      <published_at>2013-07-01T21:23:35Z</published_at>
      <avg_rating>0.0</avg_rating>
      <properties>
      </properties>
    </media>
    <media>
      <id>2</id>
      <name>Media-4</name>
      <description>this is a description</description>
      <active>true</active>
      <order_number nil="true"/>
      <available_platform_ids/>
      <audio_languages/>
      <subtitle_languages/>
      <duration>600</duration>
      <hd>false</hd>
      <container_ids/>
      <media_type nil="true"/>
      <meta_data/>
      <available_at nil="true"/>
      <expires_at nil="true"/>
      <created_at>2014-05-01T21:23:58Z</created_at>
      <updated_at>2014-05-01T21:23:58Z</updated_at>
      <images/>
      <external_id nil="true"/>
      <published_at>2013-07-01T21:23:35Z</published_at>
      <avg_rating>0.0</avg_rating>
      <properties>
      </properties>
    </media>
  </medias>
</response>
Response Fields:
  • (Integer) media[id]
    The unique identifier of the media.
  • (String) media[name]
    The name of the media.
  • (String) media[description]
    The description of the media.
  • (Boolean) media[active]
    The active state of the media ('true' or 'false').
  • (Integer) media[order_number]
    The order number for the media.
  • (Array) media[available_platform_ids]
    The list of platform ids for which the media is available on.
  • (Integer) media[media_type][id]
    The id of the media's associated media_type.
  • (String) media[media_type][name]
    The name of the associated media_type.
  • (Hash) media[meta_data]
    The metadata for the media; represented by (key, value) pairs.
  • (String) media[external_id]
    The external ID value for the media.
  • (DateTime) media[available_at]
    The timestamp for when the media becomes available.
  • (DateTime) media[expires_at]
    The timestamp for when the media expires.
  • (DateTime) media[created_at]
    The timestamp for when the media was created.
  • (DateTime) media[updated_at]
    The timestamp for when the media was last updated.
  • (DateTime) media[published_at]
    The timestamp for when the media was published.
  • (Array) media[images]
    The Image formats and paths associated with a given piece of media.

Url:

  • [GET] /api/v2/containers/:container_id/media/count.[xml|json]

Returns a count of all media within the specified container.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following example returns a count of all media.
[GET] https://service_name.synctv.com/api/v2/media/count.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Boolean) active — Filters response by active state (e.g. active=true)
  • (String) sort_order — Defines the sort order of the response. (e.g. sort_order=order_number)
  • (DateTime) available_on — Filters response by specified available_on timestamp (e.g. available_on=2012-02-15T02:06:56Z).
  • (DateTime) available_begin_date — Filters response to include only items with available_on >= specified timestamp (e.g. available_begin_date=2012-02-15T02:06:56Z).
  • (DateTime) available_end_date — Filters response to include only items with available_on <= specified timestamp (e.g. available_end_date=2012-02-15T02:06:56Z).
  • (DateTime) expire_begin_date — Filters response to include only items with expires_on >= specified timestamp (e.g. expire_begin_date=2012-02-15T02:06:56Z).
  • (DateTime) expire_end_date — Filters response to include only items with expires_on <= specified timestamp (e.g. expire_end_date=2012-02-15T02:06:56Z).
  • (String) named_like — Filters response to include items that contain the specified value in the name field (e.g. named_like=lost).
  • (Array) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (String) external_id — Filters response based on the value of the external_id field.
  • (String) key — Filters response based on the meta_data key.
  • (String) value — Filters response based on the meta_data value.
  • (Array) ids — Filters response to within a set of media ids (e.g. ids[]=1&ids[]=2...)..
  • (Integer) clip_id — Filters response to return sub media associated with media id passed as this parameter (e.g. clip_id=2)
  • (Array) any_of_available_platform_ids — Filters response based on the value of available_platform_id field (e.g. any_of_available_platform_ids[]=1&any_of_available_platform_ids[]=2...).
  • (Array) any_of_available_platform_type_ids — Filters response based on the value of the available_platform_id field (e.g. any_of_available_platform_type_ids[]=1&any_of_available_platform_type_ids[]=2...).
  • (String) with_definition — Filters response by definition (e.g. with_definition=hd or with_definition=sd).
  • (Array) any_of_audio_languages — Filters response by audio_languages (e.g. any_of_audio_languages[]="eng"&any_of_audio_languages[]="chn").
  • (Array) all_of_audio_languages — Filters response by audio_languages returning media with exactly the supplied language codes (e.g. all_of_audio_languages[]="eng"&any_of_audio_languages[]="chn").
Example Response
XML JSON

<response>
  <count>30</count>
  <code>1</code>
  <message>Successfully completed.</message>
</response>
Response Fields:
  • (Integer) count
    The count of media

Url:

  • [GET] /api/v2/media/:id.[xml|json]

Returns information for the specified media.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
Example Request

The following example returns the media information for media 100. 
[GET] https://service_name.synctv.com/api/v2/media/100.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <media>
    <id>100</id>
    <name>Media-5</name>
    <description>this is a description</description>
    <active>true</active>
    <order_number nil="true"/>
    <available_platform_ids/>
    <audio_languages/>
    <subtitle_languages/>
    <duration>600</duration>
    <hd>false</hd>
    <container_ids/>
    <media_type nil="true"/>
    <meta_data/>
    <available_at nil="true"/>
    <expires_at nil="true"/>
    <created_at>2014-05-01T21:24:01Z</created_at>
    <updated_at>2014-05-01T21:24:01Z</updated_at>
    <images/>
    <external_id nil="true"/>
    <published_at>2013-07-01T21:23:35Z</published_at>
    <avg_rating>0.0</avg_rating>
    <properties>
    </properties>
  </media>
  <container_ids>
    <container_id>1</container_id>
    <container_id>2</container_id>
    <container_id>3</container_id>
  </container_ids>
  <contributors>
    <contributor>
      <id>1</id>
      <media_id>1</media_id>
      <program_id nil="true"/>
      <person>person name 1</person>
      <role>role 1</role>
    </contributor>
    <contributor>
      <id>2</id>
      <media_id>2</media_id>
      <program_id nil="true"/>
      <person>person name 2</person>
      <role>role 2</role>
    </contributor>
    <contributor>
      <id>3</id>
      <media_id>3</media_id>
      <program_id nil="true"/>
      <person>person name 3</person>
      <role>role 3</role>
    </contributor>
  </contributors>
  <bundle_ids>
    <bundle_id>1</bundle_id>
    <bundle_id>2</bundle_id>
  </bundle_ids>
</response>
Response Fields:
  • (Element) media
    Contains the fields for the media item. See above for description of media response fields.
  • (Element) contributors
    Contains some fields listing the contributors associated with the media item.
  • (Element) container_ids
    Contains some fields listing the container_ids associated with the media item.