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:

  • Videos

This document describes the API for accessing ingest videos. Ingest videos must be associated with a media object.

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.
Note:
The file_path field represents either an absolute path to an externally-hosted ingest source asset
(e.g. htttp://our.filestore.com/videos/video_asset_1345.mp4),
or a relative path to a ingest source asset that as been uploaded to the SyncTV SFTP site or delivered by hard drive
(e.g. videos/video_asset_1345.mp4).
Actions

Url:

  • [GET] /api/v2/media/:medium_id/ingest_videos.[xml|json]

Returns a list of ingest videos associated with the specified media.

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 all ingest videos for the specified media.
https://service_name.synctv.com/api/v2/media/100/ingest_videos.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
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) stage — Filters response based on the stage value.
  • (String) state — Filters response based on the state value.
  • (String) status — Filters response based on the status value.
  • (String) stage_like — Filters response to include items that contain the specified value in the stage field (e.g. stage_like=archive).
  • (String) removable — Filters response based on the removable_assets value.
  • (DateTime) created_at_before — Filters response to include only items with created_at <= specified timestamp (e.g. created_at_before=2012-02-15T02:06:56Z).
  • (DateTime) created_at_after — Filters response to include only items with created_at >= specified timestamp (e.g. created_at_after=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_before — Filters response to include only items with updated_at <= specified timestamp (e.g. updated_at_before=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_after — Filters response to include only items with updated_at >= specified timestamp (e.g. updated_at_after=2012-02-15T02:06:56Z).
  • (String) with_app_name — Filters response to include only items with specified app_name.
  • (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) id — The unique identifier of the media.
  • (String) updated_at — The updated_at attribute of the media.
  • (String) created_at — The created_at of the media.
  • (String) status — Status of the media.
  • (Boolean) sort_descending — Reverse order of sort_order sorting, make it descending.
Example Response
XML JSON

<response>
  <ingest_videos>
    <ingest_video>
      <app_name>tf1</app_name>
      <created_at>2014-05-01T21:31:04Z</created_at>
      <updated_at>2014-05-01T21:31:04Z</updated_at>
      <platform_ids>
        <platform_id>1</platform_id>
      </platform_ids>
      <priority>3</priority>
      <progress>0.0</progress>
      <id>1</id>
      <ingestable_type>Media</ingestable_type>
      <ingestable_id>1</ingestable_id>
      <file_path>filepath/video/ingest/file_12.mp4</file_path>
      <audio_languages>
        <audio_language>eng</audio_language>
        <audio_language>fre</audio_language>
      </audio_languages>
      <subtitle_languages/>
      <interlaced>true</interlaced>
      <aspect_ratio>4:3</aspect_ratio>
      <start_point nil="true"/>
      <end_point nil="true"/>
      <file_size>1012</file_size>
      <state>reset</state>
      <status>ok</status>
      <stage>none</stage>
      <message nil="true"/>
      <iteration>0</iteration>
      <removable_assets>false</removable_assets>
    </ingest_video>
    <ingest_video>
      <app_name>tf1</app_name>
      <created_at>2014-05-01T21:31:04Z</created_at>
      <updated_at>2014-05-01T21:31:04Z</updated_at>
      <platform_ids>
        <platform_id>1</platform_id>
        <platform_id>2</platform_id>
      </platform_ids>
      <priority>3</priority>
      <progress>0.0</progress>
      <id>2</id>
      <ingestable_type>Media</ingestable_type>
      <ingestable_id>2</ingestable_id>
      <file_path>filepath/video/ingest/file_13.mp4</file_path>
      <audio_languages>
        <audio_language>eng</audio_language>
        <audio_language>fre</audio_language>
      </audio_languages>
      <subtitle_languages/>
      <interlaced>true</interlaced>
      <aspect_ratio>4:3</aspect_ratio>
      <start_point nil="true"/>
      <end_point nil="true"/>
      <file_size>1013</file_size>
      <state>reset</state>
      <status>ok</status>
      <stage>none</stage>
      <message nil="true"/>
      <iteration>0</iteration>
      <removable_assets>false</removable_assets>
    </ingest_video>
  </ingest_videos>
</response>
Response Fields:
  • (Response) ingest_videos
    A list of ingest_video items. See below for a description of the ingest_video response fields.

Url:

  • [GET] /api/v2/media/:medium_id/ingest_videos/count.[xml|json]

Returns the count of ingest videos.

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 count of all ingest videos for the specified media.
https://service_name.synctv.com/api/v2/media/100/ingest_videos/count.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
Request Field:
  • (String) stage — Filters response based on the stage value.
  • (String) state — Filters response based on the state value.
  • (String) status — Filters response based on the status value.
  • (String) stage_like — Filters response to include items that contain the specified value in the stage field (e.g. stage_like=archive).
  • (String) removable — Filters response based on the removable_assets value.
  • (DateTime) created_at_before — Filters response to include only items with created_at <= specified timestamp (e.g. created_at_before=2012-02-15T02:06:56Z).
  • (DateTime) created_at_after — Filters response to include only items with created_at >= specified timestamp (e.g. created_at_after=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_before — Filters response to include only items with updated_at <= specified timestamp (e.g. updated_at_before=2012-02-15T02:06:56Z).
  • (DateTime) updated_at_after — Filters response to include only items with updated_at >= specified timestamp (e.g. updated_at_after=2012-02-15T02:06:56Z).
  • (String) with_app_name — Filters response to include only items with specified app_name.
Example Response
XML JSON

<response>
  <ingest_videos>
    <ingest_video>
      <app_name>tf1</app_name>
      <created_at>2014-05-01T21:31:07Z</created_at>
      <updated_at>2014-05-01T21:31:07Z</updated_at>
      <platform_ids>
        <platform_id>1</platform_id>
      </platform_ids>
      <priority>3</priority>
      <progress>0.0</progress>
      <id>1</id>
      <ingestable_type>Media</ingestable_type>
      <ingestable_id>1</ingestable_id>
      <file_path>filepath/video/ingest/file_14.mp4</file_path>
      <audio_languages>
        <audio_language>eng</audio_language>
        <audio_language>fre</audio_language>
      </audio_languages>
      <subtitle_languages/>
      <interlaced>true</interlaced>
      <aspect_ratio>4:3</aspect_ratio>
      <start_point nil="true"/>
      <end_point nil="true"/>
      <file_size>1014</file_size>
      <state>reset</state>
      <status>ok</status>
      <stage>none</stage>
      <message nil="true"/>
      <iteration>0</iteration>
      <removable_assets>false</removable_assets>
    </ingest_video>
    <ingest_video>
      <app_name>tf1</app_name>
      <created_at>2014-05-01T21:31:07Z</created_at>
      <updated_at>2014-05-01T21:31:07Z</updated_at>
      <platform_ids>
        <platform_id>1</platform_id>
        <platform_id>2</platform_id>
      </platform_ids>
      <priority>3</priority>
      <progress>0.0</progress>
      <id>2</id>
      <ingestable_type>Media</ingestable_type>
      <ingestable_id>2</ingestable_id>
      <file_path>filepath/video/ingest/file_15.mp4</file_path>
      <audio_languages>
        <audio_language>eng</audio_language>
        <audio_language>fre</audio_language>
      </audio_languages>
      <subtitle_languages/>
      <interlaced>true</interlaced>
      <aspect_ratio>4:3</aspect_ratio>
      <start_point nil="true"/>
      <end_point nil="true"/>
      <file_size>1015</file_size>
      <state>reset</state>
      <status>ok</status>
      <stage>none</stage>
      <message nil="true"/>
      <iteration>0</iteration>
      <removable_assets>false</removable_assets>
    </ingest_video>
  </ingest_videos>
</response>

<response>
  <count>30</count>
  <code>1</code>
  <message>Successfully completed.</message>
</response>
Response Fields:
  • (Integer) count
    The video count.

Url:

  • [GET] /api/v2/media/:medium_id/ingest_videos/:id.[xml|json]

Returns a specified ingest video associated with the specified media.

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 the media ingest video 300 associated with media 100.
https://service_name.synctv.com/api/v2/media/100/ingest_videos/300.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
Example Response
XML JSON

<response>
  <ingest_video>
    <app_name>tf1</app_name>
    <created_at>2014-05-01T21:31:09Z</created_at>
    <updated_at>2014-05-01T21:31:09Z</updated_at>
    <platform_ids>
      <platform_id>1</platform_id>
    </platform_ids>
    <priority>3</priority>
    <progress>0.0</progress>
    <id>300</id>
    <ingestable_type>Media</ingestable_type>
    <ingestable_id>1</ingestable_id>
    <file_path>filepath/video/ingest/file_16.mp4</file_path>
    <audio_languages>
      <audio_language>eng</audio_language>
      <audio_language>fre</audio_language>
    </audio_languages>
    <subtitle_languages/>
    <interlaced>true</interlaced>
    <aspect_ratio>4:3</aspect_ratio>
    <start_point nil="true"/>
    <end_point nil="true"/>
    <file_size>1016</file_size>
    <state>reset</state>
    <status>ok</status>
    <stage>none</stage>
    <message nil="true"/>
    <iteration>0</iteration>
    <removable_assets>false</removable_assets>
  </ingest_video>
</response>
Response Fields:
  • (Integer) ingest_video[id]
    The id of the ingest video.
  • (String) ingest_video[ingestable_type]
    Specifies the type of the ingest video. (Note: this field is only used by the content processing system).
  • (String) ingest_video[ingestable_id]
    Specifies the id of the ingest video type. (Note: this field is only used by the content processing system).
  • (String) ingest_video[file_path]
    Path to ingest video source file.
  • (Integer) ingest_video[file_size]
    The size (in bytes) of the video ingest source file.
  • (Array) ingest_video[audio_languages]
    The 3-character audio language code for the ingest video (in ISO 639-2 format).
  • (Array) ingest_video[subtitle_languages]
    The 3-character subtitle language code for the ingest video (in ISO 639-2 format).
  • (Boolean) ingest_video[interlaced]
    True indicates the ingest video source file is interlaced.
  • (String) ingest_video[aspect_ratio]
    The aspect ratio of the ingest video source file (e.g. 4:3 or 16:9).
  • (Decimal) ingest_video[start_point]
    The encoding start point for the video source file (in fractional seconds, e.g. 120.34)
  • (Decimal) ingest_video[end_point]
    The encoding end point for the video source file (in fractional seconds, e.g. 240.34).
  • (String) ingest_video[stage]
    Current stage of ingest video. (Note: this field is only used by the content processing system).
  • (String) ingest_video[state]
    State of the ingest video [values: starting, started, stopping, stopped, resetting, reset, done].
  • (String) ingest_video[status]
    Status of the ingest video [values: ok, error].
  • (String) ingest_video[message]
    Additional information (if any) related to the current ingest video status.
  • (Integer) ingest_video[iteration]
    The count of ingest passing through the workflow.
  • (Boolean) ingest_video[removable_assets]
    Determines if any associated manfiests can be removed.
  • (DateTime) ingest_video[created_at]
    The timestamp for when the ingest video was created.
  • (DateTime) ingest_video[updated_at]
    The timestamp for when the ingest video was last updated.
  • (String) ingest_video[app_name]
    The app this ingest video was created on.
  • (String) ingest_video[priority]
    Numerical prority queue: 1 is highest and 5 is lowest (defaults to '3' if not set).

Url:

  • [POST] /api/v2/media/:medium_id/ingest_videos.[xml|json]

Creates a new ingest video.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (String) ingest_video[file_path]
    The path to the ingest file.
  • (Array) ingest_video[audio_languages][]
    The 3-character audio language code for the ingest video (in ISO 639-2 format).
Example Request

The following example creates a new media ingest video record.
https://service_name.synctv.com/api/v2/media/100/ingest_videos.xml?access_id=3251&ingest_video[file_path]=test/ingest_video/file_path.mp4&ingest_video[audio_languages]=eng&ingest_video[audio_languages]=fre&signature=129d2ad3a23826bfd77bd9da23768f02
Request Field:
  • (Array) ingest_video[subtitle_languages][] — The 3-character subtitle language code for the ingest video (in ISO 639-2 format).
  • (Boolean) ingest_video[interlaced] — True indicates the ingest file is interlaced.
  • (String) ingest_video[aspect_ratio] — Specifies the ingest file aspect ratio [values: 4:3 or 16:9].
  • (Decimal) ingest_video[start_point] — Specifies the encoding start point for the video source file (in fractional seconds, e.g. 120.34).
  • (Decimal) ingest_video[end_point] — Specifies the encoding end point for the video source file (in fractional seconds, e.g. 240.34).
  • (Array) ingest_video[platform_ids][] — The platform IDs this ingest video is going to be associated (to be assigned by admin role only).
Example Response
XML JSON

<response>
  <ingest_video>
    <app_name>tf1</app_name>
    <created_at>2014-05-01T21:31:13Z</created_at>
    <updated_at>2014-05-01T21:31:13Z</updated_at>
    <platform_ids>
      <platform_id>1</platform_id>
    </platform_ids>
    <priority>3</priority>
    <progress>0.0</progress>
    <id>1</id>
    <ingestable_type>Media</ingestable_type>
    <ingestable_id>1</ingestable_id>
    <file_path>filepath/video/ingest/file_17.mp4</file_path>
    <audio_languages>
      <audio_language>eng</audio_language>
      <audio_language>fre</audio_language>
    </audio_languages>
    <subtitle_languages/>
    <interlaced>true</interlaced>
    <aspect_ratio>4:3</aspect_ratio>
    <start_point nil="true"/>
    <end_point nil="true"/>
    <file_size>1017</file_size>
    <state>reset</state>
    <status>ok</status>
    <stage>none</stage>
    <message nil="true"/>
    <iteration>0</iteration>
    <removable_assets>false</removable_assets>
  </ingest_video>
</response>
Response Fields:
  • (Response) ingest_video
    See above for a description of the ingest_video response fields.

Url:

  • [PUT] /api/v2/media/:medium_id/ingest_videos/:id.[xml|json]

Updates an ingest video.

Note:
This will return only success or failure, no content.
Note:
Update is only allowed if the ingest is in the reset state.
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 the media ingest video audio_language field of ingest_video 1 associated with media 100.
https://service_name.synctv.com/api/v2/media/100/ingest_videos/1.xml?access_id=4321ingest_video[audio_languages]=fra&signature=129d2ad3a23826bfd77bd9da23768f02
Request Field:
  • (String) ingest_video[file_path] — The path to the ingest file.
  • (Array) ingest_video[audio_languages][] — The 3-character audio language code for the ingest video (in ISO 639-2 format).
  • (Array) ingest_video[subtitle_languages][] — The 3-character subtitle language code for the ingest video (in ISO 639-2 format).
  • (Boolean) ingest_video[interlaced] — True indicates the ingest file is interlaced.
  • (String) ingest_video[aspect_ratio] — Specifies the ingest file aspect ratio [values: 4:3 or 16:9].
  • (Decimal) ingest_video[start_point] — Specifies the encoding start point for the video source file (in fractional seconds, e.g. 120.34).
  • (Decimal) ingest_video[end_point] — Specifies the encoding end point for the video source file (in fractional seconds, e.g. 240.34).
  • (Array) ingest_video[platform_ids][] — The platform IDs this ingest video is going to be associated (to be assigned by admin role only).
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/media/:medium_id/ingest_videos/:id/start.[xml|json]

Starts processing of an ingest video.

Note:
This will return only success or failure, no content.
Note:
The ingest state must be 'stopped' or 'reset' before issuing this command.
The ingest state becomes 'starting' after the command is issued and transitions to 'started' after the command is completed.
Note:
Issuing the start command from the 'stopped' state resumes processing at the current ingest stage.
Issuing the start command from the 'reset' state begins processing at the initial ingest stage.
Note:
Ingest start is an asynchronous process. Progress can be obtained by monitoring the state and status fields.
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 starts processing of the ingest video item with id == 1 associated with media 100.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_videos/1/start.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
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/media/:medium_id/ingest_videos/:id/stop.[xml|json]

Stops processing of an ingest video.

Note:
This will return only success or failure, no content.
Note:
The ingest state must be 'started' before issuing this command.
The ingest state becomes 'stopping' after the command is issued and transitions to 'stopped' after the command is completed.
Note:
Ingest stop is an asynchronous process. Progress can be obtained by monitoring the state and status fields.
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 stops processing of the ingest video item with id == 1 associated with media 100.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_videos/1/stop.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
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/media/:medium_id/ingest_videos/:id/reset.[xml|json]

Resets a ingest video to initial state. Will cause iteration field to increment.

Note:
This will return only success or failure, no content.
Note:
The ingest state must be 'stopped' or 'done' before issuing this command.
The ingest state becomes 'resetting' after the command is issued and transitions to 'reset' after the command is completed.
Note:
Ingest reset is an asynchronous process. Progress can be obtained by monitoring the state and status fields.
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 resets the ingest video item with id == 1 associated with media 100.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_videos/1/reset.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
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/media/:medium_id/ingest_videos/:id/remove.[xml|json]

Removes the ingest video and all associated media, encodes, and manifests.

Note:
This will return only success or failure, no content.
Note:
The ingest state must be 'reset' before issuing this command.
The ingest state becomes 'removing' after the command is issued and transitions to 'removed' after the command is completed.
Note:
Remove is an asynchronous process. Progress can be obtained by monitoring the state and status fields.
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 starts the process of removing ingest video item with id == 1 associated with media 100.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_videos/1/remove.xml?access_id=4321&signature=129d2ad3a23826bfd77bd9da23768f02
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>