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:

  • Containers

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

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/containers.[xml|json]
  • [GET] /api/v2/containers/:container_id/containers.[xml|json]
  • [GET] /api/v2/media/:medium_id/containers.[xml|json]

Returns a list of containers.

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 container items based on any supplied arguments (filters). 
[GET] https://service_name.synctv.com/api/v2/containers.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).
  • (String) id — The unique idenfitier of a container.
  • (String) name — Name attribute of a container.
  • (String) order_number — Order number of a container.
  • (String) ownerships_count — Count of ownerships for a container.
  • (String) created_at — Timestamp when container was first created.
  • (String) published_at — Timestamp when container was first published.
  • (String) published_max — Timestamp criteria of when container was published.
  • (String) published_min — Timestamp criteria of when container was published.
  • (String) available_max — Timestamp criteria of when container was available.
  • (String) available_min — Timestamp criteria of when container was available.
  • (Boolean) sort_descending — Reverse order of sort_order sorting, make it descending.
  • (String) named_like — Filters response to include items that contain the specified value in the name field (e.g. named_like=lost).
  • (String) external_id — Filters response based on value of external_id field.
  • (String) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (String) key — Filters response based on the meta_data key.
  • (String) value — Filters response based on the meta_data value.
  • (Integer) order_number — Filters response based on order_number.
  • (Array) any_of_activity_types — Filters response to include only items that have recorded account activities of type "favorite" or "rating" (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" (e.g. none_of_activity_types[]=rating).
  • (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).
Example Response
XML JSON

<response>
  <containers>
    <container>
      <id>1</id>
      <name>Container-4</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:24:27Z</created_at>
      <updated_at>2014-05-01T21:24:27Z</updated_at>
      <images/>
      <external_id>157F34B</external_id>
      <published_at>2012-02-03T03:18:32Z</published_at>
      <container_group_id nil="true"/>
      <bundle_ids/>
      <avg_rating>0.0</avg_rating>
      <properties>
      </properties>
    </container>
    <container>
      <id>3</id>
      <name>Container-6</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:24:27Z</created_at>
      <updated_at>2014-05-01T21:24:27Z</updated_at>
      <images/>
      <external_id>257F34B</external_id>
      <published_at>2012-02-03T03:18:32Z</published_at>
      <container_group_id nil="true"/>
      <bundle_ids/>
      <avg_rating>0.0</avg_rating>
      <properties>
      </properties>
    </container>
  </containers>
</response>
Response Fields:
  • (Response) containers
    A list of containers. See below for a description of the container response fields.

Url:

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

Returns a count of all containers.

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 container items based on any supplied arguments (filters). 
[GET] https://service_name.synctv.com/api/v2/containers/count.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Boolean) active — Filters response by active state (e.g. active=true)
  • (Integer) container_id — Filters response to include items that are in a container of specified id (e.g. container_id=1)
  • (Integer) media_id — Filters response to include items that have media of specified id (e.g. media_id=1)
  • (String) external_id — Filters response based on value of external_id field.
  • (String) type_id — Filters response based on given set of type_ids (e.g. type_id[]=1&type_id[]=2)
  • (String) key — Filters response based on the meta_data key.
  • (String) value — Filters response based on the meta_data value.
  • (Integer) order_number — Filters response based on order_number.
  • (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).
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 containers.

Url:

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

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

<response>
  <container>
    <id>100</id>
    <name>Container-8</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:24:29Z</created_at>
    <updated_at>2014-05-01T21:24:29Z</updated_at>
    <images/>
    <external_id>357F34B</external_id>
    <published_at>2012-02-03T03:18:32Z</published_at>
    <container_group_id nil="true"/>
    <bundle_ids/>
    <avg_rating>0.0</avg_rating>
    <properties>
    </properties>
  </container>
</response>
Response Fields:
  • (String) container[id]
    The unique id of the container.
  • (String) container[name]
    The name of the container.
  • (String) container[description]
    The description of the container.
  • (Integer) container[parent_id]
    The id of the parent container.
  • (Integer) container[order_number]
    The order number. Containers will be ordered depending on value.
  • (Boolean) container[active]
    Determinate for whether the container is active or inactive.
  • (DateTime) container[created_at]
    The date of when the container was first created.
  • (DateTime) container[updated_at]
    The date of when the container was last updated.
  • (DateTime) container[published_at]
    The date of when the container was published.
  • (Boolean) container[leaf]
    Determinate for whether the container is a leaf or branch in containers tree.
  • (Integer) container[container_type][id]
    The id of the container_type for the container.
  • (String) container[container_type][name]
    The name of the container_type for the container.
  • (Integer) container[meta_data_attributes][][id]
    The id of the meta data to update.
  • (String) container[meta_data_attributes][][key]
    The meta data key.
  • (String) container[meta_data_attributes][][value]
    The meta data value.
  • (String) container[external_id]
    The external ID value for the container.
  • (Array) container[bundle_ids]
    The list of bundle ids for the container.