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:

  • Activities

This document describes the API for creating, reading, updating and deleting account activities, such as media views, favorites, ratings, and more in the future.

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

Url:

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

Returns a list of the currently authorized account's activities.

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 the currently authorized account's activities.
[GET] https://service_name.synctv.com/api/v2/accounts/activities.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example returns a list of the currently authorized account's media activities.
[GET] https://service_name.synctv.com/api/v2/accounts/media/activities.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example returns a list of the currently authorized account's activities for media_id = 1.
[GET] https://service_name.synctv.com/api/v2/accounts/media/1/activities.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example returns a list of the currently authorized account's container activities.
[GET] https://service_name.synctv.com/api/v2/accounts/containers/activities.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example returns a list of the currently authorized account's activities for container_id = 1.
[GET] https://service_name.synctv.com/api/v2/accounts/containers/1/activities.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.
  • (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) created_at_greater — Filters response to include only items with created_at >= specified timestamp (e.g. created_at_greater=2012-02-15T02:06:56Z).
  • (String) any_of_types — Filters response by included activity types, "media_view", "favorite", "rating", "media_favorite", "media_rating", "container_favorite", "container_rating" (e.g. any_of_types=media_favorite).
  • (String) none_of_types — Filters response by activity types that not included, "media_view", "favorite", "rating", "media_favorite", "media_rating", "container_favorite", "container_rating" (e.g. none_of_types=rating).
  • (Array) media_type_id — If scoped to media, it filters response by media_type_id (e.g. media_type_id[]=1&media_type_id[]=2)
  • (Array) container_type_id — If scoped to containers, it filters response by container_type_id (e.g. container_type_id[]=1&container_type_id[]=2)
  • (Boolean) sort_descending — Reverse order of sort_order sorting, make it descending.
  • (String) sort_order — Orders activities by fields. (e.g. sort_order=created_at)
  • (String) id — Unique identifier of the activity.
  • (String) created_at — Timestamp of when the activity was created.
  • (String) updated_at — Timestamp of when the activity was updated.
  • (String) media_name — Media name if activity is linked to media.
  • (String) container_name — Container name if activity is linked to container.
  • (String) media_published_at — Timestamp of when media was published if linked to media.
  • (String) media_avg_rating — Average media rating if activity is linked to media.
  • (String) container_avg_rating — Average container rating if activity is linked to container.
  • (String) media_ownerships_count — Media ownerships if activity is linked to media.
Example Response
XML JSON

<response>
  <activities>
    <activity>
      <id>1</id>
      <account_id>1</account_id>
      <account_profile_id nil="true"/>
      <media_id>1</media_id>
      <kind>1</kind>
      <media>
        <id>1</id>
        <name>Media-44</name>
        <description>this is a description</description>
        <active>true</active>
        <order_number nil="true"/>
        <available_platform_ids>
          <available_platform_id>1</available_platform_id>
        </available_platform_ids>
        <audio_languages/>
        <subtitle_languages/>
        <duration>600</duration>
        <hd>false</hd>
        <container_ids/>
        <media_type>
          <id>1</id>
          <name>MediaType-47</name>
        </media_type>
        <meta_data/>
        <available_at nil="true"/>
        <expires_at nil="true"/>
        <created_at>2014-05-01T21:26:58Z</created_at>
        <updated_at>2014-05-01T21:26: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>
      <type>Account::Activity::MediaFavorite</type>
      <created_at>2014-05-01T21:26:58Z</created_at>
      <updated_at>2014-05-01T21:26:58Z</updated_at>
    </activity>
    <activity>
      <id>2</id>
      <account_id>2</account_id>
      <account_profile_id nil="true"/>
      <container_id>1</container_id>
      <type>Account::Activity::ContainerRating</type>
      <kind>2</kind>
      <container>
        <id>1</id>
        <name>Container-26</name>
        <description nil="true"/>
        <parent_id nil="true"/>
        <order_number>0</order_number>
        <active>true</active>
        <leaf>true</leaf>
        <container_type nil="true"/>
        <media_ids/>
        <meta_data/>
        <created_at>2014-05-01T21:26:58Z</created_at>
        <updated_at>2014-05-01T21:26:58Z</updated_at>
        <images/>
        <external_id nil="true"/>
        <published_at>2014-05-01T21:13:35Z</published_at>
        <container_group_id nil="true"/>
        <bundle_ids/>
        <avg_rating>0.0</avg_rating>
        <properties>
        </properties>
      </container>
      <int_value>3</int_value>
      <created_at>2014-05-01T21:26:58Z</created_at>
      <updated_at>2014-05-01T21:26:58Z</updated_at>
    </activity>
  </activities>
</response>
Response Fields:
  • (Integer) activity[id]
    The unique identifier of the account activity.
  • (Integer) activity[media_id]
    The unique identifier of a media object if activity is a media related activity.
  • (Integer) activity[container_id]
    The unique identifier of a container object if activity is a container related activity.
  • (Integer) activity[type]
    The type of activity ("media_view", "media_favorite", "media_rating", "container_favorite", "container_rating", "media_watched", "container_watched").
  • (Integer) activity[kind]
    DEPRECATED: The kind value of the activity (1 = Favorite, 2 = Rating).
  • (Integer) activity[int_value]
    An int value associated with the rating if activity is of type "rating".
  • (Object) activity[media]
    Content of the media if activity is media related. Elements are defined in the media API.
  • (Object) activity[container]
    Content of the container if activity is container related. Elements are defined in the container API.
  • (Object) activity[client_id]
    The unique identifier of a client object if activity is of type "media view".
  • (Object) activity[watched_time]
    Number of times the associated media has been watched if activity is of type "media_view".
  • (DateTime) activity[created_at]
    The timestamp for when the activity was created.
  • (DateTime) activity[updated_at]
    The timestamp for when the activity was updated.

Url:

  • [GET] /api/v2/accounts/activities/count.[xml|json]
  • [GET] /api/v2/accounts/media/activities/count.[xml|json]
  • [GET] /api/v2/accounts/media/:medium_id/activities/count.[xml|json]
  • [GET] /api/v2/accounts/container/activities/count.[xml|json]
  • [GET] /api/v2/accounts/container/:container_id/activities/count.[xml|json]

Returns a count of the currently authorized account's activities.

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 the current account's activities.
[GET] https://service_name.synctv.com/api/v2/accounts/activities/count.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example returns a count of the current account's media activities.
[GET] https://service_name.synctv.com/api/v2/accounts/media/activities/count.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example returns a count of the current account's container activities.
[GET] https://service_name.synctv.com/api/v2/accounts/containers/activities/count.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (DateTime) created_at_before — Filters response to include only items with created_at <= specified timestamp (e.g. created_at_before=2012-02-15T02:06:56Z).
  • (DateTime) created_at_after — Filters response to include only items with created_at >= specified timestamp (e.g. created_at_after=2012-02-15T02:06:56Z).
  • (String) any_of_types — Filters response by included activity types, "media_view", "favorite", "rating", "media_favorite", "media_rating", "container_favorite", "container_rating" (e.g. any_of_types=media_favorite).
  • (String) none_of_types — Filters response by activity types that not included, "media_view", "favorite", "rating", "media_favorite", "media_rating", "container_favorite", "container_rating" (e.g. none_of_types=rating).
  • (Array) media_type_id — If scoped to media, it filters response by media_type_id (e.g. media_type_id[]=1&media_type_id[]=2)
  • (Array) container_type_id — If scoped to containers, it filters response by container_type_id (e.g. container_type_id[]=1&container_type_id[]=2)
Example Response
XML JSON

<response>
  <count>30</count>
  <code>1</code>
  <messages>
    <message>Successfully completed.</message>
  </messages>
</response>
Response Fields:
  • (Response) Count
    The total number of the current authorized account's activities.

Url:

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

Returns information for the specified activity.

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 URL returns the media activity information for activities[id] == 100.
[GET] https://service_name.synctv.com/api/v2/accounts/media/activities/100.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <activity>
    <id>100</id>
    <account_id>1</account_id>
    <account_profile_id nil="true"/>
    <media_id>1</media_id>
    <kind>1</kind>
    <media>
      <id>1</id>
      <name>Media-45</name>
      <description>this is a description</description>
      <active>true</active>
      <order_number nil="true"/>
      <available_platform_ids>
        <available_platform_id>1</available_platform_id>
      </available_platform_ids>
      <audio_languages/>
      <subtitle_languages/>
      <duration>600</duration>
      <hd>false</hd>
      <container_ids/>
      <media_type>
        <id>1</id>
        <name>MediaType-48</name>
      </media_type>
      <meta_data/>
      <available_at nil="true"/>
      <expires_at nil="true"/>
      <created_at>2014-05-01T21:27:03Z</created_at>
      <updated_at>2014-05-01T21:27:03Z</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>
    <type>Account::Activity::MediaFavorite</type>
    <created_at>2014-05-01T21:27:03Z</created_at>
    <updated_at>2014-05-01T21:27:03Z</updated_at>
  </activity>
</response>
Response Fields:
  • (Integer) activity[id]
    The unique identifier of the account activity.
  • (Integer) activity[media_id]
    The unique identifier of a media object if activity is a media related activity.
  • (Integer) activity[container_id]
    The unique identifier of a container object if activity is a container related activity.
  • (Integer) activity[type]
    The type of activity ("media_view", "media_favorite", "media_rating", "container_favorite", "container_rating", "media_watched", "container_watched").
  • (Integer) activity[kind]
    DEPRECATED: The kind value of the activity (1 = Favorite, 2 = Rating).
  • (Integer) activity[int_value]
    An int value associated with the rating if activity is of type "rating".
  • (Object) activity[media]
    Content of the media if activity is media related. Elements are defined in the media API.
  • (Object) activity[container]
    Content of the container if activity is container related. Elements are defined in the container API.
  • (Object) activity[client_id]
    The unique identifier of a client object if activity is of type "media view".
  • (Object) activity[watched_time]
    Number of times the associated media has been watched if activity is of type "media_view".
  • (DateTime) activity[created_at]
    The timestamp for when the activity was created.
  • (DateTime) activity[updated_at]
    The timestamp for when the activity was updated.

Url:

  • [POST] /api/v2/accounts/media/:medium_id/activities.[xml|json]
  • [POST] /api/v2/accounts/container/:container_id/activities.[xml|json]

Creates a new activity for the currently authorized account and the specified object.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (Integer) activity[type]
    Type of activity ("favorite", "rating", "media_view").
  • (Integer) activity[int_value]
    For type rating requires an integer value associated with this activity.
  • (Integer) activity[watched_time]
    Progress time stamp (in seconds) the user has watched a specific media (only for type "media_view").
Example Request

The following URL creates a new rating for the current account to the media object with an id = 123.
[POST] https://service_name.synctv.com/api/v2/accounts/media/123/activities.xml?activity[type]=rating&activity[int_value]=2&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following URL creates a new favorite for the current account to the container object with an id = 123.
[POST] https://service_name.synctv.com/api/v2/accounts/containers/123/activities.xml?activity[type]=favorite&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <activity>
    <id>1</id>
    <account_id>1</account_id>
    <account_profile_id nil="true"/>
    <media_id>1</media_id>
    <kind>1</kind>
    <media>
      <id>1</id>
      <name>Media-46</name>
      <description>this is a description</description>
      <active>true</active>
      <order_number nil="true"/>
      <available_platform_ids>
        <available_platform_id>1</available_platform_id>
      </available_platform_ids>
      <audio_languages/>
      <subtitle_languages/>
      <duration>600</duration>
      <hd>false</hd>
      <container_ids/>
      <media_type>
        <id>1</id>
        <name>MediaType-49</name>
      </media_type>
      <meta_data/>
      <available_at nil="true"/>
      <expires_at nil="true"/>
      <created_at>2014-05-01T21:27:06Z</created_at>
      <updated_at>2014-05-01T21:27:06Z</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>
    <type>Account::Activity::MediaFavorite</type>
    <created_at>2014-05-01T21:27:06Z</created_at>
    <updated_at>2014-05-01T21:27:06Z</updated_at>
  </activity>
</response>
Response Fields:
  • (Integer) activity[id]
    The unique identifier of the account activity.
  • (Integer) activity[media_id]
    The unique identifier of a media object if activity is a media related activity.
  • (Integer) activity[container_id]
    The unique identifier of a container object if activity is a container related activity.
  • (Integer) activity[type]
    The type of activity ("media_view", "media_favorite", "media_rating", "container_favorite", "container_rating", "media_watched", "container_watched").
  • (Integer) activity[kind]
    DEPRECATED: The kind value of the activity (1 = Favorite, 2 = Rating).
  • (Integer) activity[int_value]
    An int value associated with the rating if activity is of type "rating".
  • (Object) activity[media]
    Content of the media if activity is media related. Elements are defined in the media API.
  • (Object) activity[container]
    Content of the container if activity is container related. Elements are defined in the container API.
  • (Object) activity[client_id]
    The unique identifier of a client object if activity is of type "media view".
  • (Object) activity[watched_time]
    Number of times the associated media has been watched if activity is of type "media_view".
  • (DateTime) activity[created_at]
    The timestamp for when the activity was created.
  • (DateTime) activity[updated_at]
    The timestamp for when the activity was updated.

Url:

  • [PUT] /api/v2/accounts/activities/:id.[xml|json]
  • [PUT] /api/v2/accounts/media/:medium_id/activities/:id.[xml|json]
  • [PUT] /api/v2/accounts/container/:container_id/activities/:id.[xml|json]

Updates the specified activity.

Note:
The type attribute cannot be updated, only int_value can be updated for ratings.
Note:
This will return only success or failure, no content.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (Integer) activity[int_value]
    For type rating requires an integer value associated with this activity.
  • (Integer) activity[watched_time]
    Progress time stamp (in seconds) the user has watched a specific media (only for type "media_view").
Example Request

The following URL updates the specified account activity and the media_id 123 instead.
[PUT] https://service_name.synctv.com/api/v2/accounts/media/123/activities/1.xml?activity[int_value=1]&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

On success: HTTP 200

Url:

  • [DELETE] /api/v2/accounts/activities/:id.[xml|json]
  • [DELETE] /api/v2/accounts/media/:medium_id/activities/:id.[xml|json]
  • [DELETE] /api/v2/accounts/container/:container_id/activities/:id.[xml|json]

Deletes the specified account activity.

Note:
This will return only success or failure, no content.
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 URL deletes the account activity with id = 100
[DELETE] https://service_name.synctv.com/api/v2/accounts/activities/100.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

On success: HTTP 200
On error:   HTTP 400 with array of errors in message tags
<response>
  <code>-4</code>
  <messages>
    <message>Record not found</message>
  </messages>
</response>