Resource: Volumes

Topics:

Actions

  • - (Object) index(method = GET, url = '/rest/v1/volumes')

Url:

  • [GET] /rest/v1/volumes
  • [GET] /rest/v1/shows/:id/volumes (volumes linked to a specific show)
Note:

This action does not require a cookie session. If there is no cookie session then the device id parameter is required.

Note:

The url shows/:id/volumes requires that the show you are requesting volumes for is active, if inactive you will receive a record not found error, to retrieve volumes of an inactive show use the show_include_inactive param

Note:

By default this request will only return volumes with a active value of true, you need to explicitly request inactive volumes in the url to receive them

Returns all volumes on the service or all volumes linked to a show

Arguments:

  • (Integer) device

    The id of the service device (only required if no cookie session)

  • (Boolean) active

    (optional) If "true" then only active volumes will be returned, if "false" then only inactive volumes will be returned, if omitted then only active shows will be returned

  • (Any) show_include_inactive

    (optional) only has effect on shows/:id/volumes, this is used when you want to see a shows volumes regardless of whether the show is active or inactive. All volumes will be returned for the show whether they are active or not

Example Request:

Requesting all active volumes on the service
https://service_name.synctv.com/rest/v1/volumes?device=urn:synctv:devices:web:11223344

Example Response:

<scbp>
  <version>0.6</version>
  <response>
    <code>1</code>
    <message>Successfully completed.</message>
    <count>1</count>
  </response>
<volumes>
  <volume>
    <id>271</id>
    <active>true</active>
    <name>Another Volume</name>
    <number>1</number>
    <copyright></copyright>
    <sku></sku>
    <advisory></advisory>
    <status>complete</status>
    <episode_first></episode_first>
    <episode_last></episode_last>
    <episode_count>0</episode_count>
    <description>A description</description>
    <images>
      <image>
        <format>show_icon_lg</format>
        <url></url>
      </image>
    </images>
    <links>
      <metadata>/rest/v1/volumes/271</metadata>
      <episodes>/rest/v1/volumes/271/episodes</episodes>
    </links>
  </volume>
  </volumes>
</scbp>
  • - (Object) show(method = GET, url = '/rest/v1/volumes/:id')

Url:

  • [GET] /rest/v1/volumes/:id
Note:

This action does not require a cookie session. If there is no cookie session then the device id parameter is required.

Note:

By default this url will not return a volume set to inactive, if you wish to access inactive volumes will need to use the include_inactive param

Returns details of a specific volume

Arguments:

  • (String) device

    (optional, required if no cookie session) the id of the service device

  • (Any) include_inactive

    (optional) the value of this can be anything, the presence of this param will signal that you wish view an inactive or active volume

Example Request:

https://service_name.synctv.com/rest/v1/volumes/100?device=urn:synctv:devices:web:11223344

Example Response:

<scbp>
  <version>0.6</version>
  <response>
    <code>1</code>
    <message>Successfully completed.</message>
    <count>1</count>
  </response>
  <volume>
    <id>273</id>
    <active>true</active>
    <name>My Volume</name>
    <number>1</number>
    <copyright></copyright>
    <sku></sku>
    <advisory></advisory>
    <status>complete</status>
    <episode_first></episode_first>
    <episode_last></episode_last>
    <episode_count>0</episode_count>
    <description>No Description</description>
    <images>
      <image>
        <format>show_icon_lg</format>
        <url></url>
      </image>
    </images>
    <links>
      <volumes>/rest/v1/shows/432/volumes</volumes>
      <episodes>/rest/v1/volumes/273/episodes</episodes>
    </links>
  </volume>
</scbp>
  • - (Object) update(method = PUT, url = '/rest/v1/volumes/:id')

Url:

  • [PUT] /rest/v1/volumes/:id
Note:

This request requires admin access.

Updates a volume’s metadata

Arguments:

  • (Boolean) volume[active]

    (optional) sets the volume to active or inactive, accepts only "true" or "false"

  • (String) volume[name]

    (optional) sets the volume name

  • (Integer) volume[number]

    (optional) sets the volume number, it must be a valid number and can not be the same as any other volume which is linked to the same show record

  • (String) volume[copyright]

    (optional) sets the volume copyright

  • (String) volume[sku]

    (optional) sets the volume stock keeping unit, accepts any string

  • (String) volume[advisory]

    (optional) sets the volume advisory rating, accepts any string, max of 20 characters

  • (String) volume[status]

    (optional) sets the volume status, can only be "complete", "incomplete" or "unknown", any other value will result in a error

  • (String) volume[description]

    (optional) sets the volume description

Example Request:

Request changing a volumes name
https://service_name.synctv.com/rest/v1/volumes/100?volume[name]=new_name

Example Response:

<scbp>
  <response>
    <message>Successfully completed.</message>
    <count>1</count>
    <code>1</code>
  </response>
  <version>0.5</version>
  <volume>
    <status>complete</status>
    <description>Description</description>
    <episode_count type="integer">1</episode_count>
    <episode_last type="integer">1</episode_last>
    <copyright nil="true"></copyright>
    <episode_first type="integer">1</episode_first>
    <number type="integer">1</number>
    <advisory nil="true"></advisory>
    <name>My Volume (new)</name>
    <active type="boolean">true</active>
    <id type="integer">272</id>
    <sku nil="true"></sku>
  </volume>
</scbp>