Loading Search...
Content API Developers Reference

  Audience and Overview

This documentation is intended for programmers who are writing client or server applications that interact with the data contained within a Limelight Orchestrate Video account. It provides explanation and examples of basic Application Programming Interface (API) operations using REST, XML, JSON, PHP, Ruby, and Flash.

This documentation assumes that you understand the general principles behind the aforementioned programming languages and concepts. Code examples and links to sample code are provided.

  Table of Contents


  1.0 Content API Overview

The Limelight Orchestrate Video Content API gives developers programmatic access to the media and supporting metadata within an account, allowing for the creation of fully integrated applications or sites. Developers can enable applications to perform actions that are normally performed within a Limelight Orchestrate Video account by searching, updating, and creating video content programmatically. The Content API enables the ability to create any customized experience, such as a web application that allows a user to submit and rate video, a video thumbnail gallery on a website, or a workflow integration with an existing Content Management System (CMS).

Specifically, the Content API permits the following:
  • Query - Request information about your media, channel and channel group metadata
  • Upload - Submit new media and create new channels and channel groups
  • Update - Change or update existing metadata for media, channels and channel groups
  • Delete - Remove existing media, channels or channel groups
  • Extend - Augment the Limelight Orchestrate Video schema with your own custom metadata fields
Resources and methods pertaining to the above bullet points are described in detail in sections 2.0 and 3.0 below.

1.1 REST

All API requests in the Content API are REST based and are available through the following base end-point:

http://api.video.limelight.com/rest/
NOTE: You can optionally choose to access API requests via HTTPS.

1.2 Pagination

For performance reasons, a query response will be paginated. The default and maximum page size for a response is 500. A value of 'true' for 'has_next' indicates that more results are available with subsequent page calls. The following optional parameters can be used to control the page of results:

Paging Parameter Description
page_id The zero-based identifier of the page to return
Example: page_id=3
page_size The number of results to return per page. The default and maximum page size is 500.
Example: page_size=100
sort_by The field by which the results should be sorted. Results can be sorted by any of the following: publish_date, create_date, update_date
Example: sort_by=publish_date
sort_order The order in which the results should display. Specify 'asc' for ascending or 'desc' for descending. Results will display in ascending order by default.
Example: sort_order=desc

1.3 Authentication

In order to ensure the security of your information we require some requests to be signed. Those methods indicated below as requiring authentication must have a signature. See section 8.0 below for how to sign requests.

1.4 Errors

Standard errors are returned with 4xx codes and a descriptive message. Internal server errors are returned with a status code of 500.

1.5 Deprecation Policy

Technology moves fast and we want to keep our developer API at the innovative forefront of new technologies and techniques. As such, Limelight from time to time will deprecate certain API calls. Limelight will announce if it intends to discontinue or make backwards incompatible changes to the API. Following a deprecation notice, we will use commercially reasonable efforts to continue to operate the deprecated API for a period of one year after the announcement.

All deprecated API announcements and dates are documented here: Product Updates and Releases

1.6 Server-side Caching

In order to ensure a fast, reliable, and responsive site, we recommend that all interaction with the Content API be done on the server. For example, don't try to call the API on every page load of your hugely popular website. Instead, call the API only to periodically update a local cache and save the response, displaying your cached version on your site. Caching is essential to ensuring the reliability of your web application, ensuring robustness and preventing overall network load. For information on a suggested technique to implement caching, see Appendix D below.


  2.0 Resources - Data Organization

The data in your Limelight Orchestrate Video account is organized into four resources: organization, channel groups, channels and media. Your account is represented by a single organization, denoted by an organization ID. You can obtain your organization ID by logging into your account and navigating to the 'Developer Tools' tab under 'Settings'. A channel is a nested resource of an organization (organizations are composed of channels). A channel may contain zero or more media but cannot contain more than 7000. Channel groups can be used to further organize channels into logical groupings. However, channel groups are not required, they are simply an extra level of organization that is at your convenience. The following diagram outlines these resource relationships:

2.1 Channel Group Resource

The channel group resource is an aggregation of metadata associated with a channel group. Channel groups can be used to organize channels into logical groupings. The following metadata properties are assoicated with a channel group; these properties will be returned in the response to an API query request:

Property Name Required on Create Updatable Description Limited to Values
id Automatically Set NO A unique identifier for a channel group. Limelight automatically assigns an ID upon creation n/a
title YES YES The name of the channel group n/a
update_date Automatically Set NO The date the channel group was last updated (this includes the last time a channel was added/removed from the channel group), represented as the number of seconds since the Unix epoch n/a
create_date Automatically Set NO The date the channel group was created, represented as the number of seconds since the Unix epoch n/a

2.2 Channel Resource

The channel resource is an aggregation of metadata associated with a channel. Channels can be used to organize media into logical groupings or playlists. The following metadata properties are assoicated with a channel; these properties will be returned in the response to an API query request:

Property Name Required on Create Updatable Description Limited to Values
id Automatically Set NO A unique identifier for a channel. Limelight automatically assigns an ID upon creation n/a
title YES YES The name of the channel n/a
description NO YES A description of the channel n/a
thumbnail_url NO NO The URL of the thumbnail image associated with the channel n/a
state Automatically Set YES Current state of the channel. Limelight automatically sets this to 'NotPublished' upon create. To publish a channel, first create it and then perform an update to set the state to 'Published.' Published, NotPublished
email_enabled NO YES An indicator that enables share with a friend functionality true, false
embed_enabled NO YES An indicator that enables get embed code functionality true, false
search_inside_enabled NO YES An indicator that enables search inside functionality true, false
autoplay_enabled NO YES An indicator that enables autoplay functionality true, false
rss_enabled NO YES An indicator that enables RSS functionality true, false
itunes_rss_enabled NO YES An indicator that enables iTunes functionality true, false
publish_date NO NO The date the channel was last set to 'Published', represented as the number of seconds since the Unix epoch. Value will be blank if channel is not published. n/a
update_date Automatically Set NO The date the channel was last updated (this includes the last time a media was added/removed from the channel), represented as the number of seconds since the Unix epoch n/a
create_date Automatically Set NO The date the channel was created, represented as the number of seconds since the Unix epoch n/a

2.3 Media Resource

The media resource is an aggregation of metadata associated with a media. A media has the following standard metadata properties; these properties will be returned in the response to an API query request:

Property Name Required on Create Updatable Description Limited to Values
id Automatically Set NO A unique identifier for a media. Limelight automatically assigns an ID upon creation n/a
title YES YES The name of the media n/a
description NO YES A description of the media n/a
media_type Automatically Set NO The type of media. Limelight automatically sets this value Video, Audio, LiveStream
original_filename Automatically Set NO The original name of the file that was uploaded n/a
state Automatically Set NO Current state of the video. Limelight automatically sets this value New, Uploading, Processing, Publishable, Published, Error
duration_in_milliseconds Automatically Set NO The length of the video in milliseconds. Limelight automatically sets this value n/a
total_storage_in_bytes Automatically Set NO The total number of bytes used to store the video. This value reflects the storage of the originally uploaded source plus all transcoded files n/a
category NO YES The genre associated with the media Politics, Entertainment, Travel, Sports, Technology, Gaming, Business
ref_id NO YES A free-form field that can house an internally used media reference ID, possibly from an existing CMS n/a
restrictionrule_id NO YES The unique ID of the viewing restriction rule that is assigned to the media. A restriction rule represents the listing of approved domains and/or geographic locations where a media can be played. A restriction rule can be setup under 'Settings -> Content Restrictions' in your account. n/a
closed_captions_url NO YES The URL to the caption file that is associated with the media. n/a
allow_ads NO YES A true/false field that indicates if ads can play for a media. A value of 'false' will prevent any ads from playing for the media. true, false
thumbnails Automatically Set NO A list of URLs associated with the different thumbnail image sizes for the video. A video will have two thumbnail sizes, a small (width of 120) and a large (width of 540). The width of the large size can be customized by uploading your own image in the Limelight Orchestrate Video console n/a
tags NO YES A list of strings representing the tags of the video n/a
sched_start_date NO YES The date the video is scheduled to be available for viewing, represented as the number of seconds since the Unix epoch n/a
sched_end_date NO YES The date the video is scheduled to become unavailable for viewing, represented as the number of seconds since the Unix epoch n/a
publish_date NO NO The date the video was 'Published', represented as the number of seconds since the Unix epoch. A media is set to 'Published' when it first exists in a 'Published' channel. Value will be blank if the video is not published. n/a
update_date Automatically Set NO The date the media was last updated, represented as the number of seconds since the Unix epoch n/a
create_date Automatically Set NO The date the media was created in the account, represented as the number of seconds since the Unix epoch n/a

  3.0 API Requests - Query

Requests for information about the media, channel and channel group content in your account can be accomplished using our suite of GET requests. All results are returned in JSON format by default. You can specify an alternative response format (such as XML) by applying a 'dot-extension' on the end of the resource path.

See Appendix B for an example of a query request result.

NOTE: In order to ensure a fast, reliable, and responsive site, we recommend that you execute Query API requests on the server and cache responses. For example, don't try to call a Query API on every page load of your hugely popular website. Instead, call the API only to update the cache and save the response, displaying your cached version on your site. For information on a technique to implement caching, see Appendix D below.

3.1 Media Methods

The following methods are available for requesting content information for media:

Methods

Search for media

Find and list media that meet specified search criteria
NOTE: See Appendix A for specific examples that illustrate the use of search

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/search.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Parameters

NOTE: All parameters are optional. If no parameters are specified then the search will simply return all media.

and = <search criteria represented as <key>:<value> pairs, separated by semi-colons. All criteria must be true for a video to be returned>
Example - find all published media with a tag of football: 'and = tag:football;state:published'

or = <search criteria represented as <key>:<value> pairs, separated by semi-colons. At least one of the criteria must be true for a video to be returned>
Example - find all media with a tag of football or a tag of hockey: 'or = tag:football;tag:hockey'

Search criteria for the above parameters can be built using any of the following media properties. All criteria is case insensitive.
Key Value
title Any word or phrase in the title.
description Any word or phrase in the description.
original_filename Any word or phrase in the original filename.
tag Any word or phrase in the tag.
state Exact match of one of the following: new, uploading, processing, publishable, published, error
media_type Exact match of one of the following: video, audio, livestream
channel_id Id of a channel where the search should be limited.
created_after Date, represented in Unix Time. Limits search to media created after a particular date.
updated_after Date, represented in Unix Time. Limits search to media updated after a particular date.
published_after Date, represented in Unix Time. Limits search to media published after a particular date.
custom_property[<custom_property_id>]

The ID of a custom property can be found by accessing 'Settings' then 'Custom Properties' in the Orchestrate Video console. Right-click on the property name to reveal. Click to copy.
Any word or phrase in the value of the custom property

Paging Parameters

page_id = <The zero-based identifier of the page to return> (default: 0)
page_size = <The number of results to return per page> (default/max: 500)
sort_by = <The field by which the results should be sorted> {create_date, update_date} (default: update_date)
sort_order = <The order in which the results should display> {asc, desc} (default: asc)

Response

List of media and associated properties that meet the specified search criteria

Errors

Invalid value

Example Usage

See Appendix A below

List all properties for a specific media

Find and list all properties for a specific media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pairs for all properties, including existing custom properties

Errors

Media does not exist

Example Usage

(click link to execute)

Get the value of a particular media property

Find and get the value of a media property

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/<property name>.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pair of requested property

Errors

Media does not exist

Example Usage

(click link to execute)

List all channels that contain a specific media

Find and get a list of all the channels that contain a specific media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/channels.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Optional Parameters

page_id = <The zero-based identifier of the page to return>
page_size = <The number of results to return per page> (default/max: 500)
sort_by = <The field by which the results should be sorted> {publish_date, create_date, update_date} (default: update_date)
sort_order = <The order in which the results should display> {asc, desc} (default: asc)

Response

A list of channels and associated properties that contain the specific media

Errors

Media either does not exist or you do not have access to it

List the cue points for a specific media

Find and get the details for all cue points on a media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/cuepoints.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Required Parameters

None

Optional Parameters

type=<the type of cuepoint to return> {valid values are: 'all', 'ad', 'contentOverlay', 'customEvent'} (case insensitive)

Response

A complete list of all the cue points for the media and the corresponding details.

Errors

User does not exist or you do not have access to it
Media either does not exist or you do not have access to it
You supplied an invalid value: type must be one of the following ['all', 'ad', 'contentoverlay', 'customevent']

List the encodings for a specific media

Find and get the details, including playback URLs, for all the transcoded files that have been produced for a media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/encodings.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Required Parameters

primary_use = <identifies the encodings to return> {valid values are: 'all', 'flash', 'mobileh264', 'mobile3gp', 'httplivestreaming', 'widevine', 'smoothstreaming', 'httpdynamicstreaming'} (case insensitive)

See the Encoding Guide for a description of each 'primary_use'.

Optional Parameters

group = <The encoding group identifier - this parameter pertains to Widevine only> {valid values: 'HD', 'SD'}

Response

A complete list of all the encodings for the media and the corresponding details, including resolution, codec, bit rate, and playback URL.

Playback URL Types
url The streaming URL for the content (i.e. RTMP for Flash; RTSP for Mobile3GP). Also used for the HTTP playback URL for both MobileH264 and Widevine content.
master_playback_url The master manifest URL for segmented content (i.e. M3U8 for Apple HLS; ISM for Microsoft Smooth Streaming; F4M for Adobe HDS)
file_url The HTTP progressive URL for 'Flash' content (MP4 files)

Errors

User does not exist or you do not have access to it
Media either does not exist or you do not have access to it
You supplied an invalid value: primary_use must be one of the following ['all', 'flash', 'httplivestreaming', 'httpdynamicstreaming', 'mobileh264', 'mobile3gp', 'smoothstreaming', 'widevine']

List the encodings for all media

Find and get the details, including playback URLs, for all the transcoded files for all media in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/encodings.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Required Parameters

primary_use = <identifies the encodings to return> {valid values are: 'all', 'flash', 'mobileh264', 'mobile3gp', 'httplivestreaming', 'widevine', 'smoothstreaming', 'httpdynamicstreaming'} (case insensitive)

See the Encoding Guide for a description of each 'primary_use'.

Optional Parameters

group = <The encoding group identifier - this parameter pertains to Widevine only> {valid values: 'HD', 'SD'}

page_id = <The zero-based identifier of the page to return> (default: 0)
page_size = <The number of results to return per page> (default/max: 200)

Response

A complete list of all the encodings and the corresponding details, including resolution, codec, bit rate, and playback URL.

Playback URL Types
url The streaming URL for the content (i.e. RTMP for Flash; RTSP for Mobile3GP). Also used for the HTTP playback URL for both MobileH264 and Widevine content.
master_playback_url The master manifest URL for segmented content (i.e. M3U8 for Apple HLS; ISM for Microsoft Smooth Streaming; F4M for Adobe HDS)
file_url The HTTP progressive URL for 'Flash' content (MP4 files)

Errors

User does not exist or you do not have access to it
You supplied an invalid value: primary_use must be one of the following ['all', 'flash', 'httplivestreaming', 'httpdynamicstreaming', 'mobileh264', 'mobile3gp', 'smoothstreaming', 'widevine']

List the thumbnails for a specific media

Find and get the details for all skimming thumbnails that have been produced for a media. These are the images that are automatically produced when a media is uploaded - one image for each ten seconds of content.

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/skimming_thumbnails.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Paging Parameters

page_id = <The zero-based identifier of the page to return> (default: 0)
page_size = <The number of results to return per page> (default/max: 100)

Response

A complete list of all the skimming thumbnails for the media and the corresponding details.

Errors

Media either does not exist or you do not have access to it
Skimming thumbnails are only available for media of type 'Video'.

3.2 Channel Methods

The following methods are available for requesting content information for channels:

Methods

List published channels

Find and list all 'published' channels in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Optional Parameters

page_id = <The zero-based identifier of the page to return>
page_size = <The number of results to return per page> (default/max: 500)
sort_by = <The field by which the results should be sorted> {publish_date, create_date, update_date} (default: update_date)
sort_order = <The order in which the results should display> {asc, desc} (default: asc)

Response

List of channels and associated properties, including existing custom properties

Errors

Invalid value

Example Usage

(click link to execute)

List all channels

Find and list all channels, including 'unpublished' channels

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/all.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Parameters

None

Optional Parameters

page_id = <The zero-based identifier of the page to return>
page_size = <The number of results to return per page> (default/max: 500)
sort_by = <The field by which the results should be sorted> {publish_date, create_date, update_date} (default: update_date)
sort_order = <The order in which the results should display> {asc, desc} (default: asc)

Response

List of channels and associated properties, including existing custom properties

Errors

Invalid value

Example Usage

Example code for this method can be found in section 9.2.1

List all properties for a channel

Find and list all properties for a specific channel

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/properties.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pairs for all properties, including existing custom properties

Errors

Channel does not exist

Example Usage

(click link to execute)

Get the value of a particular channel property

Find and get the value of a channel property

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/properties/<property name>.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pair of requested property

Errors

Channel does not exist

Example Usage

(click link to execute)

List all media associated with a channel

Find and get all media in a particular channel

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/media.{XML,JSON}

Formats

Note: The above method can also be used to retrieve the RSS or iTunes feeds for a channel
XML, JSON, RSS, ITUNESRSS

HTTP Method

GET

Requires Authentication

NO

Optional Parameters

page_id = <The zero-based identifier of the page to return>
page_size = <The number of results to return per page> (default/max: 500)

Response

List of all media in a channel

Errors

Channel does not exist

Example Usage

(click link to execute)

List the encodings for a specific channel

Find and get the details, including playback URLs, for all the transcoded files for all media in a particular channel

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/encodings.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Required Parameters

primary_use = <identifies the encodings to return> {valid values are: 'all', 'flash', 'mobileh264', 'mobile3gp', 'httplivestreaming', 'widevine', 'smoothstreaming', 'httpdynamicstreaming'} (case insensitive)

See the Encoding Guide for a description of each 'primary_use'.

Optional Parameters

group = <The encoding group identifier - this parameter pertains to Widevine only> {valid values: 'HD', 'SD'}

page_id = <The zero-based identifier of the page to return> (default: 0)
page_size = <The number of results to return per page> (default/max: 200)

Response

A complete list of all the encodings and the corresponding details, including resolution, codec, bit rate, and playback URL.

Playback URL Types
url The streaming URL for the content (i.e. RTMP for Flash; RTSP for Mobile3GP). Also used for the HTTP playback URL for both MobileH264 and Widevine content.
master_playback_url The master manifest URL for segmented content (i.e. M3U8 for Apple HLS; ISM for Microsoft Smooth Streaming; F4M for Adobe HDS)
file_url The HTTP progressive URL for 'Flash' content (MP4 files)

Errors

User does not exist or you do not have access to it
You supplied an invalid value: primary_use must be one of the following ['all', 'flash', 'httplivestreaming', 'httpdynamicstreaming', 'mobileh264', 'mobile3gp', 'smoothstreaming', 'widevine']

3.3 Channel Group Methods

The following methods are available for requesting content information for channel groups:

Methods

List all channel groups

Find and list all channel groups in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/all.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Optional Parameters

page_id = <The zero-based identifier of the page to return>
page_size = <The number of results to return per page> (default/max: 500)
sort_by = <The field by which the results should be sorted> {create_date, update_date} (default: update_date)
sort_order = <The order in which the results should display> {asc, desc} (default: asc)

Response

List of channel groups and associated properties, including custom properties

List all properties of a channel group

Find and list all properties for a specific channel group

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>/properties.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pairs for all properties

Errors

Channel group does not exist

Example Usage

(click link to execute)

List all channels in a channel group

Find and get all published channels in a particular channel group

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>/channels.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Optional Parameters

page_id = <The zero-based identifier of the page to return>
page_size = <The number of results to return per page> (default/max: 500)

Response

List of all published channels in a channel group

Errors

Channel group does not exist

Example Usage

(click link to execute)

3.4 Miscellaneous Methods

The following miscellaneous methods are available:

Methods

List all restriction rules

Find and list all the viewing restriction rules for an account.

URL

http://api.video.limelight.com/rest/organizations/<org id>/restrictionrules/all.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

List of all restriction rules and associated properties.

Errors

User does not exist or you do not have access to it (thrown when an incorrect org ID is specified)

Example Usage

List all players

Find and list all the players for an account.

URL

http://api.video.limelight.com/rest/organizations/<org id>/players/all.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

Parameters

None

Response

List of all players and associated properties.

Errors

User does not exist or you do not have access to it (thrown when an incorrect org ID is specified)

  4.0 API Requests - Upload

New content can be created or uploaded to your account using our suite of POST requests. All results are returned in JSON format by default. You can specify an alternative response format (such as XML) by applying a 'dot-extension' on the end of the resource path.

4.1 Media Methods

The following method is available for uploading new media:

Methods

Upload media

Upload a media to an account by either pushing the binary of the file or by specifying a public URL to the file. If a URL is specified the system will automatically retrieve the file.
Note: The max file size permitted via API is 4 GB. Alternative upload methods, specifically FTP or Aspera, are recommended for larger files.

URL

http://api.video.limelight.com/rest/organizations/<org id>/media.{XML,JSON}

Formats

XML, JSON

HTTP Method

POST

Requires Authentication

Required Parameters

  • title = <the title of the media>

  • One of the following (if both are provided then the value of 'media_file' shall take precedence):
    media_file=<binary data for file> (This takes the form of a file part, in a multipart/form-data HTTP request)
    or
    media_file_url=<the public URL to the media file; example: 'http://example.com/media/my_file.mp4'>

Optional Parameters

  • encoding_profile_id = <the ID of the desired encoding profile; if no value is specified then the profile that is 'Active' on your account shall be used>
    NOTE: When specifying this parameter, make sure it appears before the 'media_file' or 'media_file_url' in your request. Otherwise the value will be ignored and the system will fallback to using the 'Active' profile.
    NOTE: The ID of an encoding profile can be found by accessing 'Settings' then 'Encoding' in the Orchestrate Video console. Right-click on the profile name to reveal. Click to copy.

  • add_to_channel = <the ID of a channel to which the newly uploaded media should be added>

  • See section 2.3 above for additional media properties that can be set during upload. (properties that can be set are those that are labled as 'Updatable'). NOTE: the 'allow_ads' property cannot be set during upload. To set this property, you must first upload the media then update the existing metadata.

  • Values for existing custom metadata properties can also be set during upload. For each custom property you wish to set, include the following as a parameter:
    custom_property[<custom_property_name>] = <custom_property_value>

Response

Key-value pairs for all properties

Errors

Missing required parameter
Undefined property
Invalid value

Example Usage

Example Header and Body of an Executed Upload Request

See Appendix E for the example.

Replace media

Replace an existing media file in an account by uploading a new file
Note: The content-type of this method should be multipart/form-data in order to upload a binary file.
Note: The max file size permitted via API is 4 GB.
Warning: We recommend NOT replacing a file if the duration of the new file is different than the original. Doing so will affect the calculation of engagement metrics.
Warning: Playback for the media file will be temporarily unavailable during the replacement while new transcodes are produced.
Warning: Existing player embed codes will continue to function following a replace. However. the media playback URLs may have changed. If you reference URLs directly, we recommend that you re-query the API for URLs.

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>.{XML,JSON}

Formats

XML, JSON

HTTP Method

PUT

Requires Authentication

Required Parameters

media_file=<binary data for file> (This takes the form of a file part, in a multipart/form-data HTTP request)

Optional Parameters

encoding_profile_id = <the ID of the desired encoding profile; if no value is specified then the profile that is 'Active' on your account shall be used>
NOTE: When specifying this parameter, make sure it appears before the 'media_file' in your request. Otherwise the value will be ignored and the system will fallback to using the 'Active' profile.
NOTE: The ID of an encoding profile can be found by accessing 'Settings' then 'Encoding' in the Orchestrate Video console. Right-click on the profile name to reveal. Click to copy.

You can optionally update metadata at the same time as replacing a file. See section 2.3 above (optional parameters are those properties that are 'Updatable').

Values for existing custom metadata properties can also be set during replacement. For each custom property you wish to set, include the following as a parameter:
custom_property[<custom_property_name>] = <custom_property_value>

Response

Key-value pairs for all properties

Errors

Missing required parameter
Undefined property
Invalid value

4.2 Channel Methods

The following method is available for creating new channels:

Methods

Create a new channel

Create a new channel in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels.{XML,JSON}

Formats

XML, JSON

HTTP Method

POST

Requires Authentication

Required Parameters

title = <the title of the channel>

Optional Parameters

See section 2.2 above (optional parameters are those properties that are 'Updatable')

Response

Key-value pairs for all properties

Errors

Missing required parameter
Undefined property
Invalid value

Example Usage

Example code for this method can be found in section 9.2.5

4.3 Channel Group Methods

The following method is available for creating new channel groups:

Methods

Create a new channel group

Create a new channel group in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups.{XML,JSON}

Formats

XML, JSON

HTTP Method

POST

Requires Authentication

Required Parameters

title = <the title of the channel group>

Response

Key-value pairs for all properties

Errors

Missing required parameter
Undefined property
Invalid value

  5.0 API Requests - Update

Updates to media and channel information in your account can be accomplished using our suite of PUT requests. All results are returned in JSON format by default. You can specify an alternative response format (such as XML) by applying a 'dot-extension' on the end of the resource path.

5.1 Media Methods

The following methods are available for updating media content information:

Methods

Set one or more properties for a media

Update media properties for a specific media
Note: This does not apply to custom properties. To set custom properties, see section 7.0 below

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties.{XML,JSON}

Formats

XML, JSON

HTTP Method

PUT

Requires Authentication

Parameters

See section 2.3 above

NOTE: In order to perform a PUT request you will need to include the parameters in the body of the request rather than the header otherwise you will get a '411 Length Required' error.

Response

Key-value pairs for all properties

Errors

Missing required parameter
Undefined property
Invalid value
Media does not exist

Example Usage

Example code for this method can be found in section 9.2.4

Add a tag to an existing media

Append a tag to an existing media
Note: This differs from the "Set one or more properties for a media" method in that setting a tag via this method does not remove existing tags

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/tags/<tag>

Formats

None

HTTP Method

PUT

Requires Authentication

Parameters

None

Response

None

Errors

Invalid tag
Media does not exist

Add a closed captions file to a media

Upload a DFXP closed captions file for an existing media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/captions.{XML, JSON}

Formats

XML, JSON

HTTP Method

PUT

Requires Authentication

Required Parameters

caption_file=<binary data for file> (This takes the form of a file part, in a multipart/form-data HTTP request)

NOTE: Only files with an extension of 'dfxp' or 'xml' will be accepted.

Response

Key-value pairs for all media properties

Errors

Media either does not exist or you do not have access to it
You failed to supply the required caption_file attachment
Closed captioning files must have the extension '.dfxp' or '.xml'

Publish/Unpublish a Media

Request that a media be 'published' or 'unpublished'.
Note: You are not explicitly setting the state of the media with a call to this API. You are simply submitting a request that the media be 'published' or 'unpublished'. Upon request, the system will take care of setting the media state when appropriate. For example, if a media is currently 'uploading' or 'processing' and a request is made to 'publish' then the system will queue the request until the media has completed uploading and processing.

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/{publish, unpublish}.{xml,json}

Formats

XML, JSON

HTTP Method

POST

Requires Authentication

Parameters

None

Response

Key-value pairs for all media properties

Errors

Media either does not exist or you do not have access to it

Replace the cue points on a Media

Replace all the cue points on an existing media
NOTE: See Appendix C for specific examples of using this API. Also see our Cue Point Guide for a review of the various types and practical uses of cue points.

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/cuepoints.{xml,json}

Formats

XML, JSON

HTTP Method

POST

Requires Authentication

Required Parameters

cue_point_json=<JSON object that represents the cue points> (the object must adhere to the expected format. See Appendix C for examples)

Response

None

Example Usage

See Appendix C below

Replace the preview image on a media

Replace the existing preview/thumbnail image for a media by uploading a new image file. The system will use the uploaded file as the 'preview image' and automatically produce a smaller size for the 'thumbnail'.

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/preview_image.{XML, JSON}

Formats

XML, JSON

HTTP Method

PUT

Requires Authentication

Required Parameters

preview_image_file=<binary data for image file> (This takes the form of a file part, in a multipart/form-data HTTP request.)

NOTE: Only files with an extension of '.jpg', '.jpeg', '.gif', or '.png' will be accepted.

Response

Key-value pairs for all media properties. (NOTE: the image URLs in the response will be blank. The URLs will be available only after the image file is processed.)

Errors

Media either does not exist or you do not have access to it
You failed to supply the required preview_image_file attachment
Image files must have one of the following extensions ['.jpg', '.jpeg', '.gif', '.png']

5.2 Channel Methods

The following methods are available for updating channel content information:

Methods

Set one or more properties for a channel

Update channel properties for a specific channel

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/properties.{XML,JSON}

Formats

XML, JSON

HTTP Method

PUT

Requires Authentication

Parameters

See section 2.2 above

NOTE: In order to perform a PUT request you will need to include the parameters in the body of the request rather than the header otherwise you will get a '411 Length Required' error.

Response

Key-value pairs for all properties

Errors

Missing required parameter
Undefined property
Invalid value
Channel does not exist

Example Usage

Example code for this method can be found in section 9.2.5

Add existing media to a channel

Place existing media into an existing channel
NOTE: A channel can contain no more than 7000 media. Once a channel reaches 7000 media calls to this API will be ignored.

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/media/<media id>

Formats

None

HTTP Method

PUT

Requires Authentication

Parameters

None

Response

None

Errors

Media not owned by organization
Invalid value
Channel does not exist

Example Usage

Example code for this method can be found in section 9.2.5

5.3 Channel Group Methods

The following methods are available for updating channel group content information:

Methods

Set a property for a channel group

Update the channel group title

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channel id>/properties.{XML,JSON}

Formats

XML, JSON

HTTP Method

PUT

Requires Authentication

Parameters

title = <the title of the channel group>

NOTE: In order to perform a PUT request you will need to include the parameters in the body of the request rather than the header otherwise you will get a '411 Length Required' error.

Response

Key-value pairs for all properties

Errors

Missing required parameter
Undefined property
Invalid value
Channel group does not exist

Add an existing channel to a channel group

Place an existing channel into an existing channel group

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>/channels/<channel id>

Formats

None

HTTP Method

PUT

Requires Authentication

Parameters

None

Response

None

Errors

Invalid value
Channel group does not exist
Channel does not exist

  6.0 API Requests - Delete

The deletion of media and channel content information in your account can be accomplished using our suite of DELETE requests.

6.1 Media Methods

The following methods are available for deleting media content information:

Methods

Delete a media

This method will remove a specific media from an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Errors

Media does not exist

Remove a tag from an existing media

Deletes a tag form the list of tags for a media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/tags/<tag>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Errors

Media does not exist

Unset a single media property

Unsetting a media property will return it to the default value

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Errors

Media does not exist
Undefined property
Property cannot be deleted

Remove a closed captions file

Remove a closed captions file from a specific media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/captions.{XML, JSON};

Formats

XML, JSON

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

Key-value pairs for all media properties

Errors

Media either does not exist or you do not have access to it

6.2 Channel Methods

The following methods are available for deleting channel content information:

Methods

Delete a channel

This method will not delete the media within the channel from the account, only the channel will be deleted

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Errors

Channel does not exist

Remove media from a channel

Remove a specific media from a specific channel

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/media/<media id>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Errors

Channel does not exist
Media not in channel

Unset a single channel property

Unsetting a channel property will return it to the default value

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/properties/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Errors

Channel does not exist
Undefined property
Property cannot be deleted

6.3 Channel Group Methods

The following methods are available for deleting channel group content information:

Methods

Delete a channel group

This method will not delete the channels within the channel group, only the channel group itself will be deleted

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Remove a channel from a channel group

Remove a specific channel from a specific channel group

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>/channels/<channel id>

Formats

None

HTTP Method

DELETE

Requires Authentication

Parameters

None

Response

None

Errors

Channel group does not exist
Channel not in channel group

  7.0 API Requests - Extend

To accommodate special business needs, Limelight permits the creation and use of custom metadata properties in addition to the standard properties listed in section 2.0 above. Common applications of custom metadata include synchronization with an existing CMS and the tracking of information specific to a type of business (you may have a need to include information with your media or channels that is specific to your company or industry).

7.1 Custom Properties for Media

The creation, update, and deletion of custom metadata can be accomplished with the following methods:

Methods

Create media custom property

Add a custom media property to an account. The following types of custom properties can be created:
-- Text (the value of the custom property is free-form text)
-- List (the value of the custom property is limited to a predefined list)

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/properties/custom/<property name>

Formats

None

HTTP Method

PUT

Requires Authentication

Required Parameters

None

Optional Parameters

type = <text or list> (default: text)

If the type parameter is 'list', the following additional parameter is required:
default_values = <list of possible values for the custom property>

Response

None

Errors

Property name empty
Property already exists
Property name too long
Custom property type limit reached
Invalid characters in name
The custom property type specified was invalid
The custom property list type requires default values

Example Usage

Example code for this method can be found in section 9.2.6

Update media custom property

Update the details of a custom property including renaming, changing the type (text or list) or updating the list of possible values

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/properties/custom/<property name>

Formats

None

HTTP Method

POST

Requires Authentication

Required Parameters

new_property_name = <the existing name of the custom property or a new name if desired>

Optional Parameters

type = <text or list>
default_values = <list of possible values for the custom property>

Response

None

Errors

Undefined property
Property already exists
Property name too long
Invalid characters in name
The custom property type specified was invalid
The custom property list type requires default values

Delete media custom property

Remove a custom property from an account.
Note: Before deleting a custom property you may want to find out if the property is used. See the following method below: "Count the number of media with a value for a property"

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/properties/custom/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Required Parameters

None

Response

None

Errors

Undefined property
Property cannot be deleted

Assign a value to a custom property for a media

Add a value for a custom property for an existing media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/custom

Formats

None

HTTP Method

PUT

Requires Authentication

Required Parameters

For each custom property you wish to set, include the following as a parameter:
<custom_property_name> = <custom_property_value>

Response

None

Errors

Media id does not exist
Property value too long
The custom property value for a list type must match one of the list type's default values

Example Usage

Example code for this method can be found in section 9.2.6

Un-assign a value to a custom property for a media

Set the value of a custom property back to blank

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/custom/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Required Parameters

None

Response

None

Errors

Undefined property

List all custom property names in an account

Get a list of all custom property names in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/properties/custom.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

A list of all existing custom property names in the account

Errors

None

List all custom properties and details in an account

Get a list of all custom properties and details, including type and default list values

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/properties/custom_details.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

A list of all existing custom property details in the account

Errors

None

Get the value for a custom property for a media

Get the value of a particular custom property for a media

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/custom/<property name>.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pair of requested property

Errors

Media id does not exist

Example Usage

Example code for this method can be found in section 9.2.6

Count the number of media with a value for a property

Get a count of the number of media currently with an assigned value for a custom property.
Note: This method is useful for determining the use of a custom property before deleting.

URL

http://api.video.limelight.com/rest/organizations/<org id>/media/properties/custom/<property name>/count.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

The total number of media that has a value for the given <property name>

Errors

Media id does not exist
Undefined property

7.2 Custom Properties for Channels

The creation, update, and deletion of custom metadata for channels can be accomplished with the following methods:

Methods

Create channel custom property

Add a custom channel property to an account. The following types of custom properties can be created:
-- Text (the value of the custom property is free-form text)
-- List (the value of the custom property is limited to a predefined list)

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/properties/custom/<property name>

Formats

None

HTTP Method

PUT

Requires Authentication

Required Parameters

None

Optional Parameters

type = <text or list> (default: text)

If the type parameter is 'list', the following additional parameter is required:
default_values = <list of possible values for the custom property>

Response

None

Errors

Property name empty
Property already exists
Property name too long
Custom property type limit reached
Invalid characters in name
The custom property type specified was invalid
The custom property list type requires default values

Update channel custom property

Update the details of a channel custom property including renaming, changing the type (text or list) or updating the list of possible values

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/properties/custom/<property name>

Formats

None

HTTP Method

POST

Requires Authentication

Required Parameters

new_property_name = <the existing name of the custom property or a new name if desired>

Optional Parameters

type = <text or list>
default_values = <list of possible values for the custom property>

Response

None

Errors

Undefined property
Property already exists
Property name too long
Invalid characters in name
The custom property type specified was invalid
The custom property list type requires default values

Delete channel custom property

Remove a custom channel property from an account.
Note: Before deleting a custom property you may want to find out if the property is used. See the following method below: "Count the number of media with a value for a property"

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/properties/custom/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Required Parameters

None

Response

None

Errors

Undefined property
Property cannot be deleted

Assign a value to a custom property for a channel

Add a value for a custom property for an existing channel

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/properties/custom

Formats

None

HTTP Method

PUT

Requires Authentication

Required Parameters

For each custom property you wish to set, include the following as a parameter:
<custom_property_name> = <custom_property_value>

Response

None

Errors

Channel id does not exist
Property value too long
The custom property value for a list type must match one of the list type's default values

Un-assign a value to a custom property for a channel

Set the value of a custom property back to blank

URL

http://api.video.limelight.com/rest/organizations/<org id>/channel/<channel id>/properties/custom/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Required Parameters

None

Response

None

Errors

Undefined property

List all custom channel property names in an account

Get a list of all custom channel property names in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/properties/custom.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

A list of all existing custom channel property names in the account

Errors

None

List all custom channel properties and details in an account

Get a list of all custom channel properties and details, including type and default list values

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/properties/custom_details.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

A list of all existing custom channel property details in the account

Errors

None

Get the value for a custom property for a channel

Get the value of a particular custom property for a channel

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/properties/custom/<property name>.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pair of requested property

Errors

Channel id does not exist

Count the number of channels with a value for a property

Get a count of the number of channels currently with an assigned value for a custom property.
Note: This method is useful for determining the use of a custom property before deleting.

URL

http://api.video.limelight.com/rest/organizations/<org id>/channels/properties/custom/<property name>/count.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

The total number of channels that have a value for the given <property name>

Errors

Channel id does not exist
Undefined property

7.3 Custom Properties for Channel Groups

The creation, update, and deletion of custom metadata for channel groups can be accomplished with the following methods:

Methods

Create a channel group custom property

Add a custom channel group property to an account. The following types of custom properties can be created:
-- Text (the value of the custom property is free-form text)
-- List (the value of the custom property is limited to a predefined list)

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/properties/custom/<property name>

Formats

None

HTTP Method

PUT

Requires Authentication

Required Parameters

None

Optional Parameters

type = <text or list> (default: text)

If the type parameter is 'list', the following additional parameter is required:
default_values = <list of possible values for the custom property>

Response

None

Errors

Property name empty
Property already exists
Property name too long
Custom property type limit reached
Invalid characters in name
The custom property type specified was invalid
The custom property list type requires default values

Update a channel group custom property

Update the details of a custom property including renaming, changing the type (text or list) or updating the list of possible values

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/properties/custom/<property name>

Formats

None

HTTP Method

POST

Requires Authentication

Required Parameters

new_property_name = <the existing name of the custom property or a new name if desired>

Optional Parameters

type = <text or list>
default_values = <list of possible values for the custom property>

Response

None

Errors

Undefined property
Property already exists
Property name too long
Invalid characters in name
The custom property type specified was invalid
The custom property list type requires default values

Delete a channel group custom property

Remove a custom property from an account.
Note: Before deleting a custom property you may want to find out if the property is used. See the following method below: "Count the number of channel groups with a value for a property"

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/properties/custom/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Required Parameters

None

Response

None

Errors

Undefined property
Property cannot be deleted

Assign a value to a custom property for a channel group

Add a value to a custom property for an existing channel group

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>/properties/custom

Formats

None

HTTP Method

PUT

Requires Authentication

Required Parameters

For each custom property you wish to set, include the following as a parameter:
<custom_property_name> = <custom_property_value>

Response

None

Errors

Channel group id does not exist
Property value too long
The custom property value for a list type must match one of the list type's default values

Un-assign a value to a custom property for a channel group

Set the value of a custom property back to blank

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>/properties/custom/<property name>

Formats

None

HTTP Method

DELETE

Requires Authentication

Required Parameters

None

Response

None

Errors

Undefined property

List all custom property names in an account

Get a list of all channel group custom property names in an account

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/properties/custom.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

A list of all existing custom property names in the account

Errors

None

List all custom properties and details in an account

Get a list of all custom properties and details, including type and default list values for channel groups

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/properties/custom_details.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

A list of all existing custom property details in the account

Errors

None

Get the value for a custom property for a channel group

Get the value of a particular custom property for a channel group

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/<channelgroup id>/properties/custom/<property name>.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

Key-value pair of requested property

Errors

Channel group id does not exist

Count the number of channel groups with a value for a property

Get a count of the number of channel groups currently with an assigned value for a custom property.
Note: This method is useful for determining the use of a custom property before deleting.

URL

http://api.video.limelight.com/rest/organizations/<org id>/channelgroups/properties/custom/<property name>/count.{XML,JSON}

Formats

XML, JSON

HTTP Method

GET

Requires Authentication

NO

Parameters

None

Response

The total number of channel groups that have a value for the given <property name>

Errors

Channel group id does not exist
Undefined property

  8.0 Authentication - Signing Requests

In order to ensure the security of your information we require some requests to be authenticated. All methods indicated above as requiring authentication must have a signature. A signature is generated by doing an HMAC 264 hash on the request URL and its parameters. In order to do this you will need to obtain your unique access_key and secret. The access_key is passed as a normal parameter to the URL. The secret is used to generate a signature by performing a hash. Both the access_key and secret can be found in your Limelight Orchestrate Video account, under the 'Developer Tools' tab in 'Settings'. Lastly, you will need to determine a value for the expires parameter. This value, represented in Unix Time, indicates when the URL should no longer return results. A handy Unix Time converter can be found here: http://www.epochconverter.com

To illustrate the steps involved in generating a signature, we provide an example below. In this example, we authenticate the URL used to 'Create a new channel':

We will use the following variables for this example:
Org ID:bfb3caa8e6204fea9a23ce855768fc93
Access Key:ezU4jGTelX8UAsfaiWUcjWsn1mY=
Secret:+IEbSWOctQhaMi7DGop9KdPysqw=
Expires:1298347550
  1. Start with the base URL for your request. The base URL for 'Create a new channel' looks like this:
    http://api.video.limelight.com/rest/organizations/bfb3caa8e6204fea9a23ce855768fc93/channels
  2. Drop the 'http://' prefix and append the http verb ('get', 'post', 'put', or 'delete') to the front of the base URL and surround the host of the URL and the path of the URL with the '|' symbol. Make sure everything is lower case. Our URL string now looks like this (notice there are three places where the '|' symbol has been inserted):
    post|api.video.limelight.com|/rest/organizations/bfb3caa8e6204fea9a23ce855768fc93/channels|
  3. Next, sort the list of parameters alphabetically and append them as <key>=<value> pairs to the end of the URL string. Separate all parameters with the '&' symbol. Our URL string now looks like this (the parameters are bolded):
    post|api.video.limelight.com|/rest/organizations/bfb3caa8e6204fea9a23ce855768fc93/channels|access_key=ezU4jGTelX8UAsfaiWUcjWsn1mY=&expires=1298347550
  4. Now, using your secret, generate a sha256 HMAC hash in base 64 format on the URL string. The result of this hash will be your signature. In this example, our signature looks like this:
    +b5WNmwbdDe0eLwsTPgH75gRSWbIkECEbqthQhXLTrc=
  5. Lastly, create the final executable URL by beginning with the base URL. Append all the parameters in alphabetic order, starting with '?' and separated by '&'. URL encode all key and values on your parameters. Finally, URL encode the signature you generated above and append it at the end as signature=<signature>. The final executable URL looks like this:
    http://api.video.limelight.com/rest/organizations/bfb3caa8e6204fea9a23ce855768fc93/channels?access_key=ezU4jGTelX8UAsfaiWUcjWsn1mY%3D&expires=1298347550&signature=%2Bb5WNmwbdDe0eLwsTPgH75gRSWbIkECEbqthQhXLTrc%3D

8.1 Code to Perform Authentication

Limelight offers the following code to aid in authenticating requests. Simply drop this into your project and call the authentication function with the right parameters. The result will be an authenticated request:
PHP LvpAuthUtil.php
Ruby LvpAuthUtil.rb
Java LvpAuthUtil.java
C# LvpAuthUtil.cs
VB LvpAuthUtil.vb
Python LvpAuthUtil.py

  9.0 Example Code

The following are examples of executing some of the methods in the above sections.

9.1 Ruby

9.1.1 (Example 1) Get a List of All 'published' Channels

A list of all 'published' channels can be obtained through a GET method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/channels

The following code illustrates a possible execution of this method:
require 'net/http'
require 'yaml'
require 'pp'

org_id = '<your org here>'
yaml_text =
Net::Http.get(URI.parse("http://api.video.limelight.com/rest/organizations/
{org_id}/channels.yaml")
pp YAML::load(yaml_text)

9.1.2 (Example 2) Get a List of All Media Associated with a Specific Channel

A list of all media associated with a channel can be obtained through a GET method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/media

The following code illustrates a possible execution of this method:
require 'net/http'
require 'yaml'
require 'pp'

org_id = '<your org here>'
channel_id = '<desired channel id here>'
yaml_text =
Net::Http.get(URI.parse("http://api.video.limelight.com/rest/organizations/
{org_id}/channels/{channels_id}/media.yaml")
pp YAML::load(yaml_text)

9.2 PHP

All PHP code examples make use of the following code in order to authenticate requests: LvpAuthUtil.php

9.2.1 (Example 3) Get a List of All Channels, Including 'unpublished' Channels

Description Get a listing of all channels in an account, count the channels and output the count to the screen.
Code Sample api_auth_example.txt



A list of all channels can be obtained through a GET method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/channels/all

However, this method requires authentication. The URL must first be signed before execution. In this example, a call to the following function returns the signed URL:
$signed_request = LvpAuthUtil::authenticate_request("GET", $request, $access_key, $secret);

The parameters to the above function are the HTTP method, the URL to be authenticated, the authentication access key, and the authentication secret.

  include 'LvpAuthUtil.php';

  $access_key = "<INSERT_YOUR_ACCESS_KEY>";
  $secret = "<INSERT_YOUR_SECRET>";
  $org_id = "<INSERT_YOUR_ORG_ID>";
  
  $request = "http://api.video.limelight.com/rest/organizations/$org_id/channels/all.json";

The authenticated URL can then be executed and the response parsed. In this example, the response is parsed to display a total channel count.
  $response = file_get_contents($signed_request);
  
  $channel_array = json_decode($response);  
  echo("<p>There are " . count($channel_array->channel_list) . " total channels</p>");

9.2.2 (Example 4) Upload a New Media to an Account - Client Upload

Description Upload a new media to an account. Use the browser to perform the POST and a simple HTML form to gather viewer input.

Limitations: Because the browser is performing the upload, the browser will receive the response. If you would like to perform an action based on the response (e.g. do something specific with the returned media ID) you will need to perform the upload from your server. See 9.2.3 for an example of a server upload.
Code Sample upload_example.txt



New media can be uploaded through a POST method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/media

However, this method requires authentication. The URL must first be signed before attempting to upload new media. The following code illustrates the authentication:
<?php 

  include 'LvpAuthUtil.php';

  $access_key = "<INSERT_YOUR_ACCESS_KEY>";
  $secret = "<INSERT_YOUR_SECRET>";
  $org_id = "<INSERT_YOUR_ORG_ID>";
  
  // Authenticate the upload URL
  $add_media_url = "http://api.video.limelight.com/rest/organizations/$org_id/media";
  
  $signed_url = LvpAuthUtil::authenticate_request("POST", $add_media_url, $access_key, $secret);
?>  

The authenticated upload URL, returned by the above function can then be used to upload new media. The following example uses the authenticated URL and an HTML form to submit new media:
<!--Execute the signed upload URL when the user submits a new file-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<title>Upload to Limelight Orchestrate Video</title>
</head>
<body>
  Uploading:<br><form action="<?php echo $signed_url; ?>" method="post" enctype="multipart/form-data">
  <input name="title" value="title" type="text" /><br>
  <input name="description" value="description" type="text" /><br>
  <input name="media_file" type="file" /><br>
  <input type="submit" />
  </form>
</body>
</html>

9.2.3 (Example 5) Upload a New Media to an Account - Server Upload

Description Upload a new media to an account. Execute the upload from the server using curl.
Code Sample upload_example_curl.txt



New media can be uploaded through a POST method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/media

However, this method requires authentication. The URL must first be signed before attempting to upload new media. The following code declares the parameters of the upload and illustrates the authentication of the URL:
<?php 

  include 'LvpAuthUtil.php';

  $access_key = "<INSERT_YOUR_ACCESS_KEY>";
  $secret = "<INSERT_YOUR_SECRET>";
  $org_id = "<INSERT_YOUR_ORG_ID>";
  
 $file = '@ski.MOV';
 $title = 'API Upload';
 $description = 'This file was uploaded with the LVP API using PHP and Curl.';
 $upload_media_url = "http://api.video.limelight.com/rest/organizations/$org_id/media";
 
 //authenticate the upload URL
 $signed_url = LvpAuthUtil::authenticate_request("POST", $upload_media_url, $access_key, $secret);
?>  

The authenticated upload URL, returned by the above function can then be used to upload new media. Curl is used to POST the upload parameters (e.g. title, description and media_file) to the authenticated URL.
<?php

//arrange the details of the upload in an array
 $post_params = array("title" => $title, "description" => $description, "media_file" => $file);
 
 //perform the POST using CURL, passing in the array of parameters
 $upload_response = do_post($signed_url, $post_params);
 
 //display the media ID of the new upload on the screen 
 $response_obj = json_decode($upload_response);
 echo 'Media ID: ' .$response_obj->media_id;
 
  
 function do_post($url, $params=array()) {
 //this function will perform the POST using curl

	// get the curl session object
    $session = curl_init($url);
    
    // set the POST options.
    curl_setopt($session, CURLOPT_POST, true);
    curl_setopt($session, CURLOPT_POSTFIELDS, $params);
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    
    // do the POST and then close the session
    $response = curl_exec($session);
    curl_close($session);
    return $response;
  }
?>  

9.2.4 (Example 6) Update the Property of a Media

Description Update the title and description of an existing media in an account.
Code Sample api_update_media.txt



Media properties can be updated (or set) through a PUT request to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties

However, this method requires authentication. The URL must first be signed before attempting to update the media. The following code declares the parameters of the upload and illustrates the authentication of the URL:
<?php 

  include 'LvpAuthUtil.php';

  $access_key = "<INSERT_YOUR_ACCESS_KEY>";
  $secret = "<INSERT_YOUR_SECRET>";
  $org_id = "<INSERT_YOUR_ORG_ID>";
  
  $media_id = "<YOUR MEDIA ID>";
  
  $update_media_url = "http://api.video.limelight.com/rest/organizations/$org_id/media/
  $media_id/properties";
  
  # authenticate the call to the api
  $signed_update_media_url = LvpAuthUtil::authenticate_request("PUT", $update_media_url, $access_key, $secret);
?>  

The authenticated URL, returned by the above function can then be used to update the properties of the media. Curl is used to execute the PUT request, placing the parameters (e.g. title and description) in the body of the request
<?php

  # update the media title and description
  $params = array("title" => "my new title", "description" => "my new description");
  $put_response = do_put($signed_update_media_url, $params);

  
  # Execute the PUT
  function do_put($url, $params=array()) {
  
    // Get the curl session object
    $session = curl_init($url);
    
    // Set the PUT options.  
    curl_setopt($session, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_POSTFIELDS, $params);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    
    // Do the PUT and then close the session
    $response = curl_exec($session);
    curl_close($session);
    return $response;
  }
?>  

9.2.5 (Example 7) Create a New Channel, Add Media to the Channel and Publish

Description Create a new channel in an account. Once the channel is created, place a media in the channel and set the state of the channel to 'Published'. Get the embed code for the channel and display the corresponding player on the screen.
Code Sample api_add_new_and_update_channel.txt



A new channel can be added through a POST method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/channels

However, this method requires authentication. The URL must first be signed before a new channel can be created. The following code illustrates the authentication:
<?php 

  include 'LvpAuthUtil.php';

  $access_key = "<INSERT_YOUR_ACCESS_KEY>";
  $secret = "<INSERT_YOUR_SECRET>";
  $org_id = "<INSERT_YOUR_ORG_ID>";

  $add_new_channel_url = "http://api.video.limelight.com/rest/organizations/$org_id/channels";

  // obtain a signature for the add new channel URL
  $signed_add_channel_url = LvpAuthUtil::authenticate_request("POST", $add_new_channel_url, $access_key, $secret);
?>  

The authenticated URL, returned by the above function can then be used to add the new channel. The following example executes the signed request:
// perform the addition of the new channel
$params = array("title" => "My New API Channel")
$add_channel_response = do_post($signed_add_channel_url, $params);


  function do_post($url, $params=array()) {
  //this function will perform a POST using curl

	// get the curl session object
    $session = curl_init($url);
    
    // set the POST options.
    curl_setopt($session, CURLOPT_POST, true);
    curl_setopt($session, CURLOPT_POSTFIELDS, $params);
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    
    // do the POST and then close the session
    $response = curl_exec($session);
    curl_close($session);
    return $response;
  }


Once the new channel is added, media can then be placed in the channel through a PUT method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/media/<media id>

However, this method also requires authentication. The URL must have a signature before adding media to the channel. The following code illustrates the authentication. Notice that we are utilizing a variable called $new_channel_id. In this example, this variable contains the ID of the channel we just added above:
<?php 
  $media_id_to_add = "d6fafd2da733467fac0ba2788993fae8";
 

  $add_media_to_channel_url = "http://api.video.limelight.com/rest/organizations/$org_id/channels/
$new_channel_id/media/$media_id_to_add";

  # obtain a signature for the add media to channel URL
  $signed_add_media_url = LvpAuthUtil::authenticate_request("PUT", $add_media_to_channel_url, $access_key, $secret);
?>  

The authenticated URL, returned by the above function can then be used to add media to the channel. The following example executes the signed request:
$add_media = do_put($signed_add_media_url);


  function do_put($url, $params=array()) {
  //this function will perform a PUT using curl
  
    // get the curl session object
    $session = curl_init($url);
    
    // set the PUT options.  
    curl_setopt($session, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_POSTFIELDS, $params);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    
    // do the PUT and then close the session
    $response = curl_exec($session);
    curl_close($session);
    return $response;
  }


Finally, we can publish our new channel by updating the channel state. A channel can be updated by a PUT to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/channels/<channel id>/properties

However, like the others above, this method also requires authentication. The following code illustrates the authentication:
<?php 

  $update_channel_url = "http://api.video.limelight.com/rest/organizations/$org_id/channels/
$new_channel_id/properties";

  # obtain a signature for the update channel URL
  $signed_update_channel_url = LvpAuthUtil::authenticate_request("PUT", $update_channel_url, $access_key, $secret);
?>  

The authenticated URL, returned by the above function can then be used to publish the channel. The following example executes the signed request. Notice that we are setting the "state" to "Published":
// perform the channel update
$params = array("state" => "Published");
$put_response = do_put($signed_update_channel_url, $params);


  function do_put($url, $params=array()) {
  //this function will perform a PUT using curl
  
    // get the curl session object
    $session = curl_init($url);
    
    // set the PUT options.  
    curl_setopt($session, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_POSTFIELDS, $params);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    
    // do the PUT and then close the session
    $response = curl_exec($session);
    curl_close($session);
    return $response;
  }


9.2.6 (Example 8) Create a New Custom Property and Assign a Value for a Media

Description Add a new custom media property to an account. Assign a value for this new property on a media and output the result as a key/value pair to the screen.
Code Sample api_create_custom_prop_example.txt



A new custom property can be added through a PUT method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/media/properties/custom/<property name>

However, this method requires authentication. The URL must first be signed before executing to create a new custom property. The following code illustrates the authentication:
<?php 

  include 'LvpAuthUtil.php';

  $access_key = "<INSERT_YOUR_ACCESS_KEY>";
  $secret = "<INSERT_YOUR_SECRET>";
  $org_id = "<INSERT_YOUR_ORG_ID>";

  $new_prop_name = "<ADD_YOUR_PROP_NAME>";
  $media_id = "<ADD_YOUR_MEDIA_ID>";
  
  $new_prop_value = "Yes";

  $create_new_property_url = "http://api.video.limelight.com/rest/organizations/$org_id/media/properties/
custom/$new_prop_name";

  # obtain a signature for creating the new custom property

  $signed_create_new_property_url = LvpAuthUtil::authenticate_request("PUT", $create_new_property_url, $access_key, $secret);
?>  

The authenticated URL, returned by the above function can then be used to add a new custom property. The following example executes the signed request:
# perform the creation of the new custom property
$params = array("type" => "list", "default_values" => "Yes,No,Maybe");
$put_response = do_put($signed_create_new_property_url, $params);


  # Execute the PUT
  function do_put($url, $params=array()) {
  
    // Get the curl session object
    $session = curl_init($url);
    // Set the PUT options.  
    curl_setopt($session, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_POSTFIELDS, $params);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    // Do the PUT and then close the session
    $response = curl_exec($session);
    curl_close($session);
    return $response;
  }


Once the new custom property is added a value can be assigned for a media through a PUT method to the following URL:
http://api.video.limelight.com/rest/organizations/<org id>/media/<media id>/properties/custom

However, this method also requires authentication. The following code illustrates the authentication:
<?php 

  include 'LvpAuthUtil.php';

  $access_key = "<INSERT_YOUR_ACCESS_KEY>";
  $secret = "<INSERT_YOUR_SECRET>";
  $org_id = "<INSERT_YOUR_ORG_ID>";

  $new_prop_name = "<ADD_YOUR_PROP_NAME>";
  $media_id = "<ADD_YOUR_MEDIA_ID>";
  
  $new_prop_value = "Yes";

  $assign_value_for_cust_prop_for_a_media_url = "http://api.video.limelight.com/rest/organizations/$org_id/media/$media_id/
properties/custom";

  # obtain a signature for creating the new custom property

  $signed_add_value_property_url = LvpAuthUtil::authenticate_request("PUT", $assign_value_for_cust_prop_for_a_media_url, $access_key, $secret);
?>  

The authenticated URL, returned by the above function can then be used to add the value for the custom property. The following example executes the signed request:
# perform the addition of the value to the media
$params = array($new_prop_name => $new_prop_value);
$put_response = do_put($signed_add_value_property_url, $params);


  # Execute the PUT
  function do_put($url, $params=array()) {
  
    // Get the curl session object
    $session = curl_init($url);
    
    // Set the PUT options.  
    curl_setopt($session, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($session, CURLOPT_HEADER, false);
    curl_setopt($session, CURLOPT_POSTFIELDS, $params);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    
    // Do the PUT and then close the session
    $response = curl_exec($session);
    curl_close($session);
    return $response;
  }



Finally, we can show the new property name and value by outputting the key-value pair. In this example we use a simple HTML form to perform a GET method:
<?php
  $get_name_and_value_of_cust_property_for_a_media_url = "http://api.video.limelight.com/rest/organizations/$org_id/media/$media_id/
properties/custom/$new_prop_name";

?>

<!--Display the name and value of the newly created custom property-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<title>Show New Custom Property</title>
</head>
<body>
  <br><form action="<?php echo $get_name_and_value_of_cust_property_for_a_media_url; ?>" method="get" enctype="multipart/form-data">
  <input type="submit" value="Get Name and Value of Your Newly Added Prop"/>
  </form>
</body>
</html>

9.3 C#

9.3.1 (Example 9) Upload a New Media to an Account

Description Perform the upload of a new media to an account.
Code Sample lvp_upload_api_asp_c_sharp_sample.zip


9.4 VB

9.4.1 (Example 10) Upload a New Media to an Account

Description Perform the upload of a new media to an account.
Code Sample lvp_upload_api_vb_sample.zip




  10.0 Upload Widget

Note: The Upload Widget is only available for Professional, Premier, and Enterprise customers and must be enabled for your account.

For convenience, we provide a Flash upload widget that can be seamlessly embedded on your website, allowing for user generated content or an alternate way to upload directly to your Limelight Orchestrate Video account. A screenshot of the widget is shown here:

To use the widget, execute the following:
  1. Obtain your organization ID, access key, and secret. These can be found in your account, under the 'Developer Tools' tab in 'Settings'
  2. When your web application renders the page that will contain the widget, perform the following. Note: For extra security, it is recommended that these steps be performed on the server:
    1. Authenticate an 'Upload Media' URL using the following parameters (more details on authenticating can be found in section 8.0 above):
      Http_verb: POST
      Resource_url: http://api.video.limelight.com/rest/organizations/<org id>/media
      Secret: <YOUR_SECRET>
      Access_key: <YOUR_ACCESS_KEY>
      Expires: <YOUR_DESIRED_EXPIRATION>

      For 'expires', we suggest using an expiration time that is equal to the number of minutes in a user session.

    2. URL-encode the authenticated URL
    3. Render the following embed code on the page, substituting your own values for 'presigned_url' and 'redirect_to':
      <object id='obj1'
      classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'
      codebase='http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=8,5,0,0' height='400' width='500'>
      <param name='src'
      value='http://video.limelight.com/upload-widget/current.swf'/>
      <param name='AllowScriptAccess' value='always'/>
      <param name='flashvars' value='presigned_url=[URL-ENCODED UPLOAD URL]&redirect_to=[URL-ENCODED REDIRECT TARGET]'/>
      <embed name='obj2'
      pluginspage='http://www.macromedia.com/go/getflashplayer'
      AllowScriptAccess='always'
      src='http://video.limelight.com/upload-widget/current.swf'
      height='325' width='475' flashvars='presigned_url=[URL-ENCODED UPLOAD URL]&redirect_to=[URL-ENCODED REDIRECT TARGET]'/>
      </object>
                  

10.1 Getting the Upload Widget Response

By declaring a javascript callback function called 'delveUploadWidgetCallback' on the same page as your embedded Upload Widget you can obtain information about the uploaded media once the upload has completed. For example, you can retrieve the ID of the newly uploaded media and perform an action. The callback function will receive an object containing all the media properties for the recent upload.

The callback function should take the following form:
<script type="text/javascript">
var media;
function delveUploadWidgetCallback(data) 
{
  media = eval("media = " + unescape(data));
 
  <insert your logic here>
  
}
</script>

The following code example declares an Upload Widget callback function that displays the details of the newly uploaded media (e.g. id, title, desscription) and then displays a redirect option to the viewer using the media id as a query string:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   "http://www.w3.org/TR/html4/loose.dtd">

<html>

<script type="text/javascript">
var media;
var redir_url;
function delveUploadWidgetCallback(data) 
{
  media = eval("media = " + unescape(data));
 
  document.getElementById('mediaId').innerHTML = media.media_id;
  document.getElementById('desc').innerHTML = media.description;
  document.getElementById('orgFilename').innerHTML = media.original_filename;
  document.getElementById('redirect_b').style.display = "block";
  
  redir_url = "http://www.example.com?mediaId=" + media.media_id;
  
}
</script>


<body>

<INSERT_YOUR_UPLOAD_WIDGET_CODE_HERE>
            
<br /><br />

Details of the recently uploaded media: <br /><br />

Media ID = <span id="mediaId"></span>
<br />
Description = <span id="desc"></span>
<br />
Original Filename = <span id ="orgFilename"></span>
<br /><br />
<span id="redirect_b" style="display: none">
<input type="button" onClick="javascript:window.location = redir_url;" value="Press to Redirect with New Media ID as a Query String"/>
</span>

</body>

</html>


Appendix A
Searching for Media Examples

The examples below illustrate common uses of the 'search for media' API referenced in Section 3.1 above. All examples make use of the following code in order to authenticate requests: LvpAuthUtil.php.

Search for all media

Description A list of all media in an account can be obtained by simply calling the search API with no parameters.
Code Sample search_for_all_media.txt

Search for only published media

Description To get a list of published media we simply need to specify a single <key>:<value> pair (i.e. 'and=state:published')
Code Sample search_for_pub_media.txt

Search for media that meets AND criteria

Description Let's say we wanted to list all 'published' media that has a tag of 'football'. To do this we need two <key>:<value> pairs and the 'and' parameter, like this: 'and=state:published;tag:football'
Code Sample search_using_and_criteria.txt

Search for media that meets OR criteria

Description Let's say we wanted to list all media that has a tag of 'football' or a tag of 'hockey'. To do this we need two <key>:<value> pairs and the 'or' parameter, like this: 'or=tag:football;tag:hockey'
Code Sample search_using_or_criteria.txt

Search for media that does NOT meet criteria

Description Let's say we wanted to list all media that does not have a tag of 'football'. To do this we need to imply negation. We do this by putting a dash ('-') before the <key>, like this: 'and=-tag:football'
Code Sample search_using_negation.txt

Limit search to a particular channel

Description Let's say we wanted to list all media that has a tag of 'football' that currently exists in a particular channel (e.g. the channel corresponding to the ID of 'f608e642dc824303b023e6519c15afc6'). To do this we do the following: 'and=tag:football;channel_id:f608e642dc824303b023e6519c15afc6')
Code Sample limit_search_to_a_channel.txt

Search for media that has a value (any value) populated for a property

Description If you want to find media that has a value (any value) populated for a property you simply specify a <key> with no <value>. For example, let's say I want to find all media that was created after a particular date that has a populated description. The parameters for this would look like this: and=created_after:1322852843;description (notice we do not specify a <value> for description)
Code Sample search_for_media_that_has_a_value.txt

Search for media that matches complex criteria

Description Let's say we wanted to get a list of non-errored audio and video files that have a tag of 'football'. We can do this by using both the 'and' & 'or' parameters. SQL for this query would look something like this:

WHERE tag = football AND state != error AND (media_type = audio OR media_type = video)

The equivalent using the search API would look like this (notice we use the dash ('-') before 'state' to imply negation):

and=tag:football;-state:error&or=media_type:audio;media_type:video
Code Sample search_for_media_with_complex_criteria.txt


Appendix B
Example Query Request Response

API query request:
Subset of the Returned Results:
<media-list has_next="false" data_as_of="1308339832" page_id="0" type="array">
<media>
      <id>934f1baa4e6049b59568c0715bbc7eeb</id>
      <title>Chelsea vs Liverpool</title>
      <description>
      A game between Chelsea and Liverpool in the British Premier League
      </description>
      <media_type>Video</media_type>
      <original_filename>chelsea-vs</original_filename>
      <state>Published</state>
      <duration_in_milliseconds>644800</duration_in_milliseconds>
      <total_storage_in_bytes>1045502298</total_storage_in_bytes>
      <category>Sports<category/>
      <ref_id>My Video ID</ref_id>
      <thumbnails>
           <thumbnail width="120" height="66">
                <url>
                http://cpc.delvenetworks.com/bUJCvQz5QIMoBlb_CCD5G4/k08bqk5gSbUlWjAcVu8fus/ye8.120x66.jpeg
                </url>
           </thumbnail>
           <thumbnail width="540" height="304">
                <url>
                http://cpc.delvenetworks.com/bUJCvQz5QIMoBlb_CCD5G4/k08bqk5gSbUlWjAcVu8fus/ye8.540x304.jpeg
                </url>
           </thumbnail>
      </thumbnails>      
      <tags>
           <tag>chelsea</tag>
           <tag>english premier league</tag>
           <tag>football</tag>
           <tag>liverpool</tag>
      </tags>
      <sched_start_date/>
      <sched_end_date/>
      <publish_date>1297964805</publish_date>
      <update_date>1301809662</update_date>
      <create_date>1297902935</create_date>
      <custom_property>
      </custom_property>
</media>
<media>
      <id>6c8e57248a6e4f0fa9a0093d4c61b938</id>
      <title>Harry Potter - Halfblood Prince</title>
      <description>The sixth movie in the Harry Potter saga</description>
      <media_type>Video</media_type>
      <original_filename>harrypotterhalfbloodprince-tlr4b_h720p_stereo</original_filename>
      <state>Published</state>
      <duration_in_milliseconds>144230</duration_in_milliseconds>
      <total_storage_in_bytes>760835214</total_storage_in_bytes>
      <category>Entertainment</category>
      <ref_id/>My Movie ID2<ref_id/>
      <thumbnails>
           <thumbnail width="120" height="50">
                <url>
                http://cpc.delvenetworks.com/bUJCvQz5QIMoBlb_CCD5G4/bI5XJIpuTw8qaAJPUxhuTg/cyM.120x50.jpeg
                </url>
           </thumbnail>
           <thumbnail width="540" height="228">
                <url>
                http://cpc.delvenetworks.com/bUJCvQz5QIMoBlb_CCD5G4/bI5XJIpuTw8qaAJPUxhuTg/cyM.540x228.jpeg
                </url>
           </thumbnail>
      </thumbnails>      
      <tags>
           <tag>halfblood prince</tag>
           <tag>harry potter</tag>
           <tag>delve networks</tag>
           <tag>movie</tag>
     </tags>
     <sched_start_date/>
     <sched_end_date/>
     <publish_date>1297294575</publish_date>
     <update_date>1302852324</update_date>
     <create_date>1297294202</create_date>
     <custom_property>
        <Embedded_On>Javascript Sample Page</Embedded_On>
     </custom_property>
</media>
</media-list>

Appendix C
Cue Point API Examples

The examples below illustrate how to use the 'Replace the cue points on a Media' API referenced in Section 5.1 above. All examples make use of the following code in order to authenticate requests: LvpAuthUtil.php.

Apply an 'Ad' Cue Point

Description In this example we show how to apply 'Ad' cue points to a media. This particular example is specific to 'DART' or 'VAST' delivered ads.
Implementation To apply 'Ads' to a media you must construct a JSON object that represents the desired cue points. Your object must adhere to the expected format for an 'Ad' cue point which is outlined in the table below. Use the object as the value for the 'cue_point_json' parameter in the call to the API.
Element Description
placement String: Set to "BEFORE" for a pre-roll; "DURING" for a mid-roll; "AFTER" for a post-roll
name String: Specify a name for the cue point
startPositionInMilliseconds Number: Set to -2147483648 if pre-roll; Set to 2147483648 if post-roll; Set to the desired position in milliseconds if mid-roll
endPositionInMilliseconds Number: Set to -2147483648 if pre-roll; Set to 2147483648 if post-roll; Set to the same value as 'startPositionInMilliseconds' if mid-roll
index Number: This is a zero-based index - increment by one for each cue point
details Object: A nested JSON object that has the following ad-specific properties:
adType String: Set to 'Dart' or 'VAST'
isOverlay Boolean: Set to 'false'
trackingPixelUrls String: The URL of a tracking pixel for the event (set to null if no pixels)
adDetails Object: A nested JSON object that has the following specific properties:
url String: URL of the ad-tag
Code Sample ad_cuepoint.txt

The JSON below shows an example of a properly formatted object for an 'Ad' cue point. This specific example will result in the creation of three ad cue points - one pre-roll (before), one mid-roll (during) and one post-roll (after). NOTE: The JSON has been altered slightly for display purposes.
[
	{
		"placement":"BEFORE",
		"startPositionInMilliseconds":-2147483648,
		"endPositionInMilliseconds":-2147483648,
		"name":"My pre-roll",
		"index":0,
		"details": {
			"adType":"Dart",
			"isOverlay":false,
			"trackingPixelUrls":null,
			"adDetails": {
				"url":"http://example.com/adtag/"
				}
			}
	},
	{
		"placement":"DURING",
		"startPositionInMilliseconds":6000,
		"endPositionInMilliseconds":6000,
		"name":"My mid-roll",
		"index":1,
		"details": {
			"adType":"Dart",
			"isOverlay":false,
			"trackingPixelUrls":null,
			"adDetails": {
				"url":"http://example.com/adtag/"
				}
			}
	},
	{
		"placement":"AFTER",
		"startPositionInMilliseconds":2147483647,
		"endPositionInMilliseconds":2147483647,
		"name":"My post-roll",
		"index":2,
		"details": {
			"adType":"Dart",
			"isOverlay":false,
			"trackingPixelUrls":null,
			"adDetails": {
				"url":"http://example.com/adtag/"
				}
			}
	}
] 

Apply a 'Custom Event' Cue Point

Description In this example we show how to apply 'Custom Event' cue points to a media. A 'Custom Event' is a generic mechanism to define, track and trigger an event. For example, custom events could be used to declare chapters (or seek points) within a video. See our Cue Point Guide for more information on the practical uses of 'Custom Events'.
Implementation To apply 'Custom Events' to a media you must construct a JSON object that represents the desired cue points. Your object must adhere to the expected format for a 'Custom Event' which is outlined in the table below. Use the object as the value for the 'cue_point_json' parameter in the call to the API.
Element Description
type Number: Always set to 2
placement String: Always set to "DURING"
name String: The name of the event
index Number: This is a zero-based index - increment by one for each cue point
startPositionInMilliseconds Number: The moment during playback when the custom event should fire
details Object: A nested JSON object that has the following event-specific properties:
data String: Any data you want to store with the event
trackingPixelUrls String: The URL of a tracking pixel for the event (set to null if no pixels)
Code Sample custom_event_cuepoint.txt

The JSON below shows an example of a properly formatted object for a 'Custom Event' cue point. This specific example will result in the creation of two events. NOTE: The JSON has been altered slightly for display purposes.
[
	{
		"type": 2,
		"placement": "DURING",
		"name": "My Custom Event 1",
		"index": 0,
		"startPositionInMilliseconds": 60000,
		"details": {
			"trackingPixelUrls":null,
			"data":"My data 1" 
			}
	},
	{
		"type": 2,
		"placement": "DURING",
		"name": "My Custom Event 2",
		"index": 1,
		"startPositionInMilliseconds": 120000,
		"details": {
			"trackingPixelUrls":null,
			"data":"My data 2"
			}
	}
]

Apply a 'Content Overlay' Cue Point

Description In this example we show how to apply 'Content Overlay' cue points to a media. A 'Content Overlay' is used to display a non-linear call to action during video playback. A common use case for a content overlay is a 'click here' or 'buy it now' button. See our Cue Point Guide for more information on the practical uses of 'Content Overlays'.
Implementation To apply 'Content Overlay' to a media you must construct a JSON object that represents the desired cue points. Your object must adhere to the expected format for a 'Content Overlay' which is outlined in the table below. Use the object as the value for the 'cue_point_json' parameter in the call to the API.
Element Description
type Number: Always set to 1
placement String: Always set to "DURING"
name String: The name you wish to apply to the cue point
startPositionInMilliseconds Number: The moment during playback when the overlay should appear
endPositionInMilliseconds Number: The moment during playback when the overlay should disappear
index Number: This is a zero-based index - increment by one for each cue point
details Object: A nested JSON object that has the following overlay-specific properties:
overlayType String: Set to either "Image" or "Text"
source String: If "Image" is specified, the URL of the image to display. Set to null otherwise.
label String: If "Text" is specified, the text to display. Set to null otherwise.
trackingPixelUrls String: The URL of a tracking pixel for the event (set to null if no pixels)
adDetails Array: A two-element array representing horizontal and vertical position:
Index 0 String or Number: If a String, one of "Left", "Center", or "Right"; If a Number, a value between 0 and 1
Index 1 String or Number: If a String, one of "Top", "Middle", or "Bottom"; If a Number, a value beteen 0 and 1
Code Sample content_overlay_cue_point.txt

The JSON below shows an example of a properly formatted object for a 'Content Overlay' cue point. This specific example will result in the creation of two overlays - one text and one image. NOTE: The JSON has been altered slightly for display purposes.
[
	{
		"type": 1,
		"index": 0,
		"placement": "DURING",
		"name": "Text Overlay",
  		"startPositionInMilliseconds": 2000,
		"endPositionInMilliseconds": 5000,
		"details": {
			"overlayType": "Text",
			"label": "This is a test",
			"source": null,
			"position": ["Top", "Left"],
			"trackingPixelUrls": null
		}
	},
	{
		"type": 1,
		"index": 1,
		"placement": "DURING",
		"name": "Image Overlay",
		"startPositionInMilliseconds": 7000,
		"endPositionInMilliseconds": 9000,
		"details": {
			"overlayType": "Image",
			"label": null,
			"source": "http://media.limelight.com/images/limelight-logo-sm.png",
			"position": ["Center", "Middle"],
			"trackingPixelUrls": null
		}
	}
]


Appendix D
File Swap Caching

Information courtesy of Yahoo, http://developer.yahoo.com/php/howto-cacheRestPhp.html

File swap caching is a simple flat-file caching technique. In essence, it does nothing more than store your Web service requests in local files. When a file becomes too old (when the cache becomes "stale"), the file is deleted and replaced by a fresh Web service request. To make a Web services request using the cache, you call the caching function instead of making a direct request.

$response = request_cache($request, $cache_fullpath,$cache_timeout);

The three parameters are the actual request URL, the path to the cached version of the request, and the number of seconds before the cache becomes stale:

$request =
'http://api.video.limelight.com/rest/organizations/7fd6def47cde
4d5694f9b16bfa04c521/media.xml';
$cache_fullpath = '/mydir/ImageMad1';
$cache_timeout = 7200;

Here, we arbitrarily chose the name ImageMad1 as the cache file name corresponding to this particular Web services request. Typically, however, you would have a unique file name corresponding to each variation of Web services request. So, you would need to come up with a mapping function to map requests into file names if you want to use the caching with different variations of Web services requests.

The function request_cache does all the real work. First, it checks to see if the request has already been cached or if it has become stale.

function request_cache($url, $dest_file, $timeout) {
   if (!file_exists($dest_file) || filemtime($dest_file) < (time()-$timeout)) {

If the request has not been cached or it is stale, then we make the request and cache it:

$data = file_get_contents($url);
$tmpf = tempnam('/tmp','YWS');
$fp = fopen($tmpf,"w");
fwrite($fp, $data);
fclose($fp);
rename($tmpf, $dest_file);

Otherwise, we return the contents of the cached request:

} else {
   return file_get_contents($dest_file);

A potential problem arises if more than one user of your Web application accesses a cached file just as it is being deleted and refreshed. The statement rename($tmpf, $dest_file) appears to destroy the currently cached version of the file (if any). However, the way the Unix filesystem is implemented guarantees that any process currently reading the previous cache file will continue to read it until it closes the file. So, no process will be cut off or otherwise damaged by the rename.

See the following code sample:

http://developer.yahoo.com/php/samples/cache/cacheSWAP.txt

Appendix E
Example Header and Body of an Executed Upload Request

(A successful upload will follow a similar structure)
POST /rest/organizations/<ORG ID HERE>/media?access_key=<ACCESS KEY HERE>&expires=1262655732&signature=<SIGNATURE HERE> HTTP/1.1

Host: api.video.limelight.com

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryzn5sSWPDvmHE6QPU 

Content-Length: 3532404 



------WebKitFormBoundaryzn5sSWPDvmHE6QPU 

Content-Disposition: form-data; name="title"



My Media Title 

------WebKitFormBoundaryzn5sSWPDvmHE6QPU 

Content-Disposition: form-data; name="description" 



My Media Description 

------WebKitFormBoundaryzn5sSWPDvmHE6QPU 

Content-Disposition: form-data; name="media_file"; filename="MyVideoFile.mp4" 

Content-Type: video/mp4 



<BINARY DATA OF FILE WOULD BE HERE> 
------WebKitFormBoundaryzn5sSWPDvmHE6QPU--