Admin 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:29:33Z</created_at>
      <updated_at>2014-05-01T21:29:33Z</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:29:33Z</created_at>
      <updated_at>2014-05-01T21:29:33Z</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:29:35Z</created_at>
    <updated_at>2014-05-01T21:29:35Z</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.

Url:

  • [POST] /api/v2/containers.[xml|json]

Creates a new container.

Note:
The container[parent_id] value allows for a container to be put inside another container. This allows for a nested set structure to be established.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (String) container[name]
    The name of container.
  • (Integer) container[container_type_id]
    Set container type by container_type_id.
Example Request

The following example creates a new container item.
[POST] https://service_name.synctv.com/api/v2/containers.xml?container[name]=Container-1&container[container_type_id]=1&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (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.
  • (Integer) container[media_ids][] — Set the media ids for media in the container.
  • (Integer) container[bundle_ids][] — Set the media ids for media in the container.
  • (String) container[meta_data_attributes][][key] — Used to set the meta data key value.
  • (String) container[meta_data_attributes][][value] — Used to set the meta data value value.
  • (String) container[external_id] — The external id value for the container.
  • (DateTime) container[published_at] — The date of when the container was published.
Example Response
XML JSON

<response>
  <container>
    <id>1</id>
    <name>Container-10</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:29:37Z</created_at>
    <updated_at>2014-05-01T21:29:37Z</updated_at>
    <images/>
    <external_id>457F34B</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:
  • (Response) container
    All attribute fields for the created container. See above for a description of the container response fields.

Url:

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

Updates a container.

Note:
This will return only success or failure, no content.
Note:
Meta_data_attributes behave like two dimensional arrays. You can append more attributes with new keys, but you will overwrite the existing value if you are using the same key.
Note:
The container[parent_id] value allows for a container to be put inside another container. This allows for a nested set structure to be established.
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 modifies the container name.
[PUT] https://service_name.synctv.com/api/v2/containers/10.xml?container[name]=Container-8&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example creates a new meta_data
[PUT] https://service_name.synctv.com/api/v2/containers/1.xml?container[meta_data_attributes][][key]=meta_data_key&container[meta_data_attributes][][value]=some value&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example updates a meta data
[PUT] https://service_name.synctv.com/api/v2/containers/1.xml?container[meta_data_attributes][][id]=1&container[meta_data_attributes][][key]=meta_data_key&container[meta_data_attributes][][value]=something to change&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example deletes a meta data
[PUT] https://service_name.synctv.com/api/v2/containers/1.xml?container[meta_data_attributes][][id]=1&container[meta_data_attributes][][_destroy]=1&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d

The following example creates multiple meta data
[PUT] https://service_name.synctv.com/api/v2/containers/1.xml?container[meta_data_attributes][][key]=first_key&container[meta_data_attributes][][value]=some value&container[meta_data_attributes][][key]=second_key&container[meta_data_attributes][][value]=some other value&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) container[name] — The name of the container.
  • (Integer) container[container_type_id] — Set container type by container_type_id.
  • (String) container[description] — The description of 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.
  • (Integer) container[media_ids][] — Set the media ids for media in the container. This will determine which media objects are available through this container.
  • (String) container[meta_data_attributes][][key] — Used to set the meta data key value.
  • (String) container[meta_data_attributes][][value] — Used to set the meta data value value.
  • (String) container[external_id] — The external id value for the container.
  • (DateTime) container[published_at] — The date of when the container was published.
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>

Url:

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

Delete the specified container.

Note:
This will return only success or failure, no content.
Example Request

The following example deletes container item with id == 10.
[DELETE] https://service_name.synctv.com/api/v2/containers/10.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) access_id — Access id returned from Authorization (User) client_authorize.
  • (String) signature — MD5 hash encoded string of query parameters.
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>