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:

  • Devices

This document describes the API for reading, updating and deauthorizing devices.

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/devices.[xml|json]

Returns a list of all devices.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
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) authorized — Filters response by authorization (e.g. auhtorization=true).
  • (String) uid — The unique identifier of the device.
  • (String) device_name — Filters response by device name. the supplied account id.
  • (Array) any_of_account_ids — Only return devices belonging to the supplied account id.
Example Response
XML JSON

<response>
  <devices>
    <device>
      <id>1</id>
      <device_name>Device Name</device_name>
      <uid>abcdefghijk</uid>
      <client_access_id nil="true"/>
      <created_at>2014-05-01T21:28:45Z</created_at>
      <updated_at>2014-05-01T21:28:45Z</updated_at>
      <authorized>false</authorized>
    </device>
    <device>
      <id>2</id>
      <device_name>Device Name</device_name>
      <uid>a1b23c34lkpo</uid>
      <client_access_id nil="true"/>
      <created_at>2014-05-01T21:28:45Z</created_at>
      <updated_at>2014-05-01T21:28:45Z</updated_at>
      <authorized>false</authorized>
    </device>
  </devices>
</response>
Response Fields:
  • (Integer) device[id]
    Id of the device
  • (String) device
    [name] Name of the device
  • (Boolean) device[authorized]
    Whether the device has been authorized (true, false)
  • (String) device[uid]
    The UID of the device.
  • (Integer) device[client_access_id]
    The id of the associated client_access.
  • (DateTime) device[created_at]
    Timestamp of when the device was created.
  • (DateTime) device[updated_at]
    Timestamp of when the device was last updated.

Url:

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

Returns the specified device.

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 information for device 100.
[GET] https://service_name.synctv.com/api/v2/devices/100.xml?access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <device>
    <id>100</id>
    <device_name>Device Name</device_name>
    <uid>zyxwvu</uid>
    <client_access_id nil="true"/>
    <created_at>2014-05-01T21:28:53Z</created_at>
    <updated_at>2014-05-01T21:28:53Z</updated_at>
    <authorized>false</authorized>
  </device>
</response>
Response Fields:
  • (Integer) device[id]
    Id of the device
  • (String) device
    [name] Name of the device
  • (Boolean) device[authorized]
    Whether the device has been authorized (true, false)
  • (String) device[uid]
    The UID of the device.
  • (Integer) device[client_access_id]
    The id of the associated client_access.
  • (DateTime) device[created_at]
    Timestamp of when the device was created.
  • (DateTime) device[updated_at]
    Timestamp of when the device was last updated.

Url:

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

Updates the specified device.

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 example updates device 100's name field to say "My Device".
[PUT] https://service_name.synctv.com/api/v2/devices/100.xml?device[name]=My+Renamed+Device&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (String) device[name] — The device's name.
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:

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

Deauthorize the specified device.

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 example deauthorizes device 100.
[PUT] https://service_name.synctv.com/api/v2/devices/100/deauthorize.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>-16</code>
  <messages>
    <message>Device already deauthorized</message>
  </messages>
</response