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:

  • Images

This document describes the APIs for different actions that can be performed on ingest images. Ingest images must be associated with either a media object or a container 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/images/image_asset_1345.png),
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. images/image_asset_1345.png).
Actions

Url:

  • [GET] /api/v2/media/:medium_id/ingest_images.[xml|json]
  • [GET] /api/v2/containers/:container_id/ingest_images.[xml|json]

Returns a list of ingest images associated with the specified media object or 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 example returns all ingest images associated with the specified media.
https://service_name.synctv.com/api/v2/media/100/ingest_images.xml

The following example returns all ingest images associated with the specified container.
https://service_name.synctv.com/api/v2/containers/200/ingest_images.xml
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) removable — Filters response based on the removable_assets value.
  • (String) stage_like — Filters response to include items that contain the specified value in the stage field (e.g. stage_like=archive).
  • (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_images>
    <ingest_image>
      <app_name>tf1</app_name>
      <created_at>2014-05-01T21:30:37Z</created_at>
      <updated_at>2014-05-01T21:30:37Z</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/media/image/ingest/file_1.jpg</file_path>
      <file_size>1001</file_size>
      <state>reset</state>
      <status>ok</status>
      <stage>none</stage>
      <message nil="true"/>
      <iteration>0</iteration>
      <removable_assets>false</removable_assets>
    </ingest_image>
    <ingest_image>
      <app_name>tf1</app_name>
      <created_at>2014-05-01T21:30:37Z</created_at>
      <updated_at>2014-05-01T21:30:37Z</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/media/image/ingest/file_2.jpg</file_path>
      <file_size>1002</file_size>
      <state>reset</state>
      <status>ok</status>
      <stage>none</stage>
      <message nil="true"/>
      <iteration>0</iteration>
      <removable_assets>false</removable_assets>
    </ingest_image>
  </ingest_images>
</response>
Response Fields:
  • (Response) ingest_images
    A list of ingest_image items. See below for a description of the ingest_image response fields.

Url:

  • [GET] /api/v2/media/:medium_id/ingest_images/count.[xml|json]
  • [GET] /api/v2/containers/:container_id/ingest_images/count.[xml|json]

Returns the count of ingest images.

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 images associated with the specified media.
https://service_name.synctv.com/api/v2/media/100/ingest_images/count.xml

The following example returns all ingest images associated with the specified container.
https://service_name.synctv.com/api/v2/containers/200/ingest_images.xml
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) removable — Filters response based on the removable_assets value.
  • (String) stage_like — Filters response to include items that contain the specified value in the stage field (e.g. stage_like=archive).
  • (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>
  <count>30</count>
  <code>1</code>
  <message>Successfully completed.</message>
</response>
Response Fields:
  • (Integer) count
    The image count.

Url:

  • [GET] /api/v2/media/:medium_id/ingest_images/:id.[xml|json]
  • [GET] /api/v2/containers/:container_id/ingest_images/:id.[xml|json]

Returns the specified ingest image.

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 ingest image 50 associated with media 100.
https://service_name.synctv.com/api/v2/media/100/ingest_images/50.xml

The following example returns information for ingest image 150 associated with container 200.
https://service_name.synctv.com/api/v2/containers/200/ingest_images/150.xml
Example Response
XML JSON

<response>
  <ingest_image>
    <app_name>tf1</app_name>
    <created_at>2014-05-01T21:30:41Z</created_at>
    <updated_at>2014-05-01T21:30:41Z</updated_at>
    <platform_ids>
      <platform_id>1</platform_id>
    </platform_ids>
    <priority>3</priority>
    <progress>0.0</progress>
    <id>150</id>
    <ingestable_type>Media</ingestable_type>
    <ingestable_id>1</ingestable_id>
    <file_path>filepath/media/image/ingest/file_3.jpg</file_path>
    <file_size>1003</file_size>
    <state>reset</state>
    <status>ok</status>
    <stage>none</stage>
    <message nil="true"/>
    <iteration>0</iteration>
    <removable_assets>false</removable_assets>
  </ingest_image>
</response>
Response Fields:
  • (Integer) ingest_image[id]
    The id of the ingest image.
  • (String) ingest_image[ingestable_type]
    Specifies the type of the ingest image. (Note: this field is only used by the content processing system).
  • (String) ingest_image[ingestable_id]
    Specifies the id of the ingest image type. (Note: this field is only used by the content processing system).
  • (String) ingest_image[file_path]
    Path to ingest image source file.
  • (Integer) ingest_image[file_size]
    The size (in bytes) of the ingest image source file
  • (String) ingest_image[stage]
    Current stage of ingest image. (Note: this field is only used by the content processing system).
  • (String) ingest_image[state]
    State of the ingest image [values: starting, started, stopping, stopped, resetting, reset, done].
  • (String) ingest_image[status]
    Status of the ingest image [values: ok, error].
  • (String) ingest_image[message]
    Additional information (if any) related to the current ingest image status.
  • (Integer) ingest_image[iteration]
    The count of ingest passing through the workflow.
  • (DateTime) ingest_image[created_at]
    The timestamp for when the ingest image was created.
  • (DateTime) ingest_image[updated_at]
    The timestamp for when the ingest image was last updated.
  • (String) ingest_image[app_name]
    The app this ingest image was created on.
  • (String) ingest_image[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_images.[xml|json]
  • [POST] /api/v2/containers/container_id/ingest_images.[xml|json]

Creates an ingest image.

Required Arguments:
  • (Integer) access_id
    Access id returned from Authorization (User) client_authorize.
  • (String) signature
    MD5 hash encoded string of query parameters.
  • (String) ingest_image[file_path]
    The path to the ingest file.
Example Request

The following example creates a new media ingest image record.
https://service_name.synctv.com/api/v2/media/100/ingest_images.xml?ingest_image[file_path]=/some/filepath/for/image.jpg

The following example creates a new container ingest image record.
https://service_name.synctv.com/api/v2/containers/200/ingest_images.xml?ingest_image[file_path]=/some/filepath/for/image.jpg
Example Response
XML JSON

<response>
  <ingest_image>
    <app_name>tf1</app_name>
    <created_at>2014-05-01T21:30:43Z</created_at>
    <updated_at>2014-05-01T21:30:43Z</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/media/image/ingest/file_4.jpg</file_path>
    <file_size>1004</file_size>
    <state>reset</state>
    <status>ok</status>
    <stage>none</stage>
    <message nil="true"/>
    <iteration>0</iteration>
    <removable_assets>false</removable_assets>
  </ingest_image>
</response>
Response Fields:
  • (Response) ingest_image
    See above for a description of the ingest_image response fields.

Url:

  • [PUT] /api/v2/media/medium_id/ingest_images/:id.[xml|json]
  • [PUT] /api/v2/containers/container_id/ingest_images/:id.[xml|json]

Updates an ingest image.

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 image file_path field.
https://service_name.synctv.com/api/v2/media/100/ingest_images/1.xml?ingest_image[file_path]="/my/new/filpath/image.jpg"

The following example updates the container ingest image file_path field.
https://service_name.synctv.com/api/v2/containers/200/ingest_images/1.xml?ingest_image[file_path]="/my/new/filpath/image.jpg"
Request Field:
  • (String) ingest_image[file_path] — The path to the ingest file
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_images/:id/start.[xml|json]
  • [PUT] /api/v2/containers/container_id/ingest_images/:id/start.[xml|json]

Starts processing of an ingest image.

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 media ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_images/1/start.xml

The following example starts processing of container ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/containers/200/ingest_images/1/start.xml
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_images/:id/stop.[xml|json]
  • [PUT] /api/v2/containers/container_id/ingest_images/:id/stop.[xml|json]

Stops processing of a ingest image.

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 media ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_images/1/stop.xml

The following example stops processing of container ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/containers/200/ingest_images/1/stop.xml
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_images/:id/reset.[xml|json]
  • [PUT] /api/v2/containers/container_id/ingest_images/:id/reset.[xml|json]

Resets an ingest image 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 media ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_images/1/reset.xml

The following example resets ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/containers/200/ingest_images/1/reset.xml
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_images/:id/remove.[xml|json]
  • [PUT] /api/v2/containers/container_id/ingest_images/:id/remove.[xml|json]

Remove the ingest image 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 media ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/media/100/ingest_images/1/remove.xml

The following example starts the process of removing container ingest image item with id == 1.
[PUT] https://service_name.synctv.com/api/v2/containers/200/ingest_images/1/remove.xml
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>