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:

  • Mediographies

This document describes the API for creating, reading, updating and deleting mediographies. Mediography is a detailed information regarding one piece of work from a particular contributor. It contains information such as roles and characters a contributor had in context to a Movie, TV Show, etc.

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

Url:

  • [GET] /api/v2/mediography.[xml|json]
  • [GET] /api/v2/media/:media_id/mediography.[xml|json]
  • [GET] /api/v2/contributors/:contributor_id/mediography.[xml|json]

Returns a list of all mediographies.

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 request returns a list of all mediography.
[GET] https://service_name.synctv.com/api/v2/mediography.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.
  • (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. When multi-sorting the url placement determines which is dominant).
  • (String) role_category — The role category of the mediography.
  • (String) name — The name attribute of the mediography.
  • (Array) remove_fields — Filters response by which fields are removed from response object (e.g. remove_fields[]=participant_id).
  • (Array) add_fields — Filters response by which fields are added in addition to the default fields for each response object (e.g. add_fields[]=participant).
  • (Array) fields — Filters response by which fields are rendered for each response object. This can include optional fields, like 'participant' (e.g. fields[]=id&fields[]=participant).
  • (String) participant — Add participant object to the response.
Example Response
XML JSON

<response>
  <mediographies>
    <mediography>
      <id>1</id>
      <media_id>1</media_id>
      <container_id nil="true"/>
      <program_id nil="true"/>
      <participant_id>1</participant_id>
      <name>Harrison Ford 1</name>
      <role>Actor</role>
      <role_category nil="true"/>
      <characters>
        <character>Han Solo</character>
      </characters>
      <external_image_paths/>
    </mediography>
    <mediography>
      <id>2</id>
      <media_id>2</media_id>
      <container_id nil="true"/>
      <program_id nil="true"/>
      <participant_id>2</participant_id>
      <name>Harrison Ford 2</name>
      <role>Actor</role>
      <role_category nil="true"/>
      <characters>
        <character>Han Solo</character>
      </characters>
      <external_image_paths/>
    </mediography>
    <mediography>
      <id>3</id>
      <media_id>3</media_id>
      <container_id nil="true"/>
      <program_id nil="true"/>
      <participant_id>3</participant_id>
      <name>Harrison Ford 3</name>
      <role>Actor</role>
      <role_category nil="true"/>
      <characters>
        <character>Han Solo</character>
      </characters>
      <external_image_paths/>
    </mediography>
  </mediographies>
</response>
Response Fields:
  • (Integer) mediography[id]
    The unique identifier of the mediography.
  • (Integer) mediography[media_id]
    The media_id associated with this mediography.
  • (Integer) mediography[container_id]
    The container_id associated with this mediography.
  • (Integer) mediography[program_id]
    The program_id associated with this mediography.
  • (Integer) mediography[contributor_id]
    The contributor_id associated with this mediography.
  • (String) mediography[name]
    The name associated with this mediography.
  • (String) mediography[role_category]
    The role_category such as crew, cast, etc.
  • (String) mediography[characters]
    The characters this contributor played in this mediography.
  • (String) mediography[role]
    The role of the contributor for this mediography.
  • (String) mediography[images]
    The images associated with this mediography.

Url:

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

Returns the specified mediography.

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

<response>
  <mediography>
    <id>1</id>
    <media_id>1</media_id>
    <container_id nil="true"/>
    <program_id nil="true"/>
    <participant_id>1</participant_id>
    <name>Harrison Ford 4</name>
    <role>Actor</role>
    <role_category nil="true"/>
    <characters>
      <character>Han Solo</character>
    </characters>
    <external_image_paths/>
  </mediography>
</response>
Response Fields:
  • (Integer) mediography[id]
    The unique identifier of the mediography.
  • (Integer) mediography[media_id]
    The media_id associated with this mediography.
  • (Integer) mediography[container_id]
    The container_id associated with this mediography.
  • (Integer) mediography[program_id]
    The program_id associated with this mediography.
  • (Integer) mediography[contributor_id]
    The contributor_id associated with this mediography.
  • (String) mediography[name]
    The name associated with this mediography.
  • (String) mediography[role_category]
    The role_category such as crew, cast, etc.
  • (String) mediography[characters]
    The characters this contributor played in this mediography.
  • (String) mediography[role]
    The role of the contributor for this mediography.
  • (String) mediography[images]
    The images associated with this mediography.

Url:

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

Create a new mediography.

Note:
The associated media_id, role_id, and person_id must already exist.
Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (Integer) mediography[media_id]
    The media_id associated with this mediography.
  • (Integer) mediography[container_id]
    The container_id associated with this mediography.
  • (Integer) mediography[program_id]
    The program_id associated with this mediography.
  • (Integer) mediography[contributor_id]
    The contributor_id associated with this mediography.
  • (String) mediography[name]
    The name associated with this mediography.
  • (String) mediography[role_category]
    The role_category such as crew, cast, etc.
  • (String) mediography[characters]
    The characters this contributor played in this mediography.
  • (String) mediography[role]
    The role of the contributor for this mediography.
  • (String) mediography[images]
    The images associated with this mediography.
Example Request

The following request creates a mediography associated to media id 100, mediography role id 1, and mediography person id 1.
[POST] https://service_name.synctv.com/api/v2/mediographies.xml?mediography[media_id]=100&mediography[role_id]=1&mediography[person_id]=1&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Example Response
XML JSON

<response>
  <mediography>
    <id>1</id>
    <media_id>1</media_id>
    <container_id nil="true"/>
    <program_id nil="true"/>
    <participant_id>1</participant_id>
    <name>Harrison Ford 5</name>
    <role>Actor</role>
    <role_category nil="true"/>
    <characters>
      <character>Han Solo</character>
    </characters>
    <external_image_paths/>
  </mediography>
</response>
Response Fields:
  • (Integer) mediography[id]
    The unique identifier of the mediography.
  • (Integer) mediography[media_id]
    The media_id associated with this mediography.
  • (Integer) mediography[container_id]
    The container_id associated with this mediography.
  • (Integer) mediography[program_id]
    The program_id associated with this mediography.
  • (Integer) mediography[contributor_id]
    The contributor_id associated with this mediography.
  • (String) mediography[name]
    The name associated with this mediography.
  • (String) mediography[role_category]
    The role_category such as crew, cast, etc.
  • (String) mediography[characters]
    The characters this contributor played in this mediography.
  • (String) mediography[role]
    The role of the contributor for this mediography.
  • (String) mediography[images]
    The images associated with this mediography.

Url:

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

Update the specified mediography.

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 request modifies mediography with id 5 to be associated with media_id 65, mediography role_id 1, and mediography person_id 3.
[PUT] https://service_name.synctv.com/api/v2/mediography/5.xml?mediography[media_id]=65&mediography[role_id]=1&mediography[person_id]=3&access_id=1234&signature=674aaff974348eb1a1bdd72dce75053d
Request Field:
  • (Integer) mediography[media_id] — The media_id associated with this mediography.
  • (Integer) mediography[container_id] — The container_id associated with this mediography.
  • (Integer) mediography[program_id] — The program_id associated with this mediography.
  • (Integer) mediography[contributor_id] — The contributor_id associated with this mediography.
  • (String) mediography[name] — The name associated with this mediography.
  • (String) mediography[role_category] — The role_category such as crew, cast, etc.
  • (String) mediography[characters] — The characters this contributor played in this mediography.
  • (String) mediography[role] — The role of the contributor for this mediography.
  • (String) mediography[images] — The images associated with this mediography.
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>
    <message>Person record not found</message>
  </messages>
</response>

Url:

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

Delete the specified mediography.

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 mediography 100.
[DELETE] https://service_name.synctv.com/api/v2/mediography/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>