Backlot API Reference

version 2.0

https://api.ooyala.com/

Introduction

The Backlot REST API is designed to enable custom integrations between your platforms and Backlot services. Use cases include automated asset upload, configuration, and retrieval. Thus various Backlot UI actions can be performed programmatically using the Backlot API.

An overview of REST API conventions in the context of Backlot can be found here.
General Backlot REST API calls can be made using Scratchpad. Information on Scratchpad is available here.
API libraries for generating and signing requests may be found here under Backlot REST API Libraries.

Ad Sets

Ad sets are ad configurations which control the ad experience of an asset during playback. The API can be used to create, delete, and change the names of ad sets, as well as assign ad sets to assets. All other ad behavior must be defined through the Backlot UI.

/v2/ad_sets get post

get

View all ad sets.

A description of ad sets in terms of their fields is available here.

You will need to provide your api_key, expires, and signature parameters.

post

Create an ad set.

You will need to provide your api_key, expires, and signature parameters.

View all ad sets.

A description of ad sets in terms of their fields is available here.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/ad_sets?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{"items": [{
    "id": "Erk3j4k98dh34kshdjf892kjvmF7Diew",
    "name": "Default Ad Set",
    "default": true,
    "ads": [
        {
            "id": "b631e96f928bfe0a6c2ecb6f8c5b274c",
            "ad_source": "assets",
            "ad_type": "midroll",
            "duration": 30000,
            "click_url": "http://www.myclickurl.com",
            "tracking_pixel_url": "http://www.mytrackingpixel.com",
            "plays_before": 0,
            "plays_between": 1,
            "position_type": "milliseconds",
            "position": 30001,
            "embed_code": "01M2RqNDo05HgdgJvxCGoSma9ugJkqGy",
            "name": "My Ooyala Ad"
        },
        {
            "id": "2d9d162cf89c2cacb195f231c399f0a9",
            "ad_source": "VAST Compliant In-Stream",
            "ad_type": "cuepoint",
            "plays_before": 0,
            "plays_between": 1,
            "tag_url": "http://cdn.mycdn.com/mytag2.xml",
            "tracking_pixel_urls": ["http://www.mytrackingpixel.com"]
        },
        {
            "id": "86d3a04729040a815014b77d05a0fdbb",
            "ad_source": "YuMe Video",
            "ad_type": "postroll",
            "plays_before": 0,
            "plays_between": 1,
            "tag_url": "http://cdn.mycdn.com/mytag2.xml",
            "tracking_pixel_urls": ["http://www.mytrackingpixel.com"]
        }
    ]
}]}

Create an ad set.

You will need to provide your api_key, expires, and signature parameters.

Request

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "My new Ad Set",
  "default": true,
  "ads": [
    {
      "ad_source": "assets",
      "ad_type": "preroll",
      "embed_code": "01M2F0MTr3SWBB9dfAPT5xEsg8Gpy-jP",
      "plays_before": 0,
      "plays_between": 1,
      "click_url": "http://www.myclickurl.com",
      "tracking_pixel_urls": ["http://www.mytrackingpixel.com"]
    }
  ]
}

/v2/ad_sets/{set_id} get patch delete

get

View a given ad set specified by its ID. You may obtain the ID by using GET commands to view existing ad sets, for example [GET] /v2/ad_sets.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify the ad set specified by a given ID.

You may obtain the ID by using GET commands to view existing ad sets, for example [GET] /v2/ad_sets.

Note: When changing the name of the ad set, the name cannot contain hidden characters. Hidden characters are those with ASCII values between 0 and 31, except for 10 (newline) and 13 (carriage return).

You will need to provide your api_key, expires, and signature parameters.

delete

Delete the ad set specified by a given ID.

You may obtain the ID by using GET commands to view existing ad sets, for example [GET] /v2/ad_sets.

You will need to provide your api_key, expires, and signature parameters.

View a given ad set specified by its ID. You may obtain the ID by using GET commands to view existing ad sets, for example [GET] /v2/ad_sets.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

set_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


{
  "id": "Erk3j4k98dh34kshdjf892kjvmF7Diew",
  "name": "Default Ad Set",
  "default": true,
  "ads": [
    {
      "id": "b631e96f928bfe0a6c2ecb6f8c5b274c",
      "ad_source": "assets",
      "ad_type": "midroll",
      "duration": 30000,
      "click_url": "http://www.myclickurl.com",
      "tracking_pixel_url": "http://www.mytrackingpixel.com",
      "plays_before": 0,
      "plays_between": 1,
      "position_type": "milliseconds",
      "position": 30001,
      "embed_code": "01M2RqNDo05HgdgJvxCGoSma9ugJkqGy",
      "name": "My Ooyala Ad"
    },
    {
      "id": "2d9d162cf89c2cacb195f231c399f0a9",
      "ad_source": "VAST Compliant In-Stream",
      "ad_type": "cuepoint",
      "plays_before": 0,
      "plays_between": 1,
      "tag_url": "http://cdn.mycdn.com/mytag2.xml",
      "tracking_pixel_urls": ["http://www.mytrackingpixel.com"]
    },
    {
      "id": "86d3a04729040a815014b77d05a0fdbb",
      "ad_source": "YuMe Video",
      "ad_type": "postroll",
      "plays_before": 0,
      "plays_between": 1,
      "tag_url": "http://cdn.mycdn.com/mytag2.xml",
      "tracking_pixel_urls": ["http://www.mytrackingpixel.com"]
    }
  ]
}

Modify the ad set specified by a given ID.

You may obtain the ID by using GET commands to view existing ad sets, for example [GET] /v2/ad_sets.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

set_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "Renamed Ad Set",
  "default": true
}

/v2/ad_sets/{set_id}/ads post

post

Add an ad to an ad set.

You will need to provide your api_key, expires, and signature parameters.

Add an ad to an ad set.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

set_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "ad_source": "assets",
  "ad_type": "preroll",
  "embed_code": "01M2F0MTr3SWBB9dfAPT5xEsg8Gpy-jP",
  "plays_before": 0,
  "plays_between": 1,
  "click_url": "http://www.myclickurl.com",
  "tracking_pixel_urls": ["http://www.mytrackingpixel.com"]
}

/v2/ad_sets/{set_id}/ads/{ad_id} delete

delete

Delete an ad from an ad set by its ID.

You will need to provide your api_key, expires, and signature parameters.

Assets

An asset represents a piece of content, such as a video, audio, an ad, a channel, a remote asset, or a YouTube link.

/v2/assets get post

get

Returns an array of your assets. You may add an optional include parameter to ask for an array of items, e.g., labels, associated to your assets.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/assets for the URL.

Asset resources in the APIs have this structure:

• name - The name of the asset.

• description - A description of your asset.

• asset_type - The asset type can be one of

• video

• audio

• live_stream (deprecated)

• live_audio (deprecated)

• ad

• channel (deprecated)

• channel_set (deprecated)

• remote_asset

• youtube

• embed_code - Your asset ID. This embed code is also used for embedding video assets into HTML.

• created_at - Date and time of creation.

• updated_at - Date and time asset was updated.

• original_file_name - The original filename.

• status - The current status of your asset. This can be uploading, processing, paused, or live (deprecated). Setting a video's status to paused will prevent it from being played in the player.

• duration - The video's duration in milliseconds.

• preview_image_url - The URL of the image shown for this video in the player's start screen.

• external_id - You can set an external ID for any asset in your library, which can be helpful when integrating Backlot with other content management systems. An asset's external ID can be used instead of the asset's embed code anywhere an embed code is expected in our APIs. External IDs cannot contain commas (",") or slashes ("/"), and the same external ID cannot be assigned to two different assets.

• closed_captions_url - The URL for the closed captions file for this asset.

• publishing_rule_id - The ID for the publishing rule.

• time_restrictions - Time restrictions. This can be set to null to inherit from the publishing rule. Otherwise, the time restriction can be a time range:

• type - range

• start_date - The start date and time.

• end_date - The end date and time. Can be null.

or a recurring time slot:

• type - recurring - Recurring times don't include the hour, minutes, or seconds in the date fields.

• start_date - The start date.

• end_date - The end date. Can be null.

• recurring_days - An array of the days that are recurring.

• all_day - A boolean value. Start and end time are only shown when this is set to false.

• start_time - The start time.

• end_time - The end time.

• download_allowed - A string that is set to Y or N. Indicates whether download is allowed for video assets. By default, and for non-video assets, the parameter is set to N.

• stream_urls - The fields below are only present for remote assets. These are URLs to video files, one for each device. Valid video URLs are

• flash

• iphone

• ipad

• itunes

• source

The fields are:

• flash - Video file for Flash-enabled devices.

• iphone - URL for iPhone feeds.

• ipad - URL for iPad feeds.

• itunes - URL for iTunes feeds.

• source - URL for source feeds.

• is_live_stream - (Deprecated.) A boolean value indicating whether the asset is a live stream.

• The fields below are only present for live streams (deprecated).

• primary_entry_point - (Deprecated.) The primary point of entry.

• backup_entry_point - (Deprecated.) A backup point of entry.

• is_flash - (Deprecated.) A boolean value.

• is_ios - (Deprecated.) A boolean value.

• encodings - (Deprecated.) An array of objects encapsulating width, height, and bitrate.

• The fields below are only present for ads.

• disable_seek_for_standalone - A boolean value.

• click_url - A URL to which the ad will redirect upon being clicked.

• tracking_pixel_urls - An array of URLs called every time the ad is displayed.

post

Create an asset. This can be a video, audio, live_stream (deprecated), live_audio (deprecated), ad, channel (deprecated), channel_set (deprecated), remote_asset, or youtube.

Video

Uploading a video file is a four-step process:

Create an asset using this POST API call.
Obtain the asset ID of your asset. This is its embed code. One way to find this is by performing a GET v2/assets and getting your particular asset's embed code from the response.
GET the upload URL for the asset, and upload the file to that URL.
Mark the video as uploaded to begin video processing.

The required parameters for uploading a video are name, asset_type, file_name, and file_size.

Live Stream - Video (deprecated)

The required parameters for creating a video live stream are name, asset_type, primary_encoder_ip, password, encodings. The encodings parameter is a list of up to 8 items describing the different encodings available for the live stream. The password is the encoder password. The is_flash and is_ios parameters indicate whether the live stream will be playable on Flash or iOS devices, respectively.

Live Stream - Audio (deprecated)

The required parameters for creating an audio live stream are name, asset_type, and serving_url. The asset type in this case will be live_audio.

Channels and Channel Sets (deprecated)

The required parameters for creating a channel set are name and asset_type. The type must be set to channel or channel_set. You may make further modifications by subsequently using a PUT API call with the channel's ID.

Remote Assets

The required parameters for creating a remote asset are name, asset_type, duration, and stream_urls. The asset type in this case will be remote_asset. The stream URLs should be encoded as a JSON object consisting of key-value pairs, where the keys can be flash, iphone, ipad, itunes, and source.

YouTube Assets

A YouTube asset creates a link to a video on YouTube. If the asset is part of a YouTube syndication, metadata changes in Backlot will be synced to YouTube. The required parameters for creating a YouTube asset are name, asset_type, and youtube_id. The asset type should be youtube. No two assets in your account should have the same YouTube ID.

You will need to provide your api_key, expires, and signature parameters.

Returns an array of your assets. You may add an optional include parameter to ask for an array of items, e.g., labels, associated to your assets.

You will need to provide your api_key, expires, and signature parameters.

Asset resources in the APIs have this structure:

• name - The name of the asset.

• description - A description of your asset.

• asset_type - The asset type can be one of

• video

• audio

• live_stream (deprecated)

• live_audio (deprecated)

• ad

• channel (deprecated)

• channel_set (deprecated)

• remote_asset

• youtube

• embed_code - Your asset ID. This embed code is also used for embedding video assets into HTML.

• created_at - Date and time of creation.

• updated_at - Date and time asset was updated.

• original_file_name - The original filename.

• duration - The video's duration in milliseconds.

• preview_image_url - The URL of the image shown for this video in the player's start screen.

• closed_captions_url - The URL for the closed captions file for this asset.

• publishing_rule_id - The ID for the publishing rule.

• time_restrictions - Time restrictions. This can be set to null to inherit from the publishing rule. Otherwise, the time restriction can be a time range:

• type - range

• start_date - The start date and time.

• end_date - The end date and time. Can be null.

or a recurring time slot:

• type - recurring - Recurring times don't include the hour, minutes, or seconds in the date fields.

• start_date - The start date.

• end_date - The end date. Can be null.

• recurring_days - An array of the days that are recurring.

• all_day - A boolean value. Start and end time are only shown when this is set to false.

• start_time - The start time.

• end_time - The end time.

• download_allowed - A string that is set to Y or N. Indicates whether download is allowed for video assets. By default, and for non-video assets, the parameter is set to N.

• stream_urls - The fields below are only present for remote assets. These are URLs to video files, one for each device. Valid video URLs are

• flash

• iphone

• ipad

• itunes

• source

The fields are:

• flash - Video file for Flash-enabled devices.

• iphone - URL for iPhone feeds.

• ipad - URL for iPad feeds.

• itunes - URL for iTunes feeds.

• source - URL for source feeds.

• is_live_stream - (Deprecated.) A boolean value indicating whether the asset is a live stream.

• The fields below are only present for live streams (deprecated).

• primary_entry_point - (Deprecated.) The primary point of entry.

• backup_entry_point - (Deprecated.) A backup point of entry.

• is_flash - (Deprecated.) A boolean value.

• is_ios - (Deprecated.) A boolean value.

• encodings - (Deprecated.) An array of objects encapsulating width, height, and bitrate.

• The fields below are only present for ads.

• disable_seek_for_standalone - A boolean value.

• click_url - A URL to which the ad will redirect upon being clicked.

• tracking_pixel_urls - An array of URLs called every time the ad is displayed.

Request
Response

Query Parameters

include: (string)
Set this to a resource to get a list of those resources assigned to your assets. This parameter can be set to labels or metadata.
include_sub_accounts: (boolean)
Set this to true to fetch all assets including subaccounts' assets.
orderby: (string)
Descriptors by which to sort results. See the query API for information on this parameter.
limit: (integer)
The maximum number of results to return. If you receive more results than the specified value, the next page of results can be accessed with the page_token.
page_token: (string)
A URL returned by the previous API request that enables you to page through results. If there is no remaining data available to display, no token is returned. This is useful if you are using a limit to restrict the number of results in your API call. Thus, an example query might look like [GET] /v2/assets?limit=2&page_token=1332345124%3B0wZTQ4NDpW27FQgXF6zry0b42OI76GZN.
where: (string)
See the query API for information on this parameter.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/assets?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Your list of assets is provided:

Body

Type: application/json

Example:

{
 "items": [   {
   "duration": "1500",
   "time_restrictions": null,
   "download_allowed": "N",
   "ad_set_id": null,
   "created_at": "2015-09-30T21:12:53Z",
   "hosted_at": "",
   "player_id": "5510596cec91409989dc258390edf182",
   "embed_code": "VpMzr2pwnp9PB_LVFaRUnnofJJAat2Js",
   "preview_image_url": "http://ak.c.ooyala.com/p3amcyOiDTJCL6iVHOgVxISRyU1qoEFy/jq3c6dntusNSL-kX5kdDoxOjBoO6F6AA",
   "publishing_rule_id": "646b4f931194404eb2bbd912ef802111",
   "description": "",
   "asset_type": "video",
   "name": "MyMovie",
   "external_id": null,
   "status": "live",
   "updated_at": "2016-09-19T10:37:55Z",
   "original_file_name": "MyMovie.MOV"
  }  ]
}

Create an asset. This can be a video, audio, live_stream (deprecated), live_audio (deprecated), ad, channel (deprecated), channel_set (deprecated), remote_asset, or youtube.

Video

Uploading a video file is a four-step process:

Create an asset using this POST API call.
Obtain the asset ID of your asset. This is its embed code. One way to find this is by performing a GET v2/assets and getting your particular asset's embed code from the response.
GET the upload URL for the asset, and upload the file to that URL.
Mark the video as uploaded to begin video processing.

The required parameters for uploading a video are name, asset_type, file_name, and file_size.

Live Stream - Video (deprecated)

Live Stream - Audio (deprecated)

The required parameters for creating an audio live stream are name, asset_type, and serving_url. The asset type in this case will be live_audio.

Channels and Channel Sets (deprecated)

Remote Assets

YouTube Assets

You will need to provide your api_key, expires, and signature parameters.

Request

Query Parameters

name: required (string)
A custom name for your asset.
asset_type: required (string)
Can be video, audio, live_stream (deprecated), live_audio (deprecated), ad, channel (deprecated), channel_set (deprecated), remote_asset, or youtube.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
file_name: (string)
Required for uploading a video. The filename of your asset.
file_size: (integer)
Required for uploading a video. The size of your file in bytes.
chunk_size: (integer)
Optional parameter for uploading a video. If provided, it will allow you to upload the video in multiple chunks. Uploading a relatively large file in separate chunks can make the upload process faster and more reliable. If the given chunk size is smaller than the file size, multiple URLs will be returned when getting the asset's uploading URLs.
post_processing_status: (string)
Optional parameter for uploading a video. This can be live or paused. The default status is live.
download_allowed: (string - default: N)
Optional parameter for a video asset. If set to Y, it indicates that the video can be downloaded. If the asset is not a video, or if download is not allowed, then the parameter is set to N. By default, the parameter is set to N.

If the parameter is set to a string other than Y or N, then a 403 (invalid input) will be returned.

Example:
```
curl -X POST -d '{"name":"example-video.mp4", "asset_type":"video","file_name":"video-1.mp4","file_size":1124814,"download_allowed":"Y"}' -H "X_API_KEY:<<API_KEY>>" "https://api.ooyala.com/v2/assets"
```
external_id: (string)
An optional ID that would have been assigned to your asset externally from Backlot.

Don't set the external_id to be null by setting "" or "null". Null external IDs cannot be searched for later.
encodings: (string)
Required for video live streams (deprecated). An array of objects encapsulating width, height, and bitrate. A list of up to 8 items describing the different encodings available for the live stream.
primary_encoder_ip: (string)
Required for video live streams (deprecated). The IP of the primary encoder.
password: (string)
Required for video live streams (deprecated). The encoder password.
is_flash: (boolean)
Optional parameter for live streams (deprecated) indicating whether the video will be playable on Flash.
is_ios: (boolean)
Optional parameter for live streams (deprecated) indicating whether the video will be playable on iOS.
serving_url: (string)
Required for audio live streams (deprecated). The URL serving the audio live stream.
duration: (integer)
Required for remote assets. A video's duration in milliseconds.
stream_urls: (string)
Required for remote assets, and should only be present for those. The keys can be flash, iphone, ipad, itunes, and source.
youtube_id: (string)
Required for YouTube assets.

Body

Type: application/json

Example:

{
  "name": "My two-minute-long video",
  "file_name": "my_source_file.avi",
  "asset_type": "video",
  "file_size": 412895,
  "chunk_size": 100000,
  "post_processing_status": "paused"
}

/v2/assets/{asset_id} get post patch delete

An asset as specified by its ID. Your asset's ID is its embed code.

get

Get an asset with specified ID. Your asset's ID is its embed code.

If your asset is of youtube type, a GET call response will display all YouTube IDs associated with the asset's embed code.

You will need to provide your api_key, expires, and signature parameters.

post

Replace an asset with specified ID. Your asset's ID is its embed code. See this article on creating assets in general for more detailed information.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify an asset with specified ID. Your asset's ID is its embed code.

You may choose to add an ad set to your asset by including its ID in the PATCH request. You may remove it by setting the ad set's ID to null.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete an asset with specified ID. Your asset's ID is its embed code.

Deleted assets are still kept track of, and you can use this API call to GET them.

You will need to provide your api_key, expires, and signature parameters.

Get an asset with specified ID. Your asset's ID is its embed code.

If your asset is of youtube type, a GET call response will display all YouTube IDs associated with the asset's embed code.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

include: (string)
Set this to a resource to get a list of those resources assigned to your asset. This parameter can be set to labels, metadata, or primary_preview_image.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/assets/VpMzr2pwnp9PB_LVFaRUnnofJJAat2Js?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

An encapsulation of your asset:

Body

Type: application/json

Example:

{
    "name": "My Song",
    "description": "A song I recorded.",
    "asset_type": "video",
    "embed_code": "VpMzr2pwnp9PB_LVFaRUnnofJJAat2Js",
    "created_at": "2010-08-24T00:24:42-00:00",
    "updated_at": "2011-05-13T11:42:14-00:00",
    "original_file_name": "my_song.mp4",
    "status": "live",
    "duration": 636053,
    "preview_image_url": "http://ak.c.ooyala.com/p3amcyOiDTJCL6iVHOgVxISRyU1qoEFy/jq3c6dntusNSL-kX5kdDoxOjBoO6F6AA",
    "external_id": "my_external_id1",
    "closed_captions_url": "http://ak.c.ooyala.com/p3amcyOiDTJCL6iVHOgVxISRyU1qoEFy/128303732",
    "publishing_rule_id": "646b4f931194404eb2bbd912ef802111",
    "time_restrictions": {
        "type": "recurring",
        "start_date": "2011-01-01",
        "end_date": null,
        "recurring_days": [
            "SUN",
            "MON",
            "TUE",
            "WED",
            "THU",
            "FRI",
            "SAT"
        ],
        "all_day": false,
        "start_time": "20:00:00",
        "end_time": "23:59:59"
    },
    "download_allowed": "N",
    "stream_urls": {
        "flash": "http://example.com/my_flash_file.flv",
        "iphone": "http://example.com/iphone_compatible_file.mp4",
        "ipad": "http://example.com/ipad_compatible_file.mp4",
        "itunes": "http://example.com/itunes_compatible_file.mp4",
        "source": "http://example.com/source_file.mp4"
    },
    "is_live_stream": true,
    "primary_entry_point": "rtmp://a.ep12372.i.akamaientrypoint.net/EntryPoint",
    "backup_entry_point": "rtmp://b.ep11372.i.akamaientrypoint.net/EntryPoint",
    "is_flash": true,
    "is_ios": false,
    "encodings": [
        {
            "width": 800,
            "height": 600,
            "bitrate": 300
        },
        {
            "width": 800,
            "height": 600,
            "bitrate": 600
        }
    ],
    "disable_seek_for_standalone": "true",
    "click_url": "http://clickurl.com",
    "tracking_pixel_urls": [
        "http://trackingpixelurl.com",
        "http://trackingurl.net"
    ]
}

Modify an asset with specified ID. Your asset's ID is its embed code.

You may choose to add an ad set to your asset by including its ID in the PATCH request. You may remove it by setting the ad set's ID to null.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "new asset name",
  "ad_set_id": "Erk3j4k98dh34kshdjf892kjvmF7Diew"
}

/v2/assets/{asset_id}/ad_set get

get

View the ad set assigned to an asset. Your asset's ID is its embed code.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/closed_captions get put delete

get

Get the closed captions file for a video asset. Your asset's ID is its embed code.

When closed captions files are assigned to a video, they are shown in the player during playback. The URL of the closed captions file is in the field closed_captions_url of the asset resource. Redirection to the URL of the closed captions file takes place using standard HTTP 302 redirect mechanism. The location header contains the redirect URL.

You will need to provide your api_key, expires, and signature parameters.

A listing of closed caption language codes is provided here.

put

Set or replace the closed captions file for a video asset. Your asset's ID is its embed code. The body of the request should be the closed captions file. The file should be in DFXP format.

When closed captions files are assigned to a video, they are shown in the player during playback. The URL of the closed captions file is in the field closed_captions_url of the asset resource.

You will need to provide your api_key, expires, and signature parameters.

A listing of closed caption language codes is provided here.

delete

Remove closed captions file from a video asset. Your asset's ID is its embed code.

You will need to provide your api_key, expires, and signature parameters.

A listing of closed caption language codes is provided here.

/v2/assets/{asset_id}/drm_attributes/{drm_type} get patch

get

Fetch all the attributes for a given DRM type.

If you package content using DRM and want Ooyala to serve licenses for that content, you will need to set some attributes per asset.

• For Widevine, you must set the id to the widevine asset ID.

• For Playready, you must set the key_id and the content_key. The content_key has the format content_key_version, where version is an integer that matches the one in the license acquisition URL. For example, if the license acquisition URL is http://player.ooyala.com/sas/drm2/jqbkH9m/UPHGNsr/playready/ooyala/version/3, then the corresponding key becomes content_key_3.

You will need to provide your api_key, expires, and signature parameters.

patch

Add or update an attribute for a given DRM type.

If you package content using DRM and want Ooyala to serve licenses for that content, you will need to set some attributes per asset.

• For Widevine, you must set the id to the widevine asset ID.

You can delete an attribute by setting the attribute value to null.

You will need to provide your api_key, expires, and signature parameters.

Add or update an attribute for a given DRM type.

If you package content using DRM and want Ooyala to serve licenses for that content, you will need to set some attributes per asset.

• For Widevine, you must set the id to the widevine asset ID.

You can delete an attribute by setting the attribute value to null.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

asset_id: required (string)
drm_type: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "id": "12345"
}

/v2/assets/{asset_id}/generated_preview_images get

get

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Issuing this request will return a list of image URLs and the time at which they appear in your movie. These are images generated by transcoding.

You will need to provide your api_key, expires, and signature parameters.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Issuing this request will return a list of image URLs and the time at which they appear in your movie. These are images generated by transcoding.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


[
  { "url": "http://ak.c.ooyala.com/your_movie/image1.jpeg", "time": 15 },
  { "url": "http://ak.c.ooyala.com/your_movie/image2.jpeg", "time": 30 }
]

/v2/assets/{asset_id}/labels get post

get

View the labels assigned to a given asset.

You will need to provide your api_key, expires, and signature parameters.

post

Add any array of labels to an asset. The array should contain the label IDs.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/labels/{label_id} put delete

put

Assign a label by its ID to a given asset.

You will need to provide your api_key, expires, and signature parameters.

delete

Unassign a label by its ID from a given asset.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/metadata get put patch delete

get

View an asset's custom metadata. Custom metadata is a list of name-value string pairs that you can associate with any asset. This custom metadata is also available via the player's JavaScript APIs.

You may also query this using the include parameter with the v2/assets or v2/assets/{asset_id} endpoint.

You will need to provide your api_key, expires, and signature parameters.

put

Set or replace an asset's custom metadata. Custom metadata is a list of name-value string pairs that you can associate with any asset. This custom metadata is also available via the player's JavaScript APIs.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify an asset's custom metadata. Custom metadata is a list of name-value string pairs that you can associate with any asset. This custom metadata is also available via the player's JavaScript APIs.

You will need to provide your api_key, expires, and signature parameters.

delete

Remove all of an asset's custom metadata. Custom metadata is a list of name-value string pairs that you can associate with any asset. This custom metadata is also available via the player's JavaScript APIs.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/movie_urls get post

get

Returns all URLs for a remote movie asset.

You will need to provide your api_key, expires, and signature parameters.

post

Specify the URLs for a remote movie asset.

The body of the POST should contain an associative array (JSON object) with the type of format as the key and the URL as the value. You identify the type of format by choosing its corresponding number from the supported formats table. Do not update more than 3 URLs at a time. To update more than 3 URLs, call the route more than once, each time with no more than 3 URLs. The admissible format types are:

• dash

• hds

• hls

• mp4

• akamai_hd2_hds

• akamai_hd2_hls

• rtmp

• smooth

You will need to provide your api_key, expires, and signature parameters.

Returns all URLs for a remote movie asset.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Upon success, the value 200 (success) is returned, along with all the URLs for the movie:

Body

Type: application/json

Example:


{
   "dash" : "https://dash.ooyala.com",
   "hls" : "https://hls.ooyala.com",
   "hds" : "http://hds.ooyala.com",
   "smooth" : "http://smooth.ooyala.com"
}

HTTP status code 404

If the route is called for an asset that does not exist:

Body

Type: application/json

Example:


{
   "message": "No asset exists with the id X."
}

Specify the URLs for a remote movie asset.

• dash

• hds

• hls

• mp4

• akamai_hd2_hds

• akamai_hd2_hls

• rtmp

• smooth

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
   "dash" : "https://dash.ooyala.com",
   "hls" : "https://hls.ooyala.com",
   "smooth" : "http://smooth.ooyala.com"
}

HTTP status code 200

Upon success, the value 200 (success) is returned, along with all the URLs for the movie:

Body

Type: application/json

Example:


{
   "dash" : "https://dash.ooyala.com",
   "hls" : "https://hls.ooyala.com",
   "hds" : "http://hds.ooyala.com",
   "smooth" : "http://smooth.ooyala.com"
}

HTTP status code 400

If an unsupported format type is used, or if you attempt to POST more than three URLs simultaneously, a 400 (invalid request) value is returned:

Body

Type: application/json

Example:


{
   "message": "You cannot update more than 3 urls at a time"
}

HTTP status code 404

If the route is called for an asset that does not exist:

Body

Type: application/json

Example:


{
   "message": "No asset exists with the id X."
}

/v2/assets/{asset_id}/movie_urls/{type} delete

delete

Deletes the URL of the specified format type for a remote movie asset.

The admissible format types are:

• dash

• hds

• hls

• mp4

• akamai_hd2_hds

• akamai_hd2_hls

• rtmp

• smooth

You will need to provide your api_key, expires, and signature parameters.

Deletes the URL of the specified format type for a remote movie asset.

The admissible format types are:

• dash

• hds

• hls

• mp4

• akamai_hd2_hds

• akamai_hd2_hls

• rtmp

• smooth

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)
type: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Upon success, the value 200 (success) is returned, along with all the (remaining) URLs for the movie:

Body

Type: application/json

Example:


{
   "dash" : "https://dash.ooyala.com",
   "hls" : "https://hls.ooyala.com",
   "hds" : "http://hds.ooyala.com",
   "smooth" : "http://smooth.ooyala.com"
}

HTTP status code 400

If an unsupported format type is used, a 400 (invalid request) value is returned.

HTTP status code 404

If the route is called for an asset that does not exist:

Body

Type: application/json

Example:


{
   "message": "No asset exists with the id X."
}

/v2/assets/{asset_id}/player get

get

View the player assigned to an asset. Your asset's ID is its embed code.

You will need to provide your api_key, expires, and signature parameters.

View the player assigned to an asset. Your asset's ID is its embed code.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Your list of assets is provided:

Body

Type: application/json

Example:

{
  "id": "5510596cec91409989dc258390edf182",
  "name": "Default player",
  "is_default": true,
  "provider_homepage_url": null,
  "default_closed_caption_language": "",
  "ooyala_branding": {
    "show_info_screen_homepage_link": true,
    "show_share_button": true,
    "twitter_sharing": false,
    "show_ad_countdown": true,
    "show_info_screen_title": true,
    "show_info_button": true,
    "url_sharing": true,
    "facebook_sharing": false,
    "email_sharing": true,
    "show_info_screen_description": false,
    "show_bitrate_button": false,
    "digg_sharing": false,
    "show_embed_button": true,
    "show_channel_button": true,
    "show_end_screen_replay_button": true,
    "accent_color": "#ffbb00",
    "enable_error_screen": true,
    "show_volume_button": true,
    "chromeless": true
  },
  "related_videos": {
    "source": "shared_labels",
    "click_behavior": "new_page",
    "order": "desc",
    "sort": "upload_time",
    "labels": []
  },
  "player_version": "V4",
  "release_version": "production",
  "scrubber": {
    "always_show": false,
    "image_url": null
  },
  "watermark": {
    "image_url": null,
    "click_url": null,
    "alpha": 1.0,
    "position": "bottom-right"
  },
  "playback": {
    "buffer_on_pause": false
  }
}

/v2/assets/{asset_id}/player/{player_id} put

put

Assign a specific player to an asset. Your asset's ID is its embed code.

All assets are assigned to your default player when first created. You can reassign the default player to your assets using the PUT call.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/preview_image_files get post put delete

get

Get images you uploaded.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

post

Add one or more preview image files to an asset's current preview image files. In the body of the request, specify an array of files you wish to add.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

put

Replace an asset's current preview image files with one or more preview image files. In the body of the request, specify an array of files you wish to add.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete all preview images you uploaded.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

Get images you uploaded.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


{
    "width": 600,
    "height": 800,
    "url": "http://ak.c.ooyala.com/promo150761232",
    "id": "150761232"
}

Add one or more preview image files to an asset's current preview image files. In the body of the request, specify an array of files you wish to add.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

[  
   {  
      "url":"http://www.mysite.com/my_medium_image.png",
      "width":1280,
      "height":720
   },
   {  
      "url":"http://www.mysite.com/my_small_image.png",
      "width":640,
      "height":480
   }
]

HTTP status code 200

Body

Type: application/json

Example:

[  
   {
      "url":"http://www.mysite.com/my_big_image.png",
      "width":1920,
      "height":1080
   },
   {  
      "url":"http://www.mysite.com/my_medium_image.png",
      "width":1280,
      "height":720
   },
   {  
      "url":"http://www.mysite.com/my_small_image.png",
      "width":640,
      "height":480
   }
]

Replace an asset's current preview image files with one or more preview image files. In the body of the request, specify an array of files you wish to add.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

[  
   {
      "url":"http://www.mysite.com/my_big_image.png",
      "width":1920,
      "height":1080
   },
   {  
      "url":"http://www.mysite.com/my_medium_image.png",
      "width":1280,
      "height":720
   },
   {  
      "url":"http://www.mysite.com/my_small_image.png",
      "width":640,
      "height":480
   }
]

HTTP status code 200

Body

Type: application/json

Example:

[  
   {
      "url":"http://www.mysite.com/my_big_image.png",
      "width":1920,
      "height":1080
   },
   {  
      "url":"http://www.mysite.com/my_medium_image.png",
      "width":1280,
      "height":720
   },
   {  
      "url":"http://www.mysite.com/my_small_image.png",
      "width":640,
      "height":480
   }
]

/v2/assets/{asset_id}/preview_image_files/{image_id} delete

delete

Delete an image you uploaded, as specified by its ID.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

Ooyala stores images you upload for use as preview images for your movie. A single preview image can be uploaded for each movie.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/preview_image_urls get post put delete

get

Get preview images you specified by URL.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

The preview image URLs must point to the same image at different resolutions.

You will need to provide your api_key, expires, and signature parameters.

post

Add a new preview image as specified by URL.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

The preview image URLs must point to the same image at different resolutions.

You will need to provide your api_key, expires, and signature parameters.

put

Replace all your preview images specified by URL with new ones. Note: this removes any preview image URLs you specified before.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

The preview image URLs must point to the same image at different resolutions.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete all preview images you specified by URL.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

The preview image URLs must point to the same image at different resolutions.

You will need to provide your api_key, expires, and signature parameters.

Get preview images you specified by URL.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

The preview image URLs must point to the same image at different resolutions.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


[
  {
    "width": 600,
    "height": 800,
    "url": "http://myimages.com/image1.jpeg"
  },
  {
    "width": 200,
    "height": 300,
    "url": "http://myimages.com/image2.jpeg"
  }
]

Add a new preview image as specified by URL.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

The preview image URLs must point to the same image at different resolutions.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


[
  {
    "width": 600,
    "height": 800,
    "url": "http://myimages.com/image1.jpeg"
  },
  {
    "width": 200,
    "height": 300,
    "url": "http://myimages.com/image2.jpeg"
  }
]

Replace all your preview images specified by URL with new ones. Note: this removes any preview image URLs you specified before.

There are three resources that an asset can obtain its preview image from: images generated at keyframes in your movie during transcoding, images you upload, and images you specify by URL.

The preview image URLs must point to the same image at different resolutions.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


[
  {
    "width": 600,
    "height": 800,
    "url": "http://myimages.com/image1.jpeg"
  },
  {
    "width": 200,
    "height": 300,
    "url": "http://myimages.com/image2.jpeg"
  }
]

/v2/assets/{asset_id}/primary_preview_image get put

get

Get the primary preview image for your asset.

The primary preview image has a type: (transcoding) generated, remote_url, or uploaded_file. The video player will examine the images within that type and pick one with the appropriate image quality and resolution to fit the device and connection quality.

You will need to provide your api_key, expires, and signature parameters.

put

Select the primary preview image for your asset.

The primary preview image has a type: (transcoding) generated, remote_url, or uploaded_file. You specify the type. If the type is generated, also specify the time when the image was created. The video player will examine the images within that type and pick one with the appropriate image quality and resolution to fit the device and connection quality.

You will need to provide your api_key, expires, and signature parameters.

Get the primary preview image for your asset.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


{
  "type": "uploaded_file",
  "url": "http://ak.c.ooyala.com/img2.gif",
  "sizes": [
    { "width": 100, "height": 200, "url": "http://ak.c.ooyala.com/img1.gif" },
    { "width": 200, "height": 300, "url": "http://ak.c.ooyala.com/img2.gif" }
  ],
  "id": "img2.gif"
}

Select the primary preview image for your asset.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

asset_id: required (string)

Query Parameters

type: required (string)
The type that the primary preview image should have.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "type": "generated",
  "time": 15
}

/v2/assets/{asset_id}/publishing_rule get

get

View the publishing rule assigned to a given asset.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/publishing_rule/{rule_id} put

put

Assign a publishing rule by its ID to a given asset.

You will need to provide your api_key, expires, and signature parameters.

/v2/assets/{asset_id}/source_file_info get

get

Retrieve an asset's source file: An asset's source file is the original video file that was uploaded to Ooyala, prior to transcoding. You can retrieve information about this file as well as a link to download it.

This API will return a status code of 400 for assets which do not have uploaded source files, like channels (deprecated) and remote assets.

Note that URLs to source files are signed, and they expire after 72 hours.

The file_size is in bytes.

You will need to provide your api_key, expires, and signature parameters.

This API will return a status code of 400 for assets which do not have uploaded source files, like channels (deprecated) and remote assets.

Note that URLs to source files are signed, and they expire after 72 hours.

The file_size is in bytes.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


{
  "original_file_name": "lakeside.wmv",
  "source_file_url": "http://cms.ooyala.com/xhdG5nM?expires=1341187786&signature=uhbcz",
  "file_size": 25227886
}

/v2/assets/{asset_id}/streams get

get

Get the streams for a given asset: Assets are transcoded into different resolutions, codecs, and bitrates. Each of these is called a stream, and can be retrieved through an asset's streams collection.

The stream_type field can be either single or abr, indicating "adaptive bitrate playback".

The profile field can be either baseline, main, or high.

The is_source field will be true if, and only if, the queried item is, in fact, the original source file.

Among the items contained in the response will be a stream URL. To get the most accurate stream URL for the asset, use the Player v3 Authorization API or Player v4 Authorization API (depending on which Ooyala Player version you prefer to work with).

You will need to provide your api_key, expires, and signature parameters.

The stream_type field can be either single or abr, indicating "adaptive bitrate playback".

The profile field can be either baseline, main, or high.

The is_source field will be true if, and only if, the queried item is, in fact, the original source file.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


[
  {
    "stream_type": "single",
    "profile": "baseline",
    "video_height": 360,
    "video_width": 640,
    "is_source": false,
    "file_size": 17937644,
    "audio_codec": "aac",
    "video_codec": "h264",
    "average_video_bitrate": 300,
    "muxing_format": "MP4",
    "url": "http://ak.c.ooyala.com/VpMzr2pwnp9PB_LVFaRUnnofJJAat2Js/DOcJ-Fxa1rRg4gtGU3OjM8OjBhO4EUTl"
  },
  {
    "stream_type": "abr",
    "profile": "baseline",
    "video_height": 360,
    "video_width": 640,
    "is_source": false,
    "file_size": 41716636,
    "audio_codec": "aac",
    "video_codec": "h264",
    "average_video_bitrate": 900,
    "muxing_format": "TS",
    "url": "http://www.ooyala.com/player/ipad/80MGxj0sGW1vxNkF7LbMwJP3iPmhaotj.m3u8"
  }
]

/v2/assets/{asset_id}/uploading_urls get

get

Get upload URLs for a given asset. Your asset's ID is its embed code.

This is typically part of the workflow for uploading a video, as detailed in the description of POST v2/assets.

Each URL corresponds to a byte range of the file. If you're not using chunked uploading, you can simply make a PUT request with your entire file to the single URL given in this response. If you're using chunked uploading, upload the file in chunks, where each chunk corresponds with one of the URLs given in this response.

When uploading a URL or chunk in this context, do not sign the request as you would other requests. Simply PUT the chunk contents to the exact URLs. These URLs have already been signed for you.

For this GET request, you will need to provide your api_key, expires, and signature parameters.

Get upload URLs for a given asset. Your asset's ID is its embed code.

This is typically part of the workflow for uploading a video, as detailed in the description of POST v2/assets.

When uploading a URL or chunk in this context, do not sign the request as you would other requests. Simply PUT the chunk contents to the exact URLs. These URLs have already been signed for you.

For this GET request, you will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

asset_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


["http://upload.ooyala.com/zbxcgqkf1c/00000000-00100000",
 "http://upload.ooyala.com/fh7nz7pq62/00100000-00200518"]

/v2/assets/{asset_id}/upload_status put

put

Mark an asset as uploaded. Your asset's ID is its embed code.

This is typically part of the workflow for uploading a video, as detailed in the description of POST v2/assets.

This action will allow pre-processing of your asset to begin.

You will need to provide your api_key, expires, and signature parameters.

Mark an asset as uploaded. Your asset's ID is its embed code.

This is typically part of the workflow for uploading a video, as detailed in the description of POST v2/assets.

This action will allow pre-processing of your asset to begin.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

asset_id: required (string)

Query Parameters

status: required (string)
The status can be either uploaded or failed. Once the status of the video has been set to uploaded, processing of the file will begin. If the upload cannot be completed for some reason, you can abandon the upload by setting its status to failed.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{ "status": "uploaded" }

/v2/assets/{asset_id}/youtube get put patch

get

View YouTube information for an asset.

Remote assets and videos will be syndicated to YouTube if:

• The asset is part of a YouTube syndication. See syndications for details.

• The asset has a valid YouTube ID.

Video assets that are part of a YouTube syndication will be automatically uploaded to YouTube. Remote assets are not uploaded to YouTube. We sync an asset's metadata to YouTube after the YouTube ID is set. Metadata consists of the title, description and the youtube_syndication_settings.

A youtube_syndication_settings object has the following structure:

• private - A boolean value. If set to true, then private videos can only be viewed by people selected by the video's owner.

• mobile - A boolean value. If set to true, then YouTube can show the video on mobile phones.

• embeddable - A boolean value. If set to true, then the YouTube video can be embedded on third-party websites.

• keywords - An array of keywords.

You will need to provide your api_key, expires, and signature parameters.

put

Set or replace YouTube information for an asset.

Remote assets and videos will be syndicated to YouTube if:

• The asset is part of a YouTube syndication. See syndications for details.

• The asset has a valid YouTube ID.

A youtube_syndication_settings object has the following structure:

• private - A boolean value. If set to true, then private videos can only be viewed by people selected by the video's owner.

• mobile - A boolean value. If set to true, then YouTube can show the video on mobile phones.

• embeddable - A boolean value. If set to true, then the YouTube video can be embedded on third-party websites.

• keywords - An array of keywords.

You will need to provide your api_key, expires, and signature parameters.

patch

Update YouTube information for an asset.

If you change the youtube_video_id of the asset, then the asset is linked to the new YouTube video. The old video is not deleted from YouTube.

You will need to provide your api_key, expires, and signature parameters.

Set or replace YouTube information for an asset.

Remote assets and videos will be syndicated to YouTube if:

• The asset is part of a YouTube syndication. See syndications for details.

• The asset has a valid YouTube ID.

A youtube_syndication_settings object has the following structure:

• private - A boolean value. If set to true, then private videos can only be viewed by people selected by the video's owner.

• mobile - A boolean value. If set to true, then YouTube can show the video on mobile phones.

• embeddable - A boolean value. If set to true, then the YouTube video can be embedded on third-party websites.

• keywords - An array of keywords.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

asset_id: required (string)

Query Parameters

youtube_id: required (string)
An asset's YouTube ID.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "youtube_id": "oHg5SJYRHA0",
  "youtube_syndication_settings":
  {
    "private": false,
    "mobile": true,
    "embeddable": true,
    "keywords": ["test1", "test2"]
  }
}

/v2/assets/{channel_id}/lineup get put

get

(Deprecated.) View a channel's lineup. This returns an array containing embed codes (of channel assets) and external IDs.

You will need to provide your api_key, expires, and signature parameters.

put

(Deprecated.) Create or replace a channel's lineup. Make this API request with an array containing embed codes (of assets) or external IDs.

Note that a channel's lineup cannot contain other channels or channel sets. A channel set's lineup can only contain channels.

You will need to provide your api_key, expires, and signature parameters.

(Deprecated.) View a channel's lineup. This returns an array containing embed codes (of channel assets) and external IDs.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

channel_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


["embed_code1", "embed_code2"]

(Deprecated.) Create or replace a channel's lineup. Make this API request with an array containing embed codes (of assets) or external IDs.

Note that a channel's lineup cannot contain other channels or channel sets. A channel set's lineup can only contain channels.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

channel_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


["embed_code1", "embed_code2"]

/v2/assets/{channel_id}/lineup/{asset_id} put delete

put

(Deprecated.) Add an asset to a channel lineup. The asset is specified through its embed code, or, if it is external, through an external ID.

You will need to provide your api_key, expires, and signature parameters.

delete

(Deprecated.) Remove an asset from a channel lineup. The asset is specified through its embed code, or, if it is external, through an external ID.

You will need to provide your api_key, expires, and signature parameters.

DRM Policies

A digital-rights management (DRM) policy is a set of configurations for supported DRM technologies. To create a custom DRM policy, please contact Ooyala support. Also see the section on provider-level DRM policies.

/v2/drm_policies get

get

View all DRM policies. Currently supported DRM technologies are Adobe Access, Playready, and Widevine. The properties of these known policies are described here.

You will need to provide your api_key, expires, and signature parameters.

View all DRM policies. Currently supported DRM technologies are Adobe Access, Playready, and Widevine. The properties of these known policies are described here.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/drm_policies?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
  "items": [
    {
        "id": "86ff97ae7c81495eacbd9a01feff0e10",
        "name": "HD Policy",
        "playready_policy": {
            "analog_video_extension_guid": "C3FD11C6-F8B7-4d20-B008-1DB17D61F2DA,3",
            "expiration_date":"60",
            "compressed_digital_video":"500",
            "analog_video":"150",
            "uncompressed_digital_video":"300"
        },
        "flashaccess_policy": {
            "analog_output_protection": "use_if_available_all",
            "digital_output_protection":"required",
            "minimum_security_level":10000
        },
        "widevine_policy": {
            "name":"sample_hd_policy",
            "license_duration": 300,
            "digital_copy_protection": "stop_video",
            "encryption_mode_indicator": "copying_prohibited",
            "analog_protection_system": "agc_on, 4_line_split_burst_on",
            "constrained_image_trigger": "none",
            "hdcp": "on",
            "analog_component_output_control": "analog_component_signal_output_allowed",
            "digital_component_output_control":"only_compressed_digital_signal_output"
        }
    }
  ]
}

/v2/drm_policies/{policy_id} get

get

View a given DRM policy specified by its ID. You may obtain the ID by using GET commands to view existing policies, for example [GET] /v2/drm_policies.

You will need to provide your api_key, expires, and signature parameters.

View a given DRM policy specified by its ID. You may obtain the ID by using GET commands to view existing policies, for example [GET] /v2/drm_policies.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

policy_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:

{
  "id": "86e224258a0441fbb19c8af7f8733d0f",
  "name": "an internal name for this playlist",
  "type": "movie",
  "sort_by": null,
  "limit": 10,
  "provider_id": 27645,
  "created_at": "2013-01-25T00:14:40Z",
  "updated_at": "2013-01-25T00:14:40Z",
  "items": [
    "M0YWNmODqougN5VrA1FIk02F3CH7Mq_d",
    "81YWNmODqT-3NfNatUGgJq9_XAR6blq8"
  ]
}

Deleted Assets

Use this API to view deleted assets.

/v2/deleted_assets get

get

Use this API to view deleted assets.

Note that the results are ordered in descending order based on when the asset was deleted. So the first asset returned in the response is the last asset to be deleted. The results are paged 500 assets to a single page. Subsequent pages can be retrieved from the page token that is also returned as part of the response.

You will need to provide your api_key, expires, and signature parameters.

Use this API to view deleted assets.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/deleted_assets?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
 "items": [   {
   "duration": "0",
   "asset_type": "video",
   "description": null,
   "id": "3718780",
   "embed_code": "l1cHBnMjqbmqOtirhi78ZbfZujCqBVOq",
   "uploaded_by_user": null,
   "created_at": "2011-05-20T18:25:28Z",
   "name": "my currently uploading video",
   "provider_id": "28440",
   "deleted_at": "2012-07-11T21:06:11Z"
  }  ]
}

Labels

You can use labels to organize your content. They are used when searching for videos, retrieving analytics, and assigning external publishing groups.

/v2/labels get post

get

View all labels. You will need to provide your api_key, expires, and signature parameters.

post

Create a label. You may optionally include a parent ID to create the label as a child of an existing label with that ID.

You will need to provide your api_key, expires, and signature parameters.

View all labels. You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

is_root: (boolean)
Set this to true to view all top-level labels only.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/labels?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:

{
  "items": [
    {
        "id": "7b2e9a9d89724c439105646a4cc0d620",
        "name": "comedy",
        "full_name": "/movies/genres/comedy",
        "parent_id": "NWY4MTkxY2I4YjExODM1MTZmYTg5MTNm"
    }
  ]
}

Create a label. You may optionally include a parent ID to create the label as a child of an existing label with that ID.

You will need to provide your api_key, expires, and signature parameters.

Request

Query Parameters

parent_id: (string)
Specify this to create the label as a child of an existing label with that ID.
name: required (string)
A name for your label.
The name cannot contain hidden characters. Hidden characters are those with ASCII values between 0 and 31, except for 10 newline and 13 carriage return.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "parent_id": "ar95zdkrg",
  "name": "My New Label"
}

/v2/labels/by_full_path/{paths} get post

get

View all labels with the specified paths. {paths} is a comma-separated list of label paths. The paths must be CGI-escaped.

The API call returns a 400 status code if any of the paths do not exist. The response body specifies the existing and missing labels.

You will need to provide your api_key, expires, and signature parameters.

post

Create the labels with the specified paths. {paths} is a comma-separated list of label paths. The paths must be CGI-escaped.

This request creates any missing labels on the path in a fashion similar to the Unix command mkdir -p.

You will need to provide your api_key, expires, and signature parameters.

View all labels with the specified paths. {paths} is a comma-separated list of label paths. The paths must be CGI-escaped.

The API call returns a 400 status code if any of the paths do not exist. The response body specifies the existing and missing labels.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

paths: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/labels/by_full_path//sports/football/NFL,/animal+videos/buffaloes?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

/v2/labels/{label_id} get patch delete

get

View a label with specified ID. You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify a label specified by an ID.

You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete a specified label, as well as all its children.

You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

View a label with specified ID. You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

label_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/labels/7b2e9a9d89724c439105646a4cc0d620?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:

{
    "id": "7b2e9a9d89724c439105646a4cc0d620",
    "name": "comedy",
    "full_name": "/movies/genres/comedy",
    "parent_id": "NWY4MTkxY2I4YjExODM1MTZmYTg5MTNm"
}

Modify a label specified by an ID.

You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

label_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "My New Name"
}

/v2/labels/{label_id}/children get

get

View all the children (sublabels) of a label with a specified ID. You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

View all the children (sublabels) of a label with a specified ID. You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

label_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/labels/7b2e9a9d89724c439105646a4cc0d620/children?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:

{
  "items": [
    {
        "id": "7b2e9a9d89724c439105646a4cc0d620",
        "name": "comedy",
        "full_name": "/movies/genres/comedy",
        "parent_id": "NWY4MTkxY2I4YjExODM1MTZmYTg5MTNm"
    }
  ]
}

/v2/labels/{label_id}/assets get

get

View all the assets assigned to a label with a specified ID. You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

The results do not include assets assigned to sub-labels. For example, 'Baseball' is a sublabel of 'Sports'. Querying for the assets assigned to 'Sports' will not return assets assigned to 'Baseball'.

You will need to provide your api_key, expires, and signature parameters.

View all the assets assigned to a label with a specified ID. You may obtain the ID by using GET commands to view existing labels, for example [GET] /v2/labels.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

label_id: required (string)

Query Parameters

include: (string)
You may set this parameter to metadata to have asset metadata included in the response.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/labels/7b2e9a9d89724c439105646a4cc0d620/assets?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Your list of assets is provided:

Body

Type: application/json

Example:

{
 "items": [   {
   "duration": "1500",
   "time_restrictions": null,
   "download_allowed": "N",
   "ad_set_id": null,
   "created_at": "2015-09-30T21:12:53Z",
   "hosted_at": "",
   "player_id": "5510596cec91409989dc258390edf182",
   "embed_code": "VpMzr2pwnp9PB_LVFaRUnnofJJAat2Js",
   "preview_image_url": "http://ak.c.ooyala.com/p3amcyOiDTJCL6iVHOgVxISRyU1qoEFy/jq3c6dntusNSL-kX5kdDoxOjBoO6F6AA",
   "publishing_rule_id": "646b4f931194404eb2bbd912ef802111",
   "description": "",
   "asset_type": "video",
   "name": "MyMovie",
   "external_id": null,
   "status": "live",
   "updated_at": "2016-09-19T10:37:55Z",
   "original_file_name": "MyMovie.MOV"
  }  ]
}

Packages

A package lists the features that are available to a provider for distributing and monetizing assets, such as what types of feeds are available and whether closed captions and pay-per-view are supported. The user calling this API must have the reseller permission.

/v2/packages get

get

A package lists the features that are available to a provider for distributing and monetizing assets, such as what types of feeds are available and whether closed-captions and pay-per-view are supported. Each provider is assigned to one package, but a package may be shared among many providers. The reseller assigns a package to a provider.

Make this GET call to view all packages.

You will need to provide your api_key, expires, and signature parameters.

/v2/packages/{package_id} get

get

View information on a package with a given ID. You may obtain the ID by using GET commands to view existing packages, for example [GET] /v2/packages.

You will need to provide your api_key, expires, and signature parameters.

View information on a package with a given ID. You may obtain the ID by using GET commands to view existing packages, for example [GET] /v2/packages.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

package_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


{
  "name": "Package Name",
  "feeds": {
    "three_gp_feeds": false,
    "iphone_abr_feeds": true,
    "ipad_feeds": true,
    "universal_feeds": true,
    "boxee_feeds": true,
    "iphone_feeds": true,
    "itunes_feeds": true,
    "source_feeds": false
  },
  "asset_types": {
    "live_streams": false,
    "youtube": true,
    "remote_assets": true,
    "ad_assets": true,
    "ios_live": true
  },
  "asset_features": {
    "closed_captions": true,
    "metadata": true,
    "movie_ratings": true,
    "pay_per_view": false
  },
  "id": "1d0bbc1f364c47ef8044030c70d3e95f",
  "base_package_id": "a4170df8346c4e1b953041bd8f4328ed",
  "apis": {
    "ingestion_api": true,
    "backlot_api": true,
    "uploader_widget_api": true,
    "epg_api": false
  },
  "reseller_id": "3a2455e44b3d48b38e58797f38acc4d9",
  "analytics": {
    "device_type_analytics": true,
    "tag_analytics": true,
    "geo_analytics": true,
    "domain_analytics": true
  },
  "misc": {
    "push_syndications": false
  }
}

Players

Players define playback options and represent the look and feel of your content. You can create players and assign them to one or more assets in your account.

/v2/players get post

get

View players. With no ID specified, the request is to view all players.

For a given player, the player version will be returned. The player version can be V3 or V4. By default, players are POSTed as V4, but players that had been created before this feature are marked as V3.

If the player version is V4, the release version will also be returned. This can be production or latest. The default is production, but latest is used for testing purposes.

Versions can be set using the Backlot UI.

You will need to provide your api_key, expires, and signature parameters. You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature.

post

Create a player.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players for the URL, and a JSON object representing the player you wish to create into the box below that. Have POST selected, then click Submit. This will generate the POST request, and the posted player will be available in your Backlot account under the Publish tab if the request is successful.

To create your player, name is the only required parameter in the JSON object request.

View players. With no ID specified, the request is to view all players.

If the player version is V4, the release version will also be returned. This can be production or latest. The default is production, but latest is used for testing purposes.

Versions can be set using the Backlot UI.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
include: (string)
An optional query to be included in the GET response. This can be set to
- metadata: See the [GET] /v2/players/{player_id}/metadata description. This will include the metadata hash in the player response for convenience, but will not update when passed through a PATCH request.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/players?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Player resources have the structure of the example below. Here provider_homepage_url is an optional link to your homepage. The ooyala_branding attribute serves to customize the player's user interface.

The related_videos are shown on the end screen. Within that object, source specifies how related videos are selected. This can be either "shared_labels" or "specified_label". The click_behavior attribute designates how related videos are opened. This can be either "same_player", "same_page", or "new_page". When specified_label is selected as the source, the array of labels is specified.

Body

Type: application/json

Example:


{
  "items": [
    {
    "id": "5510596cec91409989dc258390edf182",
    "name": "Default player",
    "is_default": true,
    "provider_homepage_url": null,
    "default_closed_caption_language": "",
    "ooyala_branding": {
        "show_info_screen_homepage_link": true,
        "show_share_button": true,
        "twitter_sharing": false,
        "show_ad_countdown": true,
        "show_info_screen_title": true,
        "show_info_button": true,
        "url_sharing": true,
        "facebook_sharing": false,
        "email_sharing": true,
        "show_info_screen_description": false,
        "show_bitrate_button": false,
        "digg_sharing": false,
        "show_embed_button": true,
        "show_channel_button": true,
        "show_end_screen_replay_button": true,
        "accent_color": "#ffbb00",
        "enable_error_screen": true,
        "show_volume_button": true,
        "chromeless": true
    },
    "related_videos": {
        "source": "shared_labels",
        "click_behavior": "new_page",
        "order": "desc",
        "sort": "upload_time",
        "labels": []
    },
    "player_version": "V4",
    "release_version": "production",
    "scrubber": {
        "always_show": false,
        "image_url": null
    },
    "watermark": {
        "image_url": null,
        "click_url": null,
        "alpha": 1.0,
        "position": "bottom-right"
    },
    "playback": {
        "buffer_on_pause": false
    }
    }
  ]
}

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

{
  "name": "Social Player",
  "ooyala_branding":
  {
    "show_share_button": true,
    "twitter_sharing": true,
    "facebook_sharing": true,
    "digg_sharing": true,
    "url_sharing": true,
    "email_sharing": true
  }
}

HTTP status code 200

The player resource you posted, as exemplified below. Unspecified values will be set to default.

Body

Type: application/json

Example:

{
  "id": "5510596cec91409989dc258390edf182",
   "provider_homepage_url": null,
    "provider_name": null,
    "default_closed_caption_language": "",
    "audio": {"show_download": "true"},
    "is_default": "false",
    "related_videos":
    {
        "labels": [   ],
        "sort": "upload_time",
        "order": "desc",
        "click_behavior": "new_page",
        "source": "shared_labels"
    },
    "watermark":
    {
        "position": "bottom-right",
        "click_url": null,
        "alpha": "1.0",
        "scaling_option": "no_scale",
        "image_url": null,
        "scaling_percentage": null
    },
    "player_version": "V4",
    "release_version": "production",
    "scrubber":
    {
        "always_show": "false",
        "image_url": null
    },
    "name": "Social player",
    "ooyala_branding":
    {
        "show_bitrate_button": "false",
        "show_volume_button": "true",
        "show_end_screen_share_button": "true",
        "show_info_screen_presented_by": "true",
        "show_end_screen_embed_button": "true",
        "chromeless": "false",
        "show_end_screen_info_button": "false",
        "show_start_screen_title": "true",
        "enable_error_screen": "true",
        "facebook_sharing": "true",
        "show_info_button": "true",
        "digg_sharing": "true",
        "twitter_sharing": "true",
        "show_end_screen_more_videos": "true",
        "show_start_screen_description": "true",
        "accent_color": "#ffbb00",
        "stumble_upon_sharing": "false",
        "url_sharing": "true",
        "show_embed_button": "true",
        "show_info_screen_title": "true",
        "show_end_screen_replay_button": "true",
        "show_start_screen_play_button_text": "true",
        "show_fullscreen_button": "true",
        "show_info_screen_description": "false",
        "show_share_button": "true",
        "show_channel_button": "true",
        "show_info_screen_homepage_link": "true",
        "show_ad_countdown": "true"
    },
    "up_next_preview":
    {
       "seconds_before_end": null,
       "timing": "disabled"
    },
    "playback":
    {
        "buffer_on_pause": false
    }
}

/v2/players/{player_id} get patch delete

get

View a player as specified by the player ID.

Besides other parameters, the player version will be returned. The player version can be V3 or V4. By default, players are POSTed as V4, but players that had been created before this feature are marked as V3.

If the player version is V4, the release version will also be returned. This can be production or latest. The default is production, but latest is used for testing purposes.

Versions can be set using the Backlot UI.

patch

Modify a player.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id} for the URL, with your player ID substituted for {player_id}. In the box below, type in a JSON object representing the modifications you wish to make to your player. Have PATCH selected, then click Submit. This will generate the PATCH request, and the modifications will show up in your Backlot account if the request is successful.

Note that you cannot patch your default player to be non-default. Instead, patch another non-default player to be default.

delete

Delete a player.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id} for the URL, with your player ID substituted for {player_id}. Have DELETE selected, then click Submit. If you refresh your Backlot account, the player you deleted will no longer appear, provided the request was successful.

You cannot delete or rename your account's default player.

View a player as specified by the player ID.

If the player version is V4, the release version will also be returned. This can be production or latest. The default is production, but latest is used for testing purposes.

Versions can be set using the Backlot UI.

Request
Response

URI Parameters

player_id: required (string)
The ID of a specific player. To obtain the ID for a given player, log in to Backlot and go to the Manage tab near the top of the screen. Then click on the Embed tab near the bottom of the screen. There is a drop-down menu where you can select your given player by name. Once the player is selected, press the copy button under "Player ID" to copy the player ID to your clipboard.

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
include: (string)
An optional query to be included in the GET response. This can be set to
- metadata: See the [GET] /v2/players/{player_id}/metadata description. This will include the metadata hash in the player response for convenience, but will not update when passed through a PATCH request.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/players/NWI1ZmU4NDNmNmIyODY3ODA0NGNhNDZk?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:

{
  "id": "5510596cec91409989dc258390edf182",
  "name": "Default player",
  "is_default": true,
  "provider_homepage_url": null,
  "default_closed_caption_language": "",
  "ooyala_branding": {
    "show_info_screen_homepage_link": true,
    "show_share_button": true,
    "twitter_sharing": false,
    "show_ad_countdown": true,
    "show_info_screen_title": true,
    "show_info_button": true,
    "url_sharing": true,
    "facebook_sharing": false,
    "email_sharing": true,
    "show_info_screen_description": false,
    "show_bitrate_button": false,
    "digg_sharing": false,
    "show_embed_button": true,
    "show_channel_button": true,
    "show_end_screen_replay_button": true,
    "accent_color": "#ffbb00",
    "enable_error_screen": true,
    "show_volume_button": true,
    "chromeless": true
  },
  "related_videos": {
    "source": "shared_labels",
    "click_behavior": "new_page",
    "order": "desc",
    "sort": "upload_time",
    "labels": []
  },
  "player_version": "V4",
  "release_version": "production",
  "scrubber": {
    "always_show": false,
    "image_url": null
  },
  "watermark": {
    "image_url": null,
    "click_url": null,
    "alpha": 1.0,
    "position": "bottom-right"
  },
  "playback": {
    "buffer_on_pause": false
  }
}

Request
Response

URI Parameters

player_id: required (string)
The ID of a specific player. To obtain the ID for a given player, log in to Backlot and go to the Manage tab near the top of the screen. Then click on the Embed tab near the bottom of the screen. There is a drop-down menu where you can select your given player by name. Once the player is selected, press the copy button under "Player ID" to copy the player ID to your clipboard.

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

{
  "name": "Renamed player"
}

HTTP status code 200

The player resource you modified, as exemplified below.

Body

Type: application/json

Example:

{
  "id": "5510596cec91409989dc258390edf182",
  "name": "Renamed player",
  "is_default": true,
  "provider_homepage_url": null,
  "default_closed_caption_language": "",
  "ooyala_branding": {
    "show_info_screen_homepage_link": true,
    "show_share_button": true,
    "twitter_sharing": false,
    "show_ad_countdown": true,
    "show_info_screen_title": true,
    "show_info_button": true,
    "url_sharing": true,
    "facebook_sharing": false,
    "email_sharing": true,
    "show_info_screen_description": false,
    "show_bitrate_button": false,
    "digg_sharing": false,
    "show_embed_button": true,
    "show_channel_button": true,
    "show_end_screen_replay_button": true,
    "accent_color": "#ffbb00",
    "enable_error_screen": true,
    "show_volume_button": true,
    "chromeless": true
  },
  "related_videos": {
    "source": "shared_labels",
    "click_behavior": "new_page",
    "order": "desc",
    "sort": "upload_time",
    "labels": []
  },
  "scrubber": {
    "always_show": false,
    "image_url": null
  },
  "watermark": {
    "image_url": null,
    "click_url": null,
    "alpha": 1.0,
    "position": "bottom-right"
  },
  "playback": {
    "buffer_on_pause": false
  }
}

/v2/players/{player_id}/metadata get patch put delete

get

Player metadata is a list of name/value string pairs that you can associate with any player.

You will need to provide your api_key, expires, and signature parameters.

To get metadata, make a GET request to the /v2/players/{player_id}/metadata URL.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/metadata for the URL, with your player ID substituted for {player_id}.

patch

Player metadata is a list of name/value string pairs that you can associate with any player.

You will need to provide your api_key, expires, and signature parameters.

To modify metadata, make a PATCH request to the /v2/players/{player_id}/metadata URL with the metadata as the request body. For instance, this might be the skin.

You may delete a metadata attribute by setting it to null.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/metadata for the URL, with your player ID substituted for {player_id}.

put

Player metadata is a list of name/value string pairs that you can associate with any player.

You will need to provide your api_key, expires, and signature parameters.

To replace all metadata, make a PUT request to the /v2/players/{player_id}/metadata URL with the metadata as the request body. For instance, this might be the skin.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/metadata for the URL, with your player ID substituted for {player_id}.

delete

Player metadata is a list of name/value string pairs that you can associate with any player.

You will need to provide your api_key, expires, and signature parameters.

To delete all metadata, make a DELETE request to the /v2/players/{player_id}/metadata URL.

You may delete a single metadata attribute by setting it to null in a PATCH request.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/metadata for the URL, with your player ID substituted for {player_id}.

Player metadata is a list of name/value string pairs that you can associate with any player.

You will need to provide your api_key, expires, and signature parameters.

To modify metadata, make a PATCH request to the /v2/players/{player_id}/metadata URL with the metadata as the request body. For instance, this might be the skin.

You may delete a metadata attribute by setting it to null.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/metadata for the URL, with your player ID substituted for {player_id}.

Request

URI Parameters

player_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

{
  "skin": "chromeless"
}

Player metadata is a list of name/value string pairs that you can associate with any player.

You will need to provide your api_key, expires, and signature parameters.

To replace all metadata, make a PUT request to the /v2/players/{player_id}/metadata URL with the metadata as the request body. For instance, this might be the skin.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/metadata for the URL, with your player ID substituted for {player_id}.

Request

URI Parameters

player_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

{
  "skin": "branded"
}

/v2/players/{player_id}/scrubber_image put

put

The scrubber image is the image that is displayed in the player as you navigate a video using the player scrubber.

The image's aspect ratio should be 4:3 and its dimensions should not exceed 320 x 240 pixels.

To upload a scrubber image, make a PUT request to the /v2/players/{player_id}/scrubber_image URL with the image file as the request body.

You will need to provide your api_key, expires, and signature parameters.

The scrubber image is the image that is displayed in the player as you navigate a video using the player scrubber.

The image's aspect ratio should be 4:3 and its dimensions should not exceed 320 x 240 pixels.

To upload a scrubber image, make a PUT request to the /v2/players/{player_id}/scrubber_image URL with the image file as the request body.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

player_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

{
  "image url": "file:///Users/the_user/Desktop/my_scrubber_image.png"
}

/v2/players/{player_id}/watermark put

put

Watermarks display while your content is being viewed.

Valid file extensions are .png, .jpg, .gif, and .swf.

We recommend using .png files with transparent backgrounds for best results.

You will need to provide your api_key, expires, and signature parameters.

To upload a watermark, make a PUT request to the /v2/players/{player_id}/watermark URL with the watermark file as the request body.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/watermark for the URL, with your player ID substituted for {player_id}.

Request

URI Parameters

player_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

{
  "watermark":
    {
      "image_url": "file:///Users/the_user/Desktop/my_watermark.png",
      "alpha": "0.5",
      "click_url": null,
      "scaling_option": "no_scale",
      "position": "bottom-right",
      "scaling_percentage": null
    } 
}

/v2/players/{player_id}/third_party_modules get

get

View all third-party modules associated with your player.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/third_party_modules for the URL, with your player ID substituted for {player_id}.

Request
Response

URI Parameters

player_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:

{
  "items": [ ]
}

/v2/players/{player_id}/third_party_modules/{module_id} get put patch delete

get

View the third-party modules associated with your player, as specified by the module's ID.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/third_party_modules/{module_id} for the URL, with your player ID substituted for {player_id}, and your module's ID substituted for {module_id}.

put

Add a third-party module to a player, as specified by the module's ID. The module may or may not include parameters.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/third_party_modules/{module_id} for the URL, with your player ID substituted for {player_id}, and your module's ID substituted for {module_id}.

patch

Modify a third-party module associated to a player, as specified by the module's ID.

Key-value pairs in the parameters object will be appended if not already present, or else overwrite existing keys.

Keys that are not present in the object will not be deleted.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/third_party_modules/{module_id} for the URL, with your player ID substituted for {player_id}, and your module's ID substituted for {module_id}.

delete

Remove a third-party module from a player, as specified by the module's ID.

You will need to provide your api_key, expires, and signature parameters.

You can obtain your api_key by logging in to Backlot, navigating to the Account tab, navigating to the Developers tab, and retrieving your API key. You may then use your API Secret key in conjunction with your API key by going to the Scratchpad link, clicking the Your Account button on the upper right, and inputting your API keys. This will generate a URL with expires and signature. Type in /v2/players/{player_id}/third_party_modules/{module_id} for the URL, with your player ID substituted for {player_id}, and your module's ID substituted for {module_id}.

Request
Response

URI Parameters

player_id: required (string)
module_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:

{
  "items": [ ]
}

Request

URI Parameters

player_id: required (string)
module_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
parameters: required (string)
Either null, or else an encapsulation of parameters you wish to toggle for the module.

Body

Type: application/json

Example:

{
    "parameters":
    {
       "menuFontSize": "10",
       "thumbnailsSpacing": "0",
       "thumbnailsSize": "150",
       "activeMenuColor": "#f50505",
       "caption": "",
       "wrapperFontSize": "",
       "podType": "scrolling",
       "tabsFontSize": "",
       "position": "bottom",
       "captionPosition": "inside",
       "theme": "dark"
     }
}

Request

URI Parameters

player_id: required (string)
module_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
parameters: required (string)
An encapsulation of parameters you wish to toggle for the module.

Body

Type: application/json

Example:

{
    "parameters":
    {
       "position": "right",
       "thumbnailsSpacing": "1"
    }
}

Playlists

A playlist consists of a list of movies or labels. Playlists can be used to sequentially play or display their contents. Playlists are generally very lightweight and fast.

/v2/playlists get post

get

View all playlists. Playlist resources have the structure shown in the example response. In particular, the type can be movie, label_and, or label_or. The sort_by criterion can be null, random, date, custom, date_desc, name, or name_desc. The limit is the maximum number of items to show when viewing the playlist. If the type is movie, the items array is a list of embed codes in the playlist. Otherwise, if the type is label_or or label_and, then items is an array of label IDs in the playlist.

You will need to provide your api_key, expires, and signature parameters.

post

Create a playlist. You will need to provide your api_key, expires, and signature parameters.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/playlists?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
  "items": [
    {
        "id": "86e224258a0441fbb19c8af7f8733d0f",
        "name": "an internal name for this playlist",
        "type": "movie",
        "sort_by": null,
        "limit": 10,
        "provider_id": 27645,
        "created_at": "2013-01-25T00:14:40Z",
        "updated_at": "2013-01-25T00:14:40Z",
        "items": [
            "M0YWNmODqougN5VrA1FIk02F3CH7Mq_d",
            "81YWNmODqT-3NfNatUGgJq9_XAR6blq8"
        ]
    }
  ]
}

Create a playlist. You will need to provide your api_key, expires, and signature parameters.

Request

Query Parameters

type: required (string)
Your playlist type. This can be movie, label_and, or label_or.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
name: (string)
Your playlist's name.
sort_by: (string)
A criterion to sort by. This can be null, random, date, custom, date_desc, name, or name_desc.
limit: (integer)
This is the maximum number of items to show when viewing the playlist.
items: (string)
An optional array parameter. If the type is movie, the items array is a list of embed codes in the playlist. Otherwise, if the type is label_or or label_and, then items is an array of label IDs in the playlist.

Body

Type: application/json

Example:


{
  "name": "Test Movie Playlist",
  "type": "movie"
}

/v2/playlists/{playlist_id} get put patch delete

get

View a given playlist specified by its ID. You may obtain the ID by using GET commands to view existing playlists, for example [GET] /v2/playlists.

You will need to provide your api_key, expires, and signature parameters.

put

Replace the playlist specified by a given ID.

You may obtain the ID by using GET commands to view existing playlists, for example [GET] /v2/playlists.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify the playlist specified by a given ID.

You may obtain the ID by using GET commands to view existing playlists, for example [GET] /v2/playlists.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete the playlist specified by a given ID.

You may obtain the ID by using GET commands to view existing playlists, for example [GET] /v2/playlists.

You will need to provide your api_key, expires, and signature parameters.

View a given playlist specified by its ID. You may obtain the ID by using GET commands to view existing playlists, for example [GET] /v2/playlists.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

playlist_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:

{
  "id": "86e224258a0441fbb19c8af7f8733d0f",
  "name": "an internal name for this playlist",
  "type": "movie",
  "sort_by": null,
  "limit": 10,
  "provider_id": 27645,
  "created_at": "2013-01-25T00:14:40Z",
  "updated_at": "2013-01-25T00:14:40Z",
  "items": [
    "M0YWNmODqougN5VrA1FIk02F3CH7Mq_d",
    "81YWNmODqT-3NfNatUGgJq9_XAR6blq8"
  ]
}

Replace the playlist specified by a given ID.

You may obtain the ID by using GET commands to view existing playlists, for example [GET] /v2/playlists.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

playlist_id: required (string)

Query Parameters

type: required (string)
Your playlist type. This can be movie, label_and, or label_or.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
name: (string)
Your playlist's name. Renaming the playlist with an existing playlist name is prohibited.
sort_by: (string)
A criterion to sort by. This can be null, random, date, custom, date_desc, name, or name_desc.
limit: (integer)
This is the maximum number of items to show when viewing the playlist.
items: (string)
An optional array parameter. If the type is movie, the items array is a list of embed codes in the playlist. Otherwise, if the type is label_or or label_and, then items is an array of label IDs in the playlist.

Body

Type: application/json

Example:


{
  "name": "Test Movie Playlist",
  "type": "movie"
}

Modify the playlist specified by a given ID.

You may obtain the ID by using GET commands to view existing playlists, for example [GET] /v2/playlists.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

playlist_id: required (string)

Query Parameters

type: (string)
Your playlist type. This can be movie, label_and, or label_or. Modifying a playlist's type will delete all associated items.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.
name: (string)
Your playlist's name. Renaming the playlist with an existing playlist name is prohibited.
sort_by: (string)
A criterion to sort by. This can be null, random, date, custom, date_desc, name, or name_desc.
limit: (integer)
This is the maximum number of items to show when viewing the playlist.

Body

Type: application/json

Example:


{
  "name": "New Playlist Name"
}

Processing Profiles

A processing profile determines how an asset is encoded and what types of streams are available for viewing the asset. The user calling this API must have the reseller permission.

/v2/processing_profiles get

get

A processing profile determines how an asset is encoded and what types of streams are available for viewing the asset. Each provider is assigned to one processing profile, but a processing profile may be shared among many providers. The reseller assigns a processing profile to a provider.

A processing profile's private parameter is set to false if the profile may be shared with other providers, and to true otherwise. If private is set to true, then changes to this profile will not affect other providers.

Make this API call to view all processing profiles.

You will need to provide your api_key, expires, and signature parameters.

/v2/processing_profiles/{profile_id} get

get

View the processing profile specified by a given profile ID. You may obtain the ID by using GET commands to view existing processing profiles, for example [GET] /v2/processing_profiles.

You will need to provide your api_key, expires, and signature parameters.

View the processing profile specified by a given profile ID. You may obtain the ID by using GET commands to view existing processing profiles, for example [GET] /v2/processing_profiles.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

profile_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

HTTP status code 200

Body

Type: application/json

Example:


{
  "name": "Processing Profile Name",
  "id": "hyNXI6XElT_qcqbePGTcH-V92Yz-",
  "private": false,
  "processing_profile": {
    "target_video_locations": "wd",
    "adobe_http_dynamic_streaming": false,
    "target_image_locations": "wd",
    "custom_image_widths": 96,
    "duplicates_check": false,
    "flv_post_bit_rate_threshold": 2000,
    "h264_post_bit_rate_threshold": 2000
  },
  "streams": [
    {
      "create_ios_stream": false,
      "save_mp4_single_stream_before_segmenting": false,
      "encode_widths": 0,
      "h264_profile": "h264default_pass1",
      "h264_video_bit_rates": 436,
      "h264_encode_pass2": "h264default_pass2",
      "audio_bit_rates": 64,
      "audio_sample_rates": 44100
    }
  ],
  "reseller_id": "3a2455e44b3d48b38e58797f38acc4d9"
}

Provider-Level DRM Policies

A digital-rights management (DRM) policy is a set of configurations for supported DRM technologies. A policy can be set as the default policy applied to all your assets.

/v2/provider_drm_policy get delete

get

Get the default DRM policy, if it exists.

You will need to provide your api_key, expires, and signature parameters.

delete

Remove the policy.

You will need to provide your api_key, expires, and signature parameters.

/v2/provider_drm_policy/{policy_id} put

put

Set a DRM policy as the default for all your assets, as specified by the policy's ID. You may obtain the ID by using GET commands to view existing policies, for example [GET] /v2/drm_policies.

You will need to provide your api_key, expires, and signature parameters.

Providers

This API can be used to get the list of provider accounts managed by a reseller. The user calling this API must have the reseller permission.

/v2/providers get post

get

View all providers. Obtain a paginated list of all the reseller's live providers, ordered from newest to oldest.

Provider resources have the following structure:

name - A name for the provider account.
pcode - The unique identifier of a content provider. You can obtain the pcode for your provider account from your API key. API keys are comprised of two parts, separated by a dot. The first part is your pcode, the second part is a unique identifier for your user account. For example, the pcode for API key yO4ZeBhtS2S3xwnd52zB7fftRkAq.V0Z2M is yO4ZeBhtS2S3xwnd52zB7fftRkAq.
api_v1_secret - A secret key.
admin_user_email - The provider's administrator user email.
address - An object encapsulating the provider's address:
- street - The provider's street address.
- street2 - A continuation of the provider's street address. An apartment or suite number.
- city - The city of the provider's street address.
- state - The state of the provider's street address.
- zip - The ZIP code of the provider's street address.
- country - The country in which the provider's street address is located.
package_id - The provider's package ID.
created_at - Date of creation of the resource.
bucket - The provider bucket, for example http://uploader.ooyala.com.
notes - Notes on this provider.
phone_numbers - An object encapsulating the provider's phone number(s):
- phone - Main phone number.
- phone2 - Secondary phone number.
processing_profile_id - ID for a provider's processing profile.
secret - A secret key.
status - Can be live, disabled, or deleted.

You may also query and filter providers. This works in a similar way to the query API for assets. See the where and users query parameters below for more details.

You will need to provide your api_key, expires, and signature parameters.

post

Create a provider.

You will need to provide your api_key, expires, and signature parameters.

View all providers. Obtain a paginated list of all the reseller's live providers, ordered from newest to oldest.

Provider resources have the following structure:

name - A name for the provider account.
pcode - The unique identifier of a content provider. You can obtain the pcode for your provider account from your API key. API keys are comprised of two parts, separated by a dot. The first part is your pcode, the second part is a unique identifier for your user account. For example, the pcode for API key yO4ZeBhtS2S3xwnd52zB7fftRkAq.V0Z2M is yO4ZeBhtS2S3xwnd52zB7fftRkAq.
api_v1_secret - A secret key.
admin_user_email - The provider's administrator user email.
address - An object encapsulating the provider's address:
- street - The provider's street address.
- street2 - A continuation of the provider's street address. An apartment or suite number.
- city - The city of the provider's street address.
- state - The state of the provider's street address.
- zip - The ZIP code of the provider's street address.
- country - The country in which the provider's street address is located.
package_id - The provider's package ID.
created_at - Date of creation of the resource.
bucket - The provider bucket, for example http://uploader.ooyala.com.
notes - Notes on this provider.
phone_numbers - An object encapsulating the provider's phone number(s):
- phone - Main phone number.
- phone2 - Secondary phone number.
processing_profile_id - ID for a provider's processing profile.
secret - A secret key.
status - Can be live, disabled, or deleted.

You may also query and filter providers. This works in a similar way to the query API for assets. See the where and users query parameters below for more details.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

where: (string)

An optional query parameter.

Supported "where" queries. You can filter based on the notes recorded for that provider, as well as by the provider's status.

Providers which have 'awesome provider' in the notes field:
```
[GET] /v2/providers?where=notes = 'awesome provider'
```
Providers which have a status of either "disabled" or "deleted":
```
[GET] /v2/providers?where=status IN ('disabled', 'deleted')
```
users: (string)

An optional query parameter.

Supported "users" queries. You can also search for a provider based on the email addresses of its users:
```
[GET] /v2/providers?user=someuser@example.com
```
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/providers?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
  "items": [
    {
        "name": "ACME Account",
        "pcode": "xi7a2vGjAJKdwKIB1EjauR8aNF2z",
        "api_v1_secret": "XPadsJkshl_kCasdjK_FD98JGJ-mchdRkLWsaH1",
        "admin_user_email": "admin@acmeaccount.com",
        "address": {
            "street": "123 Main St.",
            "street2": "Apt #2",
            "city": "Santa Clara",
            "state": "CA",
            "zip": "95051",
            "country": "US"
        },
        "package_id": "7370e1f93aa24f5aafafc1abb6418b55",
        "created_at": "2011-05-09T21:21:49+00:00",
        "bucket": "http://uploader.ooyala.com",
        "notes": "Some notes on this provider",
        "phone_numbers": {
            "phone": "408-555-1212",
            "phone2": "650-555-1212"
        },
        "processing_profile_id": "8c672406041449eab5b220144b41eed6",
        "secret": "oTxXpvu7szdjcI8oEfcWRfP8GBEjFD2vTBqWjvUw",
        "status": "live"
    }
  ]
}

Create a provider.

You will need to provide your api_key, expires, and signature parameters.

Request

Query Parameters

email: required (string)
The provider's email.
password: required (string)
The provider password.
name: (string)
The name of the provider.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "Video Productions, Inc.",
  "email": "name@example.com",
  "password": "secret_password"
}

/v2/providers/{pcode} get patch delete

get

View a provider with specified passcode. You may obtain the passcode by using GET commands to view existing providers, for example [GET] /v2/providers.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify a provider specified by a passcode. You may obtain the passcode by using GET commands to view existing providers, for example [GET] /v2/providers.

A timezone can be assigned to a provider and is used to customize the information in analytics reports. This table lists the timezones that may be set for a provider. Set a timezone by indicating its name.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete a specified provider. You may obtain the provider's passcode by using GET commands to view existing providers, for example [GET] /v2/providers.

You will need to provide your api_key, expires, and signature parameters.

View a provider with specified passcode. You may obtain the passcode by using GET commands to view existing providers, for example [GET] /v2/providers.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

pcode: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/providers/xi7a2vGjAJKdwKIB1EjauR8aNF2z?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
  "name": "ACME Account",
  "pcode": "xi7a2vGjAJKdwKIB1EjauR8aNF2z",
  "api_v1_secret": "XPadsJkshl_kCasdjK_FD98JGJ-mchdRkLWsaH1",
  "admin_user_email": "admin@acmeaccount.com",
  "address": {
    "street": "123 Main St.",
    "street2": "Apt #2",
    "city": "Santa Clara",
    "state": "CA",
    "zip": "95051",
    "country": "US"
  },
  "package_id": "7370e1f93aa24f5aafafc1abb6418b55",
  "created_at": "2011-05-09T21:21:49+00:00",
  "bucket": "http://uploader.ooyala.com",
  "notes": "Some notes on this provider.",
  "phone_numbers": {
    "phone": "408-555-1212",
    "phone2": "650-555-1212"
  },
  "processing_profile_id": "8c672406041449eab5b220144b41eed6",
  "secret": "oTxXpvu7szdjcI8oEfcWRfP8GBEjFD2vTBqWjvUw",
  "status": "live"
}

Modify a provider specified by a passcode. You may obtain the passcode by using GET commands to view existing providers, for example [GET] /v2/providers.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

pcode: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "email": "new_email@example.com",
  "timezone": "US/Pacific"
}

/v2/providers/{pcode}/assets get

get

Get a list of assets for a given provider.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/players get

get

Get a list of players for a given provider.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/paywalls get

get

Get a list of paywalls for a given provider.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/ad_sets get

get

Get a list of ad sets for a given provider.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/synd_groups get

get

Get a list of syndication groups for a given provider.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/sub_accounts get

get

View all sub-accounts for a given provider.

Sub-accounts are providers that are subsidiary to the master provider. The master account has access to all the sub-account's videos and analytics. For example, a company could have separate sub-accounts for each division in the company: the sub-accounts would only see analytics for their videos but the company can see analytics across the different divisions.

Please contact your sales team or account manager for details of the sub-accounts feature.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/changes get

get

Get the list of changes to a provider's account. (Whenever a provider's status or package is changed, we record the date of the change as well as the old and new status and the old and new package.)

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/processing_profile get

get

View a given provider's processing profile.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{pcode}/package get

get

View a given provider's package.

You will need to provide your api_key, expires, and signature parameters.

/v2/providers/{master_pcode}/sub_accounts/{sub_account_pcode} put delete

put

Assign a provider as a sub-account of another provider.

Please contact your sales team or account manager for details of the sub-accounts feature.

You will need to provide your api_key, expires, and signature parameters.

delete

Unassign a sub-account from its master account.

Please contact your sales team or account manager for details of the sub-accounts feature.

You may obtain provider passcodes by using GET commands to view existing providers, for example [GET] /v2/providers.

You will need to provide your api_key, expires, and signature parameters.

Publishing Rules

Publishing rules specify when and where your content can be played. With publishing rules, you can restrict your content to specific geographic regions, ensure that it is only embedded on specific domains, and set specific viewing times.

/v2/publishing_rules get post

get

View all publishing rules.

Publishing rules specify when and where your content can be played. With publishing rules, you can restrict your content to specific geographic regions, ensure that it is only embedded on specific domains, and set specific viewing times.

When your asset is loaded, it checks its publishing rule before playing. Each rule that you create can contain any combination of these restrictions and can be assigned to multiple videos or channels.

Within the Backlot UI, publishing rules are called syndication groups.

Publishing rules have the following structure:

id - The ID of the publishing rule.
name - A name for your publishing rule.
geographic_restrictions - An object specifying geographic restrictions:
- type - Can be blacklist or whitelist.
- locations - An array of location codes. See this page for a complete list.
- dmas - An array of designated market area codes. See this page for a complete list.
- ip_addresses - An array of valid IP addresses or IP address ranges (IPv4).
domain_restrictions - An object specifying domain restrictions:
- type - Can be blacklist or whitelist.
- domains - An array containing domain URLs.
proxy_restrictions - An object containing:
- anonymizer_statuses - An array of statuses. Ooyala uses Neustar's IP Intelligence service to identify anonymizing proxies. Neustar assigns the following statuses to IP addresses that have been detected as a proxy:
  - private - IP addresses with this designation allegedly contain anonymous proxies that are not publicly accessible. As such, they cannot be routinely tested with automated tools. These addresses usually belong to commercial ventures that sell anonymity services to the public (Hotspot Shield, CyberGhost, and others). Addresses with this designation are derived from ownership information or obtained from trusted, high-confidence sources.
  - active - The anonymizer tested positive within the last six months.
  - suspect - The anonymizer tested positive within the last two years, but not the last six months.
  - inactive - The anonymizer gave no positive test results within the last two years.
time_restrictions - See the description in the assets article. When using a range time restriction, times represent an absolute UTC time. When using a recurring time restriction, times are based on the viewer's local time.
allowed_devices - An array of devices where playback is allowed. This can contain any among the following supported devices: iphone, ipad, android, and blackberry. Playback will be attempted on all unsupported devices.
secure_playback_token - An object containing information encapsulating a secure playback token. (Secure playback tokens are only enabled for certain packages. Please contact your account manager if you would like to try this feature.) The secure playback token is specified by:
- enabled - A boolean value representing whether the token is enabled. Can be true or false.
- expiration - An integer. The expiration time in seconds.
- require_user_entitlement - A boolean value representing whether user entitlement is required. Can be true or false.

You will need to provide your api_key, expires, and signature parameters.

post

Create a publishing rule.

You will need to provide your api_key, expires, and signature parameters.

A name for your publishing rule is also required.

View all publishing rules.

Within the Backlot UI, publishing rules are called syndication groups.

Publishing rules have the following structure:

id - The ID of the publishing rule.
name - A name for your publishing rule.
geographic_restrictions - An object specifying geographic restrictions:
- type - Can be blacklist or whitelist.
- locations - An array of location codes. See this page for a complete list.
- dmas - An array of designated market area codes. See this page for a complete list.
- ip_addresses - An array of valid IP addresses or IP address ranges (IPv4).
domain_restrictions - An object specifying domain restrictions:
- type - Can be blacklist or whitelist.
- domains - An array containing domain URLs.
proxy_restrictions - An object containing:
- anonymizer_statuses - An array of statuses. Ooyala uses Neustar's IP Intelligence service to identify anonymizing proxies. Neustar assigns the following statuses to IP addresses that have been detected as a proxy:
  - private - IP addresses with this designation allegedly contain anonymous proxies that are not publicly accessible. As such, they cannot be routinely tested with automated tools. These addresses usually belong to commercial ventures that sell anonymity services to the public (Hotspot Shield, CyberGhost, and others). Addresses with this designation are derived from ownership information or obtained from trusted, high-confidence sources.
  - active - The anonymizer tested positive within the last six months.
  - suspect - The anonymizer tested positive within the last two years, but not the last six months.
  - inactive - The anonymizer gave no positive test results within the last two years.
time_restrictions - See the description in the assets article. When using a range time restriction, times represent an absolute UTC time. When using a recurring time restriction, times are based on the viewer's local time.
allowed_devices - An array of devices where playback is allowed. This can contain any among the following supported devices: iphone, ipad, android, and blackberry. Playback will be attempted on all unsupported devices.
secure_playback_token - An object containing information encapsulating a secure playback token. (Secure playback tokens are only enabled for certain packages. Please contact your account manager if you would like to try this feature.) The secure playback token is specified by:
- enabled - A boolean value representing whether the token is enabled. Can be true or false.
- expiration - An integer. The expiration time in seconds.
- require_user_entitlement - A boolean value representing whether user entitlement is required. Can be true or false.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/publishing_rules?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:

{
  "items": [
    {
        "id": "ba4e3c0976a0425385bb26a1776ec6ca",
        "name": "Default",
        "geographic_restrictions":
        {
            "type": "blacklist",
            "locations": ["US"],
            "dmas": ["501"],
            "ip_addresses": ["162.2.2.201", "162.2.2.0-162.2.2.255"]
        },
        "domain_restrictions":
        {
            "type": "whitelist",
            "domains": ["mydomain.com"]
        },
        "proxy_restrictions":
        {
            "anonymizer_statuses": ["private", "active", "suspect", "inactive"]
        },
        "time_restrictions":
        {
            "type": "range",
            "start_date": "2011-05-09T21:21:49-07:00",
            "end_date": null
        },
        "allowed_devices": ["iphone", "ipad", "android", "blackberry"],
        "secure_playback_token":
        {
            "enabled": true,
            "expiration": 600
        }
     }
  ]
}

Create a publishing rule.

You will need to provide your api_key, expires, and signature parameters.

A name for your publishing rule is also required.

Request

Query Parameters

name: required (string)
The name of your publishing rule.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "US Fridays",
  "geographic_restrictions":
  {
    "type": "whitelist",
    "locations": ["US"]
  },
  "time_restrictions": {
    "type": "recurring",
    "recurring_days": ["FRI"],
    "all_day": true
  }
}

/v2/publishing_rules/{rule_id} get patch delete

get

View a publishing rule with specified ID. You may obtain the ID by using GET commands to view existing publishing rules, for example [GET] /v2/publishing_rules.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify a publishing rule specified by an ID.

You may obtain the ID by using GET commands to view existing publishing rules, for example [GET] /v2/publishing_rules.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete a specified publishing rule.

You may obtain the ID by using GET commands to view existing publishing rules, for example [GET] /v2/publishing_rules.

You will need to provide your api_key, expires, and signature parameters.

View a publishing rule with specified ID. You may obtain the ID by using GET commands to view existing publishing rules, for example [GET] /v2/publishing_rules.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

rule_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/publishing_rules/d8f05c27511f4360afa22993bafe6e1a?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
  "name": "My Publishing Rule",
  "geographic_restrictions": {
    "type": "whitelist",
    "locations": ["US", "GB"]
  },
  "domain_restrictions": {
    "type": "whitelist",
    "domains": ["mywebsite.com"]
  },
  "time_restrictions": {
    "type": "recurring",
    "start_date": "2010-01-01",
    "end_date": null,
    "recurring_days": ["MON", "WED"],
    "all_day": false,
    "start_time": "20:00:00",
    "end_time": "23:59:00",
  },
  "allowed_devices": ["ipad"]
}

Modify a publishing rule specified by an ID.

You may obtain the ID by using GET commands to view existing publishing rules, for example [GET] /v2/publishing_rules.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

rule_id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "US Thursdays and Fridays",
  "time_restrictions": {
    "recurring_days": ["THU", "FRI"]
  }
}

Reseller

Use this API to get information about the reseller who is currently logged in. To call this API, one must have the reseller permission.

/v2/reseller get patch

get

Get information about the reseller who is currently logged in.

You will need to provide your api_key, expires, and signature parameters.

patch

Use this API call to modify reseller information. Resellers can change some of their own attributes, such as their name, email_pingback_url, and billing_url.

You will need to provide your api_key, expires, and signature parameters.

Get information about the reseller who is currently logged in.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/reseller?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
  "name": "Ooyala Reseller",
  "billing_url": "http://example.com/hello",
  "email_pingback_url": null,
  "id": "1234567890abcdef1234",
  "max_number_of_providers": null,
  "sub_accounts_enabled": true
}

Use this API call to modify reseller information. Resellers can change some of their own attributes, such as their name, email_pingback_url, and billing_url.

You will need to provide your api_key, expires, and signature parameters.

Request

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "email_pingback_url" : "http://example.com/email_pingback",
  "billing_url" : "http://example.com/billing"
}

Statistics

A reseller can get information such as the number of hours and gigabytes of videos processed. This information is aggregated per month. The user calling this API must have the reseller permission.

/v2/statistics/accounts get

get

Get the number of accounts in each package, grouped by status.

You will need to provide your api_key, expires, and signature parameters.

/v2/statistics/providers get

get

Get the sum of the statistics for all the providers under a reseller for a given date.

You will need to provide your api_key, expires, and signature parameters.

Get the sum of the statistics for all the providers under a reseller for a given date.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

date: required (string)
May be specified as a single day, for example date=2016-12-25, or a single month, for example date=2016-12.
include: required (string)
A comma-separated list of desired statistics to be queried. These can be any of the following:
- gb_processed - The number of gigabytes processed (transcoded).
- hours_ingested - The number of hours of videos managed.
- ingestion_hours - The number of hours of videos managed.
- hours_processed - The number of hours of videos transcoded.
- outbound_transcoded_hours - The number of hours of videos transcoded.
- transcoded_minutes - The number of minutes of videos transcoded (same as hours_processed, but expressed in minutes).
- processed_content - The total amount of storage in gigabytes used for source files plus processed streams.
- delivered_hours - The number of hours watched.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


[GET] /v2/statistics/providers/?date=2016-01-14&include=hours_ingested,hours_processed

HTTP status code 200

Body

Type: application/json

Example:


{
  "gb_processed": 10.0,
  "hours_ingested": 20.0,
  "hours_processed": 30.0
}

/v2/statistics/providers/{pcode} get

get

Get the statistics for a given provider under a reseller for a given date. Here {pcode} is the passcode associated with the given provider.

You will need to provide your api_key, expires, and signature parameters.

Get the statistics for a given provider under a reseller for a given date. Here {pcode} is the passcode associated with the given provider.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

pcode: required (string)

Query Parameters

date: required (string)
May be specified as a single day, for example date=2016-12-25, or a single month, for example date=2016-12.
include: required (string)
A comma-separated list of desired statistics to be queried. These can be any of the following:
- gb_processed - The number of gigabytes processed (transcoded).
- hours_ingested - The number of hours of videos managed.
- ingestion_hours - The number of hours of videos managed.
- hours_processed - The number of hours of videos transcoded.
- outbound_transcoded_hours - The number of hours of videos transcoded.
- transcoded_minutes - The number of minutes of videos transcoded (same as hours_processed, but expressed in minutes).
- processed_content - The total amount of storage in gigabytes used for source files plus processed streams.
- delivered_hours - The number of hours watched.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


[GET] /v2/statistics/providers/{pcode}/?date=2016-01-15&include=hours_ingested,hours_processed

HTTP status code 200

Body

Type: application/json

Example:


{
  "gb_processed": 10.0,
  "hours_ingested": 20.0,
  "hours_processed": 30.0
}

Syndications

A syndication consists of a list of content and a destination to which you want to syndicate the content. The feed's type determines which streams will be used in the syndication (e.g., an mp4 stream or a source file stream) and the output format (e.g., plain MRSS, or sending the files to YouTube). Universal syndication is also available.

/v2/syndications get post

get

View all syndications.

Syndications have the following structure:

id - The ID of the syndication.
name - An internal name for this syndication.
include_all_content - if true, all content is included in this syndication. If false, only content matching the include labels will be included.
include_labels - An array of strings, each of which is a label ID for inclusion.
include_encodings - An optional stream array of valid encoding objects. Use this to filter what assets are included in this syndication. The structure can be either AND:
[{ "device": a valid device value, "container": a valid container value }]
or it can be OR:
[{ "device": a valid device value }, { "container": a valid container value }]
Use AND if you want to filter by an encoding on a specific device. Use OR if you want to filter by an encoding or a specific device. Valid device values are iphone and ipad. Valid container values are mp4, 3gp, ts, ismv, and aac.
asset_types - An array of asset types to include in this syndication. Can be video, ad, remote_asset, or live_stream (deprecated).
type - The type of syndication. See this listing for more details.
These fields are only present for advanced, boxee, iphone, ipad, mp4, roku, and source syndications:

title - The title of the feed. This is included inside the <channel> tag in the feed.
description - A description.
syndication_url - The URL of this syndication's MRSS feed.
destination_url - The URL to be included inside of the <channel> tag in the feed.
require_access_key - If true, the feed's URL must be accessed using an access_key parameter. You may modify (PATCH) an individual syndication to require an access key. If so, the feed's syndication URL will no longer be navigable without including a query string parameter with the access key. See also REST API calls below involving v2/syndications/{syndication_id}/access_keys.

These fields are only present for YouTube syndications:
- username - YouTube login.
- password - YouTube password.
- should_create_youtube_videos - A boolean value.
- should_delete_youtube_videos - A boolean value.
- unrestricted_youtube_account - Set this to true if and only if YouTube lets you upload videos lasting longer than 15 minutes.
These fields are only present for iTunes syndications:
- title - Title of the podcast.
- description - Description of the podcast.
- keywords - A comma-separated list of keywords for iTunes.
- author - Podcast author.
- category - Podcast category.

You will need to provide your api_key, expires, and signature parameters.

post

Create a syndication.

To create an MRSS feed syndication, specify the name and type parameters. The type can be any of the syndication types listed here.

The name and type parameters are always required for a POST request. If the type is YouTube, then the username and password parameters are also required.

We strongly recommend using HTTPS when making API calls with sensitive information like YouTube account credentials.

Handling CAPTCHA Challenges - Youtube may respond with a CAPTCHA challenge if there are repeated attempts to create a YouTube syndication with an incorrect password. In such cases, the API will return an error in the following format:

 {
   "captcha": [ { "captcha_token": "6vKtzYIq85l-t",
   "captcha_url": "http://www.google.com/accounts/Captcha?ctoken=vd-jLZqn55i",
   "message": "Youtube returned a CAPTCHA challenge" } ]
 }

The captcha_url field is a link to the CAPTCHA image. Resend the syndication request with two additional fields:

captcha_token - Specified in the error response.

captcha_response - The word represented by the CAPTCHA image.

You will need to provide your api_key, expires, and signature parameters.

View all syndications.

Syndications have the following structure:

id - The ID of the syndication.
name - An internal name for this syndication.
include_all_content - if true, all content is included in this syndication. If false, only content matching the include labels will be included.
include_labels - An array of strings, each of which is a label ID for inclusion.
include_encodings - An optional stream array of valid encoding objects. Use this to filter what assets are included in this syndication. The structure can be either AND:
[{ "device": a valid device value, "container": a valid container value }]
or it can be OR:
[{ "device": a valid device value }, { "container": a valid container value }]
Use AND if you want to filter by an encoding on a specific device. Use OR if you want to filter by an encoding or a specific device. Valid device values are iphone and ipad. Valid container values are mp4, 3gp, ts, ismv, and aac.
asset_types - An array of asset types to include in this syndication. Can be video, ad, remote_asset, or live_stream (deprecated).
type - The type of syndication. See this listing for more details.
These fields are only present for advanced, boxee, iphone, ipad, mp4, roku, and source syndications:

title - The title of the feed. This is included inside the <channel> tag in the feed.
description - A description.
syndication_url - The URL of this syndication's MRSS feed.
destination_url - The URL to be included inside of the <channel> tag in the feed.
require_access_key - If true, the feed's URL must be accessed using an access_key parameter. You may modify (PATCH) an individual syndication to require an access key. If so, the feed's syndication URL will no longer be navigable without including a query string parameter with the access key. See also REST API calls below involving v2/syndications/{syndication_id}/access_keys.

These fields are only present for YouTube syndications:
- username - YouTube login.
- password - YouTube password.
- should_create_youtube_videos - A boolean value.
- should_delete_youtube_videos - A boolean value.
- unrestricted_youtube_account - Set this to true if and only if YouTube lets you upload videos lasting longer than 15 minutes.
These fields are only present for iTunes syndications:
- title - Title of the podcast.
- description - Description of the podcast.
- keywords - A comma-separated list of keywords for iTunes.
- author - Podcast author.
- category - Podcast category.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

limit: (integer)
The maximum number of results to return in the response array. Can range from 1 to 500.
page_token: (string)
A URL to the next page of results. Note: If the number of results for a given page is divisible by the value of limit, the service returns a 404 response.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/syndications?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:

{
  "items": [
    {
        "id": "1acfea12db3405",
        "name": "an internal name for this syndication",
        "include_all_content": false,
        "include_labels": ["label_id_1"],
        "include_encodings": [
          { "device": "iphone" },
          { "container": "mp4" }
        ],
        "asset_types": ["video"],
        "type": "iphone",
        "title": "Latest racing videos",
        "description": "Amateur Tokyo drift!",
        "syndication_url": "http://api.ooyala.com/v2/syndications/1acfea12db3405/feed?pcode=3k2jkla9",
        "destination_url": "http://mywebsite.com",
        "require_access_key": false,
        "username": "my_youtube_login",
        "password": "my_youtube_password",
        "should_create_youtube_videos": true,
        "should_delete_youtube_videos": true,
        "unrestricted_youtube_account": false,
        "keywords": "racing, car",
        "author": "Rick Astley",
        "category": "Music"
    }
  ]
}

Create a syndication.

To create an MRSS feed syndication, specify the name and type parameters. The type can be any of the syndication types listed here.

The name and type parameters are always required for a POST request. If the type is YouTube, then the username and password parameters are also required.

We strongly recommend using HTTPS when making API calls with sensitive information like YouTube account credentials.

 {
   "captcha": [ { "captcha_token": "6vKtzYIq85l-t",
   "captcha_url": "http://www.google.com/accounts/Captcha?ctoken=vd-jLZqn55i",
   "message": "Youtube returned a CAPTCHA challenge" } ]
 }

The captcha_url field is a link to the CAPTCHA image. Resend the syndication request with two additional fields:

captcha_token - Specified in the error response.

captcha_response - The word represented by the CAPTCHA image.

You will need to provide your api_key, expires, and signature parameters.

Request

Query Parameters

name: required (string)
The name of the syndication.
type: required (string)
For an MRSS feed syndication, the type can be any of the syndication types listed here.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "My iPhone MRSS Feed",
  "type": "iphone"
}

/v2/syndications/{id} get patch delete

get

View a syndication with specified ID. You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

Also, see the optional query parameters feed, updated_after, and redirect_content below.

You will need to provide your api_key, expires, and signature parameters.

patch

Modify a syndication specified by an ID.

You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

You will need to provide your api_key, expires, and signature parameters.

delete

Delete a specified syndication.

You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

You will need to provide your api_key, expires, and signature parameters.

View a syndication with specified ID. You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

Also, see the optional query parameters feed, updated_after, and redirect_content below.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

id: required (string)

Query Parameters

feed: (string)
After you've created a syndication, the URL of the feed is included in the response body (the syndication_url field). Include this parameter to get the feed associated with your syndication.
updated_after: (string)
A date parameter. If you are including the feed parameter, this will limit the feed to assets updated after the given date. The date should be in standard form (2011-01-01T00:00:00Z).
redirect_content: (string)
By default, links to assets within your syndication (such as the syndication feed URL) contain redirects. To prevent this behavior, add the query string parameter redirect_content=false to the feed request.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/syndications/d8f05c27511f4360afa22993bafe6e1a?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:

{
  "id": "1acfea12db3405",
  "name": "an internal name for this syndication",
  "include_all_content": false,
  "include_labels": ["label_id_1"],
  "include_encodings": [
    { "device": "iphone" },
    { "container": "mp4" }
  ],
  "asset_types": ["video"],
  "type": "iphone",
  "title": "Latest racing videos",
  "description": "Amateur Tokyo drift!",
  "syndication_url": "http://api.ooyala.com/v2/syndications/1acfea12db3405/feed?pcode=3k2jkla9",
  "destination_url": "http://mywebsite.com",
  "require_access_key": false,
  "username": "my_youtube_login",
  "password": "my_youtube_password",
  "should_create_youtube_videos": true,
  "should_delete_youtube_videos": true,
  "unrestricted_youtube_account": false,
  "keywords": "racing, car",
  "author": "Rick Astley",
  "category": "Music"
}

Modify a syndication specified by an ID.

You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

You will need to provide your api_key, expires, and signature parameters.

Request

URI Parameters

id: required (string)

Query Parameters

require_access_key: (boolean)
Access keys can be used to create private URLs for a syndication's MRSS feed. With this you can give out unique feed URLs to third parties, and, if needed, revoke their access to your MRSS feed without having to delete the feed. If this is set to true, then navigation to the feed's syndication_url will no longer work. In that case, the access_key query string parameter must be added to the syndication URL, e.g. http://api.ooyala.com/v2/syndications/syndication_id/feed?pcode=yourPcode&access_key=yourAccessKey.
api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "new name",
  "require_access_key": true
}

/v2/syndications/{id}/album_art put

put

This PUT request is only applicable to syndications of type itunes.

Apple advises that the image file have 300 x 300 pixels.

To upload album art, make a PUT request to the /v2/syndications/{id}/album_art URL with the image file as the request body.

You will need to provide your api_key, expires, and signature parameters.

/v2/syndications/{id}/template put

put

To upload a USTL template to an advanced syndication, you include the template in the body of the PUT request.

You will need to provide your api_key, expires, and signature parameters.

/v2/syndications/{id}/access_keys get post

get

Access keys can be used to create private URLs for a syndication's MRSS feed. With this you can give out unique feed URLs to third parties, and if needed, revoke their access to your MRSS feed without having to delete the feed.

View the access keys associated with a syndication with specified ID.

You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

You will need to provide your api_key, expires, and signature parameters.

post

Create an access key for a syndication specified by an ID. Create the key with a plaintext name. A response with the private key will be generated.

You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

You will need to provide your api_key, expires, and signature parameters.

Create an access key for a syndication specified by an ID. Create the key with a plaintext name. A response with the private key will be generated.

You may obtain the ID by using GET commands to view existing syndications, for example [GET] /v2/syndications.

You will need to provide your api_key, expires, and signature parameters.

Request
Response

URI Parameters

id: required (string)

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:


{
  "name": "MetaCafe access key"
}

HTTP status code 200

Body

Type: application/json

Example:


{
  "name": "MetaCafe access key",
  "access_key": "66eb2e2f-c444-432c-b226-eb473f76"
}

/v2/syndications/{id}/access_keys/{key_id} delete

delete

Delete an access key with ID {key_id} from a syndication with ID {id}.

You may obtain the IDs in question, for example, by using GET commands to view existing syndications, and the access keys of those syndications.

You will need to provide your api_key, expires, and signature parameters.

Third-Party Modules

Third-party modules are added to the player to enhance the base feature set. For instance, adding the Playlists module to the player will allow your player to display playlist-pods. See here for more information on how to modify a player's third-party module.

/v2/third_party_modules get

get

View all available third party modules. You will need to provide your api_key, expires, and signature parameters.

Request
Response

Query Parameters

api_key: required (string)
A user-specific key found in the Developers tab of Backlot.
expires: required (integer)
A UNIX timestamp (seconds since January 1st, 1970) indicating the time until which your request should be valid.
signature: required (string)
A computed digest of all of your request's parameters, to ensure your request URLs can't be tampered with after they've been signed.

Body

Type: application/json

Example:

curl -X GET 'https://api.ooyala.com/v2/third_party_modules?api_key=ZnMmM6AO3C-iBubra3R2Xd6pXHgK.28riq&expires=1930294539&signature=p3RfmwGk%2FjwIup%2BUtyTtXjU%2FPpDx2DwHNGyfko07%2B28'

HTTP status code 200

Body

Type: application/json

Example:


{
 "items": [   {
   "type": "v3-playlists",
   "description": "Playlists",
   "id": "e59z4c2d4f95057c88db1b52cb7a7u10",
   "is_flash": "false",
   "is_v3": "true"
  }  ]
}

Users

This API keeps track of users for providers owned by resellers. To call this API, one must have the reseller permission.

/v2/users get

get

View all users.

You will need to provide your api_key, expires, and signature parameters.

/v2/users/{user_api_key} get

get

Get information about a user as specified by the user's API key.

You will also need to provide your api_key, expires, and signature parameters.

Backlot API Reference

version 2.0

Ad Sets

get /v2/ad_sets

Query Parameters

Body

HTTP status code 200

Body

post /v2/ad_sets

Query Parameters

Body

get /v2/ad_sets/{set_id}

URI Parameters

Query Parameters

HTTP status code 200

Body

patch /v2/ad_sets/{set_id}

URI Parameters

Query Parameters

Body

delete /v2/ad_sets/{set_id}

URI Parameters

Query Parameters

post /v2/ad_sets/{set_id}/ads

URI Parameters

Query Parameters

Body

delete /v2/ad_sets/{set_id}/ads/{ad_id}

URI Parameters

Query Parameters

Assets

get /v2/assets

Query Parameters

Body

HTTP status code 200

Body

post /v2/assets

Query Parameters

Body

get /v2/assets/{asset_id}

URI Parameters

Query Parameters

Body

HTTP status code 200

Body

post /v2/assets/{asset_id}

URI Parameters

Query Parameters

patch /v2/assets/{asset_id}

URI Parameters

Query Parameters

Body

delete /v2/assets/{asset_id}

URI Parameters

Query Parameters

get /v2/assets/{asset_id}/ad_set

URI Parameters

Query Parameters

get /v2/assets/{asset_id}/closed_captions

URI Parameters

Query Parameters

put /v2/assets/{asset_id}/closed_captions

URI Parameters

Query Parameters

delete /v2/assets/{asset_id}/closed_captions

URI Parameters

Query Parameters

get /v2/assets/{asset_id}/drm_attributes/{drm_type}

URI Parameters

Query Parameters

patch /v2/assets/{asset_id}/drm_attributes/{drm_type}

URI Parameters

Query Parameters

Body

get /v2/assets/{asset_id}/generated_preview_images

URI Parameters

Query Parameters

HTTP status code 200

Body

get /v2/assets/{asset_id}/labels