Media Services API v1

Build a custom HD Network Management Interface with Akamai Utility, Domain, Stream, and Archive Management.

Learn more:

Overview

The Media Services API enables developers and architects to access and provision media streaming.

Who should use this API

The Media Services API enable you to build a customized interface.

Media Services Stream Packaging combines the best features of both Adobe® Flash® Platform–Live (HD Flash 1.0) and Media Services Live (HLS), allowing for an RTMP ingress stream and egress streams in either Adobe® HDS output, Apple® HLS output, or HD Flash 1.0 output.

Media Services: HLS Ingest allows you to stream live media to appropriate devices running iOS version 3.0 or higher

The API might not work for every user, and works based on the permissions available to the logged-in user.

Getting started

Before you use the Media Services API:

  • Review Get Started for API tools that Akamai provides.

  • Review Authorize Your Client

  • Create your Akamai API access credentials and authorizations as described in The API Identity Model.

  • Access the API using a custom hostname that is similar to: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • If you need help, provide feedback to the Akamai developer community, or contact your Akamai representative for support.

Note the following:

  • Currently, the API supports only Akamai HD for the Adobe® HTTP Dynamic Streaming and Apple® HTTP Live Streaming.

  • The API mirrors the functionality available in the Luna Control Center.

  • The event functionality works only for the stream packaging streams. It does not work for HLS ingest streams.

Resources

API summary

Operation Method Endpoint
Domains
List Domains GET /config-media-live/v1/live
Create a Domain POST /config-media-live/v1/live
Get a Domain GET /config-media-live/v1/live/{domain}
Remove a Domain DELETE /config-media-live/v1/live/{domain}
Streams
List Streams GET /config-media-live/v1/live/{domain}/stream
Create a New Stream POST /config-media-live/v1/live/{domain}/stream
Get a Stream GET /config-media-live/v1/live/{domain}/stream/{streamId}
Remove a Stream DELETE /config-media-live/v1/live/{domain}/stream/{streamId}
Modify a Stream PUT /config-media-live/v1/live/{domain}/stream/{streamId}
Events
List Events GET /config-media-live/v1/live/{domain}/stream/{streamId}/event
Get an Event GET /config-media-live/v1/live/{domain}/stream/{streamId}/event/{eventName}
Modify an Event PUT /config-media-live/v1/live/{domain}/stream/{streamId}/event/{eventName}
Remove an Event DELETE /config-media-live/v1/live/{domain}/stream/{streamId}/event/{eventName}
Versions
Create a New Version POST /config-media-live/v1/live/{domain}/version
Get a Version GET /config-media-live/v1/live/{domain}/version/{versionId}
Get Activation Status GET /config-media-live/v1/live/{domain}/version/{versionId}/activation
Activate a Version PUT /config-media-live/v1/live/{domain}/version/{versionId}/activation?environment={environment}
List Archive Locations GET /config-media-live/v1/api/live/utils/archivelocation
Utilities
List Contacts GET /config-media-live/v1/live/utils/contacts
List Countries GET /config-media-live/v1/live/utils/countries
List CP Codes GET /config-media-live/v1/live/utils/cpcode
List Delivery Formats GET /config-media-live/v1/live/utils/delivery/format
List Ingest Formats GET /config-media-live/v1/live/utils/ingest/format

List domains

Returns a list of all Universal Streaming and IDevices domains currently created on the account.

GET /config-media-live/v1/live

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<domains>
   <domain>
      <configuration-details>
         <configuration-name>hdconfig1</configuration-name>
         <hostname>hdconfig1-f.akamai-domain.net</hostname>
         <reporting-cpcode>123456</reporting-cpcode>
         <configuration-type>Universal Streaming Live</configuration-type>
         <access-control-group>ABCDEF</access-control-group>
      </configuration-details>
      <archive-configuration>
         <archive-name>hdconfig1 [HD Flash Live]</archive-name>
         <archive-cpcode>987654</archive-cpcode>
         <dvr-path>DVR</dvr-path>
         <domain-name>hdconfig1.akamai-domain.net</domain-name>
      </archive-configuration>
      <advanced-configuration>Disabled</advanced-configuration>
      <fms-backup-option>Disabled</fms-backup-option>
      <domain-versions>
         <domain-version>
            <version>1</version>
            <delivery-formats>
               <hd-flash-1.0>Enabled</hd-flash-1.0>
               <adobe-hds>Disabled</adobe-hds>
               <apple-hls>Disabled</apple-hls>
            </delivery-formats>
            <security>
               <hd-flash>
                  <token-authorization>Disabled</token-authorization>
                  <player-verification>Disabled</player-verification>
                  <geo-blocking />
               </hd-flash>
               <securehd-policy-editor>Disabled</securehd-policy-editor>
            </security>
            <advanced-configuration>
               <adobe-hds-advanced-config />
               <hd-flash-advanced-config>
                  <live-delay>14</live-delay>
               </hd-flash-advanced-config>
               <apple-hls-advanced-config />
            </advanced-configuration>
            <hd-client-support-information />
            <author>example@domain.com</author>
            <production-deployment-status>Activated</production-deployment-status>
            <activate-environment>Production</activate-environment>
         </domain-version>
      </domain-versions>
   </domain>
   <domain>
      <configuration-details>
         <configuration-name>hdconfig2</configuration-name>
         <hostname>hdconfig2-f.akamai-domain.net</hostname>
         <reporting-cpcode>678901</reporting-cpcode>
         <configuration-type>Universal Streaming Live</configuration-type>
         <access-control-group>1-ABCDEF</access-control-group>
      </configuration-details>
      <archive-configuration>
         <archive-name>hdconfig2 [HD Flash Live]</archive-name>
         <archive-cpcode>543210</archive-cpcode>
         <dvr-path>DVR</dvr-path>
         <domain-name>hdconfig2.akamai-domain.net</domain-name>
      </archive-configuration>
      <advanced-configuration>Disabled</advanced-configuration>
      <fms-backup-option>Disabled</fms-backup-option>
      <domain-versions>
         <domain-version>
            <version>1</version>
            <delivery-formats>
               <hd-flash-1.0>Enabled</hd-flash-1.0>
               <adobe-hds>Disabled</adobe-hds>
               <apple-hls>Disabled</apple-hls>
            </delivery-formats>
            <security>
               <hd-flash>
                  <token-authorization>Disabled</token-authorization>
                  <player-verification>Disabled</player-verification>
                  <geo-blocking />
               </hd-flash>
               <securehd-policy-editor>Disabled</securehd-policy-editor>
            </security>
            <advanced-configuration>
               <adobe-hds-advanced-config />
               <hd-flash-advanced-config>
                  <live-delay>14</live-delay>
               </hd-flash-advanced-config>
               <apple-hls-advanced-config />
            </advanced-configuration>
            <hd-client-support-information />
            <author>example@domain.com</author>
            <production-deployment-status>Activated</production-deployment-status>
            <activate-environment>Production</activate-environment>
         </domain-version>
      </domain-versions>
   </domain>
</domains>

Create a domain

Creates a new configuration with the assigned domain, initialized at version 1. Domains are either based on a Stream Packaging configuration or an HLS, HDS, and DASH Ingest configuration. See the Domain object for details on each type.

Before you can create new Stream Packaging streams, you must create at least one Stream Packaging configuration to establish parameters for packaged streams, such as the CP code and hostname. NetStorage is used with Live Media Services Live as your stream archive’s storage location. Therefore, you must have a NetStorage CP code set up and dedicated for use with Media Services Live, or you will be unable to create configurations. You can create as many configurations as you have CP codes available, depending on how you would like to have your streams being reported on and billed.

POST /config-media-live/v1/live

Content-Type: application/xml

Request:

<domain>
    <configuration-details>
        <configuration-name>live_test_123</configuration-name>
        <hostname>livetestapi-lh.akamai-domain.net</hostname>
        <reporting-cpcode>123456</reporting-cpcode>
        <configuration-type>Universal Streaming Live</configuration-type>
        <access-control-group>1-ABCDEF</access-control-group>
    </configuration-details>
    <archive-configuration>
        <archive-cpcode>987654</archive-cpcode>
        <archive-storage-location>EU/US preferred</archive-storage-location>
    </archive-configuration>
    <domain-versions>
        <domain-version>
            <delivery-formats>
                <hd-flash-1.0>Disabled</hd-flash-1.0>
                <adobe-hds>Enabled</adobe-hds>
                <apple-hls>Enabled</apple-hls>
            </delivery-formats>
            <advanced-configuration>
                <adobe-hds-advanced-config>
                    <hds-segment-duration>5</hds-segment-duration>
                </adobe-hds-advanced-config>
                <apple-hls-advanced-config>
                    <hls-segment-duration>10</hls-segment-duration>
                    <audio-only-stream-from-lowest-bitrate>Enabled</audio-only-stream-from-lowest-bitrate>
                </apple-hls-advanced-config>
            </advanced-configuration>
        </domain-version>
    </domain-versions>
</domain>

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response-message>
    <message>New Domain created successfully.</message>
</response-message>

Get a domain

Get the profile settings.

GET /config-media-live/v1/live/{domain}

Example: /config-media-live/v1/live/domain.com

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain..

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<domain>
   <configuration-details>
      <configuration-name>live_test_123</configuration-name>
      <hostname>livetestapi-lh.akamai-domain.net</hostname>
      <reporting-cpcode>123456</reporting-cpcode>
      <configuration-type>Universal Streaming Live</configuration-type>
      <access-control-group>1-ABCDEF</access-control-group>
   </configuration-details>
   <archive-configuration>
      <archive-name>live_test_123 [Universal Stream]</archive-name>
      <archive-cpcode>987654</archive-cpcode>
      <dvr-path>DVR</dvr-path>
      <domain-name>987654l.akamai-domain.net</domain-name>
   </archive-configuration>
   <advanced-configuration>Disabled</advanced-configuration>
   <fms-backup-option>Disabled</fms-backup-option>
   <domain-versions>
      <domain-version>
         <version>1</version>
         <delivery-formats>
            <hd-flash-1.0>Disabled</hd-flash-1.0>
            <adobe-hds>Enabled</adobe-hds>
            <apple-hls>Enabled</apple-hls>
         </delivery-formats>
         <security>
            <hd-flash>
               <geo-blocking />
            </hd-flash>
            <securehd-policy-editor>Disabled</securehd-policy-editor>
         </security>
         <advanced-configuration>
            <adobe-hds-advanced-config>
               <hds-segment-duration>5.0</hds-segment-duration>
               <hds-live-delay>10</hds-live-delay>
            </adobe-hds-advanced-config>
            <hd-flash-advanced-config />
            <apple-hls-advanced-config />
         </advanced-configuration>
         <hd-client-support-information>
            <organization-name>Akamai</organization-name>
            <support-url>http://www.akamai.com/client/streaming-support</support-url>
         </hd-client-support-information>
         <author>example@domain.com</author>
      </domain-version>
   </domain-versions>
</domain>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Make a GET request to /config-media-live/v1/live/{domainName}.

Remove a domain

Deletes a domain.

DELETE /config-media-live/v1/live/{domain}

Example: /config-media-live/v1/live/domain.com

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain..

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response-message>
    <message>Your Domain delete request was successful.</message>
</response-message>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Make a DELETE request to /config-media-live/v1/live/{domainName}.

List streams

List all the streams associated with the profile. Streams may be based on either a Stream Packaging configuration or HLS, HDS, and DASH ingest configuration. See the Stream object for details on each type.

GET /config-media-live/v1/live/{domain}/stream

Example: /config-media-live/v1/live/domain.com/stream

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<streams>
   <stream>
      <stream-id>10000</stream-id>
      <stream-type>Universal Streaming Live</stream-type>
      <stream-name>STREAM1</stream-name>
      <primary-contact-name>John Doe</primary-contact-name>
      <secondary-contact-name>Jane Doe</secondary-contact-name>
      <status>Provisioned</status>
      <notification-email>example@domain.com</notification-email>
      <encoder-settings>
         <primary-encoder-ip>250.250.250.250</primary-encoder-ip>
         <backup-encoder-ip>250.250.250.251</backup-encoder-ip>
         <username>jdoe</username>
         <password>password</password>
      </encoder-settings>
      <dvr-settings>
         <dvr>Disabled</dvr>
      </dvr-settings>
      <security-1.0>
         <token-authorization>Disabled</token-authorization>
         <player-verification>Disabled</player-verification>
      </security-1.0>
      <entrypoints>
         <entrypoint>
            <type>Backup</type>
            <domain-name>b.ep10000.i.akamaidomain.net</domain-name>
         </entrypoint>
         <entrypoint>
            <type>Primary</type>
            <domain-name>p.ep10000.i.akamaidomain.net</domain-name>
         </entrypoint>
      </entrypoints>
      <hd-flash-1.0-playback-url>http://livetestapi-lh.akamai-domain.net/[EVENT_ANGLE_BITRATE]@10000</hd-flash-1.0-playback-url>
      <hds-playback-url>http://livetestapi-lh.akamai-domain.net/z/[EVENT_ANGLE]@10000/manifest.f4m</hds-playback-url>
      <hls-playback-url>http://livetestapi-lh.akamai-domain.net/i/[EVENT_ANGLE]@10000/master.m3u8</hls-playback-url>
   </stream>
</streams>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Make a GET request to /config-media-live/v1/live/{domainName}/stream.

Create a new stream

Create a new stream, either based on a Stream Packaging configuration or an HLS, HDS, and DASH configuration. See the Stream object for details on each type.

POST /config-media-live/v1/live/{domain}/stream

Example: /config-media-live/v1/live/domain.com/stream

Content-Type: application/xml

Request:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
   <stream-type>Universal Streaming Live</stream-type>
   <stream-name>STREAM1</stream-name>
   <primary-contact-name>John Doe</primary-contact-name>
   <secondary-contact-name>Jane Doe</secondary-contact-name>
   <notification-email>jdoe@example.com</notification-email>
   <encoder-settings>
      <primary-encoder-ip>250.250.250.250</primary-encoder-ip>
      <backup-encoder-ip>250.250.250.251</backup-encoder-ip>
      <password>password</password>
   </encoder-settings>
   <dvr-settings>
      <dvr>Disabled</dvr>
   </dvr-settings>
</stream>

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
   <stream-id>10001</stream-id>
   <stream-type>Universal Streaming Live</stream-type>
   <stream-name>STREAM1</stream-name>
   <primary-contact-name>John Doe</primary-contact-name>
   <secondary-contact-name>Jane Doe</secondary-contact-name>
   <status>Not yet provisioned</status>
   <notification-email>jdoe@example.com</notification-email>
   <encoder-settings>
      <primary-encoder-ip>250.250.250.250</primary-encoder-ip>
      <backup-encoder-ip>250.250.250.251</backup-encoder-ip>
      <username>jdoe</username>
      <password>password</password>
   </encoder-settings>
   <dvr-settings>
      <dvr>Disabled</dvr>
   </dvr-settings>
   <security-1.0>
      <token-authorization>Disabled</token-authorization>
      <player-verification>Disabled</player-verification>
   </security-1.0>
   <entrypoints>
      <entrypoint>
         <type>Backup</type>
         <domain-name>b.ep10001.i.akamaidomain.net</domain-name>
      </entrypoint>
      <entrypoint>
         <type>Primary</type>
         <domain-name>p.ep10001.i.akamaidomain.net</domain-name>
      </entrypoint>
   </entrypoints>
   <hd-flash-1.0-playback-url>http://akamai-lh.akamai-domain.net/[EVENT_ANGLE_BITRATE]@10001</hd-flash-1.0-playback-url>
   <hds-playback-url>http://akamai-lh.akamai-domain.net/z/[EVENT_ANGLE]@10001/manifest.f4m</hds-playback-url>
   <hls-playback-url>http://akamai-lh.akamai-domain.net/i/[EVENT_ANGLE]@10001/master.m3u8</hls-playback-url>
</stream>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Create a Stream object.

  3. POST the object to /config-media-live/v1/live/{domainName}/stream.

Get a stream

Get the stream’s details.

GET /config-media-live/v1/live/{domain}/stream/{streamId}

Example: /config-media-live/v1/live/domain.com/stream/10000

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
      <stream-id>10000</stream-id>
      <stream-type>Universal Streaming Live</stream-type>
      <stream-name>STREAM1</stream-name>
      <primary-contact-name>John Doe</primary-contact-name>
      <secondary-contact-name>Jane Doe</secondary-contact-name>
      <status>Provisioned</status>
      <notification-email>jdoe@example.com</notification-email>
      <encoder-settings>
         <primary-encoder-ip>250.250.250.250</primary-encoder-ip>
         <backup-encoder-ip>250.250.250.251</backup-encoder-ip>
         <username>jdoe</username>
         <password>password</password>
      </encoder-settings>
      <dvr-settings>
         <dvr>Disabled</dvr>
      </dvr-settings>
      <security-1.0>
         <token-authorization>Disabled</token-authorization>
         <player-verification>Disabled</player-verification>
      </security-1.0>
      <entrypoints>
         <entrypoint>
            <type>Backup</type>
            <domain-name>b.ep10000.i.akamaidomain.net</domain-name>
         </entrypoint>
         <entrypoint>
            <type>Primary</type>
            <domain-name>p.ep10000.i.akamaidomain.net</domain-name>
         </entrypoint>
      </entrypoints>
      <hd-flash-1.0-playback-url>http://livetestapi-lh.akamai-domain.net/[EVENT_ANGLE_BITRATE]@10000</hd-flash-1.0-playback-url>
      <hds-playback-url>http://livetestapi-lh.akamai-domain.net/z/[EVENT_ANGLE]@10000/manifest.f4m</hds-playback-url>
      <hls-playback-url>http://livetestapi-lh.akamai-domain.net/i/[EVENT_ANGLE]@10000/master.m3u8</hls-playback-url>
   </stream>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Run List Streams and store the streamId from the appropriate listed object.

  3. Make a GET request to /config-media-live/v1/live/{domainName}/stream/{streamId}.

Remove a stream

Delete a stream.

DELETE /config-media-live/v1/live/{domain}/stream/{streamId}

Example: /config-media-live/v1/live/domain.com/stream/10000

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response-message>
    <message>Deleted Stream successfully.</message>
</response-message>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Run List Streams and store the streamId from the appropriate listed object.

  3. Make a DELETE request to /config-media-live/v1/live/{domainName}/stream/{streamId}.

Modify a stream

Edit an existing stream, based on either a Stream Packaging configuration or HLS, HDS, and DASH ingest configuration. See the Stream object for details on each type.

PUT /config-media-live/v1/live/{domain}/stream/{streamId}

Example: /config-media-live/v1/live/domain.com/stream/10000

Content-Type: application/xml

Request:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
   <stream-name>Sample_Stream</stream-name>
   <primary-contact-name>John Doe</primary-contact-name>
   <secondary-contact-name>Jane Doe</secondary-contact-name>
   <notification-email>jdoe@example.com</notification-email>
   <encoder-settings>
      <primary-encoder-ip>8.8.8.9</primary-encoder-ip>
      <backup-encoder-ip>8.8.8.9</backup-encoder-ip>
      <password>abc123</password>
   </encoder-settings>
   <dvr-settings>
      <dvr>Enabled</dvr>
      <dvr-window>24</dvr-window>
      </dvr-settings>
</stream>

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response:

<stream>
    <stream-id>12345</stream-id>
   <stream-type>Universal Streaming Live</stream-type>
   <stream-name>STREAM1</stream-name>
   <primary-contact-name>John Doe</primary-contact-name>
   <secondary-contact-name>Jane Doe</secondary-contact-name>
   <notification-email>jdoe@example.com</notification-email>
   <encoder-settings>
      <primary-encoder-ip>250.250.250.250</primary-encoder-ip>
      <backup-encoder-ip>250.250.250.251</backup-encoder-ip>
      <password>password</password>
   </encoder-settings>
   <dvr-settings>
      <dvr>Disabled</dvr>
   </dvr-settings>
</stream>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Run List Streams and store the streamId from the appropriate listed object.

  3. Run Get a Stream, and modify the response’s Stream object.

  4. PUT the object to /config-media-live/v1/live/{domainName}/stream/{streamId}.

List events

List the stream’s events. NOTE: The event functionality works only for the stream packaging streams. It does not work for HLS ingest streams.

GET /config-media-live/v1/live/{domain}/stream/{streamId}/event

Example: /config-media-live/v1/live/domain.com/stream/10000/event

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<event-list>
   <event>
      <stream-id>10001</stream-id>
      <event-name>news_event</event-name>
      <primary-event>
         <archive-start-time>05/19/2013 19:42:10 AM</archive-start-time>
         <archive-end-time>06/21/2013 07:37:42 PM</archive-end-time>
      </primary-event>
      <backup-event>
         <archive-start-time>05/19/2013 19:42:10 AM</archive-start-time>
         <archive-end-time>06/21/2013 07:37:42 PM</archive-end-time>
      </backup-event>
   </event>
   <event>
      <stream-id>10001</stream-id>
      <event-name>sports_event</event-name>
      <primary-event>
         <archive-start-time>05/15/2013 12:40:21 PM</archive-start-time>
         <archive-end-time>06/15/2013 12:38:00 PM</archive-end-time>
         <on-air-time>05/15/2013 12:40:21 PM</on-air-time>
         <delete-time>05/15/2013 12:40:21 PM</delete-time>
      </primary-event>
   </event>
</event-list>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Run List Streams and store the streamId from the appropriate listed object.

  3. Make a GET request to /config-media-live/v1/live/{domainName}/stream/{streamId}/event.

Get an event

Get primary and backup archive details for an event. NOTE: The event functionality works only for the stream packaging streams. It does not work for HLS ingest streams.

GET /config-media-live/v1/live/{domain}/stream/{streamId}/event/{eventName}

Example: /config-media-live/v1/live/domain.com/stream/10000/event/event_name

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
eventName String event_name Human-readable event name.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<event>
   <stream-id>10001</stream-id>
   <event-name>event_name</event-name>
   <primary-event>
      <archive-start-time>05/15/2013 12:40:21 PM</archive-start-time>
      <archive-end-time>06/15/2013 12:38:00 PM</archive-end-time>
      <on-air-time>05/15/2013 12:40:21 PM</on-air-time>
      <delete-time>05/15/2013 12:40:21 PM</delete-time>
   </primary-event>
</event>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Run List Streams and store the streamId from the appropriate listed object.

  3. Run List Events and store the eventName.

  4. Make a GET request to /config-media-live/v1/live/{domainName}/stream/{streamId}/event/{eventName}.

Modify an event

Update a steam event. You can edit an event’s on-air-time, off-air-time, and delete-time. The off-air-time element references to the On Air End field in the Luna Control Center.

NOTE: The event functionality works only for the stream packaging streams. It does not work for HLS ingest streams.

PUT /config-media-live/v1/live/{domain}/stream/{streamId}/event/{eventName}

Example: /config-media-live/v1/live/domain.com/stream/10000/event/event_name

Content-Type: application/xml

Request:

<?xml version="1.0" encoding="UTF-8"?>
<event>
   <stream-id>10001</stream-id>
   <event-name>sports_event</event-name>
   <primary-event>
      <on-air-time>05/15/2013 12:40:21 PM</on-air-time>
      <delete-time>05/15/2013 12:40:21 PM</delete-time>
   </primary-event>
</event>

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
eventName String event_name Human-readable event name.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<event>
   <stream-id>10001</stream-id>
   <event-name>sports_event</event-name>
   <primary-event>
      <on-air-time>05/15/2013 12:40:21 PM</on-air-time>
      <delete-time>05/15/2013 12:40:21 PM</delete-time>
   </primary-event>
</event>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Run List Streams and store the streamId from the appropriate listed object.

  3. Run List Events and store the eventName.

  4. Run Get an Event, then modify the Event object from the response.

  5. PUT the object to /config-media-live/v1/live/{domainName}/stream/{streamId}/event/{eventName}.

Remove an event

Delete the event details. You can delete your events at any time.

NOTE: The event functionality works only for the stream packaging streams. It does not work for HLS ingest streams.

DELETE /config-media-live/v1/live/{domain}/stream/{streamId}/event/{eventName}

Example: /config-media-live/v1/live/domain.com/stream/10000/event/event_name

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
eventName String event_name Human-readable event name.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Run List Streams and store the streamId from the appropriate listed object.

  3. Run List Events and store the eventName.

  4. Make a DELETE request to /config-media-live/v1/live/{domainName}/stream/{streamId}/event/{eventName}.

Create a new version

Create a new profile version.

POST /config-media-live/v1/live/{domain}/version

Example: /config-media-live/v1/live/domain.com/version

Content-Type: application/xml

Request:

<?xml version="1.0" encoding="UTF-8"?>
<domain-version>
   <delivery-formats>
      <hd-flash-1.0>Disabled</hd-flash-1.0>
      <adobe-hds>Disabled</adobe-hds>
      <apple-hls>Enabled</apple-hls>
   </delivery-formats>
   <security>
      <hd-flash>
         <geo-blocking />
      </hd-flash>
      <securehd-policy-editor>Disabled</securehd-policy-editor>
   </security>
   <advanced-configuration>
      <adobe-hds-advanced-config />
      <hd-flash-advanced-config />
      <apple-hls-advanced-config>
         <hls-segment-duration>10.0</hls-segment-duration>
         <hls-live-delay>10</hls-live-delay>
         <audio-only-stream-from-lowest-bitrate>Disabled</audio-only-stream-from-lowest-bitrate>
         <insert-audio-poster>Disabled</insert-audio-poster>
         <add-alternate-stream>Enabled</add-alternate-stream>
         <limit-segments-per-playlist>0</limit-segments-per-playlist>
         <serve-archive>Enabled</serve-archive>
      </apple-hls-advanced-config>
   </advanced-configuration>
</domain-version>

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response-message>
    <message>New Domain version 13 created successfully.</message>
</response-message>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Create a DomainVersion object.

  3. POST the object to /config-media-live/v1/live/{domainName}/version.

Get a version

Profile version settings.

GET /config-media-live/v1/live/{domain}/version/{versionId}

Example: /config-media-live/v1/live/domain.com/version/2

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
versionId Number 2 Domain’s incremental version number.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<domain-version>
   <version>2</version>
   <delivery-formats>
      <hd-flash-1.0>Disabled</hd-flash-1.0>
      <adobe-hds>Disabled</adobe-hds>
      <apple-hls>Enabled</apple-hls>
   </delivery-formats>
   <security>
      <hd-flash>
         <geo-blocking />
      </hd-flash>
      <securehd-policy-editor>Disabled</securehd-policy-editor>
   </security>
   <advanced-configuration>
      <adobe-hds-advanced-config />
      <hd-flash-advanced-config />
      <apple-hls-advanced-config>
         <hls-segment-duration>10.0</hls-segment-duration>
         <hls-live-delay>10</hls-live-delay>
         <audio-only-stream-from-lowest-bitrate>Disabled</audio-only-stream-from-lowest-bitrate>
         <insert-audio-poster>Disabled</insert-audio-poster>
         <add-alternate-stream>Enabled</add-alternate-stream>
         <limit-segments-per-playlist>0</limit-segments-per-playlist>
         <serve-archive>Enabled</serve-archive>
      </apple-hls-advanced-config>
   </advanced-configuration>
   <author>example@domain.com</author>
</domain-version>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Obtain versionId from the XML response that appears when you list all streaming domains.

  3. Make a GET request to /config-media-live/v1/live/{domain}/version/{versionId}.

Get activation status

Get activation status of the profile version.

GET /config-media-live/v1/live/{domain}/version/{versionId}/activation

Example: /config-media-live/v1/live/domain.com/version/2/activation

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
versionId Number 2 Domain’s incremental version number.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response-message>
   <message>Version 13 is currently NOT active on Staging.</message>
</response-message>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Obtain versionId from the XML response that appears when you list all streaming domains.

  3. Make a GET request to /config-media-live/v1/live/{domainName}/version/{versionId}/activation.

Activate a version

Activate profile version on an environment.

PUT /config-media-live/v1/live/{domain}/version/{versionId}/activation?environment={environment}

Example: /config-media-live/v1/live/domain.com/version/2/activation?environment=production

Parameter Type Sample Description
Required
domain String domain.com Unique identifier for each domain.
versionId Number 2 Domain’s incremental version number.
environment String production Specifies whether the environment is staging for testing or production to go live.

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response-message>
   <message>This version of ARL metadata has been submitted to staging network. Please note that it may take upwards of 1 hour for your configuration to take effect on our network. Contact your Akamai representative if you are having problems with your configuration.</message>
</response-message>

  1. Run List Domains and store the domainName from the appropriate listed object.

  2. Obtain versionId from the XML response that appears when you list all streaming domains.

  3. Make a PUT request to /config-media-live/v1/live/{domain}/version/{versionId}/activation?environment={environment}.

List archive locations

Returns a list of NetStorage archive locations to be used for provisioning.

GET /config-media-live/v1/api/live/utils/archivelocation

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<archive-storage-locations>
   <archive-storage-location>
      <name>Asia and US West</name>
   </archive-storage-location>
   <archive-storage-location>
      <name>Asia/Ireland</name>
   </archive-storage-location>
   <archive-storage-location>
      <name>Asia/Asia preferred</name>
   </archive-storage-location>
   <archive-storage-location>
      <name>EU/EU preferred</name>
   </archive-storage-location>
   <archive-storage-location>
      <name>US/US preferred</name>
   </archive-storage-location>
   <archive-storage-location>
      <name>EU/US preferred</name>
   </archive-storage-location>
   <archive-storage-location>
      <name>Asia/Europe</name>
   </archive-storage-location>
</archive-storage-locations>

List contacts

List an organization’s contact names who are responsible for the stream entrypoint availability.

GET /config-media-live/v1/live/utils/contacts

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<contacts>
    <contact>
        <name>John Doe</name>
    </contact>
    <contact>
        <name>Jack King</name>
    </contact>
    <contact>
        <name>Sam Adams</name>
    </contact>
</contacts>

List countries

Returns a list of countries supported when creating a configuration.

GET /config-media-live/v1/live/utils/countries

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<countries>
   <country>
      <country-code>AF</country-code>
      <country-name>AFGHANISTAN</country-name>
   </country>
   <country>
      <country-code>AL</country-code>
      <country-name>ALBANIA</country-name>
   </country>
   <country>
      <country-code>DZ</country-code>
      <country-name>ALGERIA</country-name>
   </country>
   <country>
      <country-code>AS</country-code>
      <country-name>AMERICAN SAMOA</country-name>
   </country>
   <country>
      <country-code>AD</country-code>
      <country-name>ANDORRA</country-name>
   </country>
   <country>
      <country-code>AO</country-code>
      <country-name>ANGOLA</country-name>
   </country>
   <country>
      <country-code>AI</country-code>
      <country-name>ANGUILLA</country-name>
   </country>
   <country>
      <country-code>AQ</country-code>
      <country-name>ANTARCTICA</country-name>
   </country>
   <country>
      <country-code>ZW</country-code>
      <country-name>ZIMBABWE</country-name>
   </country>
</countries>

List CP codes

Returns a list of HD Live and NetStorage CP codes available for provisioning.

GET /config-media-live/v1/live/utils/cpcode

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<available-cpcode-list>
   <reporting-cpcode-list>
      <cpcode-list>
         <cpcode>1234</cpcode>
         <cpcode-name>CPCODE-NAME</cpcode-name>
         <network-service-list>
            <USS_LIVE_SERVICE_TYPES>HD_Live::Universal_Streaming</USS_LIVE_SERVICE_TYPES>
            <USS_LIVE_SERVICE_TYPES>HD_Live::Flash</USS_LIVE_SERVICE_TYPES>
            <USS_LIVE_SERVICE_TYPES>Live_Str::HD_Flash</USS_LIVE_SERVICE_TYPES>
            <IPHONE_LIVE_SERVICE_TYPES>HD_Live::iDevices</IPHONE_LIVE_SERVICE_TYPES>
            <NS_SERVICE_TYPES>NetStorage::NetStorage</NS_SERVICE_TYPES>
            <NS_SERVICE_TYPES>ACS_HTTP</NS_SERVICE_TYPES>
            <NS_SERVICE_TYPES>ACS_FTP</NS_SERVICE_TYPES>
            <network-service>
               <service>NetStorage (Legacy)</service>
            </network-service>
            <network-service>
               <service>Universal Streaming Live (Adobe Flash)</service>
            </network-service>
         </network-service-list>
         <top-level-group-list>
            <top-level-group>1-ABCDEF</top-level-group>
         </top-level-group-list>
      </cpcode-list>
      <cpcode-list>
         <cpcode>12345</cpcode>
         <cpcode-name>CPCODE-NAME 2</cpcode-name>
         <network-service-list>
            <USS_LIVE_SERVICE_TYPES>HD_Live::Universal_Streaming</USS_LIVE_SERVICE_TYPES>
            <USS_LIVE_SERVICE_TYPES>HD_Live::Flash</USS_LIVE_SERVICE_TYPES>
            <USS_LIVE_SERVICE_TYPES>Live_Str::HD_Flash</USS_LIVE_SERVICE_TYPES>
            <IPHONE_LIVE_SERVICE_TYPES>HD_Live::iDevices</IPHONE_LIVE_SERVICE_TYPES>
            <NS_SERVICE_TYPES>NetStorage::NetStorage</NS_SERVICE_TYPES>
            <NS_SERVICE_TYPES>ACS_HTTP</NS_SERVICE_TYPES>
            <NS_SERVICE_TYPES>ACS_FTP</NS_SERVICE_TYPES>
            <network-service>
               <service>HD iPhone Live</service>
            </network-service>
         </network-service-list>
         <top-level-group-list>
            <top-level-group>1-ABCDEF</top-level-group>
         </top-level-group-list>
      </cpcode-list>
   </reporting-cpcode-list>
   <netstorage-cpcode-list />
</available-cpcode-list>

List delivery formats

Returns a list of delivery formats available for provisioning.

GET /config-media-live/v1/live/utils/delivery/format

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<delivery-format-list>
   <hd-flash-1.0 />
   <adobe-hds />
   <apple-hls />
</delivery-format-list>

List ingest formats

Returns a list of ingest formats available for provisioning.

GET /config-media-live/v1/live/utils/ingest/format

Status 200 application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<ingest-format-list>
   <hd-flash />
   <apple-idevices />
</ingest-format-list>

Data

This section describes the various data objects the Media Services API exchanges.

Domain

Domain resources enable you to view existing domain configurations, add new versions to existing domains, create new domains, and delete domains. You can also look at the activation status and activate a particular domain version in the staging and production environments.

Sample Stream Packaging Domain configuration:

<?xml version="1.0" encoding="UTF-8"?>
<domain>
    <configuration-details>
        <configuration-name>TestConfig</configuration-name>
        <hostname>hello1234-lh.akamaihd.net</hostname>
        <reporting-cpcode>125213</reporting-cpcode>
        <configuration-type>Universal Streaming Live</configuration-type>
        <access-control-group>C-SYPLCV</access-control-group>
    </configuration-details>
    <archive-configuration>
        <archive-cpcode>7338</archive-cpcode>
        <archive-storage-location>EU/US preferred</archive-storage-location>
    </archive-configuration>
    <domain-versions>
        <domain-version>
            <delivery-formats>
                <hd-flash-1.0>Disabled</hd-flash-1.0>
                <adobe-hds>Disabled</adobe-hds>
                <apple-hls>Enabled</apple-hls>
            </delivery-formats>
            <security>
                <securehd-policy-editor>Enabled</securehd-policy-editor>
                <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
            </security>
            <advanced-configuration>
                <adobe-hds-advanced-config>
                    <hds-segment-duration>5</hds-segment-duration>
                </adobe-hds-advanced-config>
                <apple-hls-advanced-config>
                    <hls-segment-duration>10</hls-segment-duration>
                    <audio-only-stream-from-lowest-bitrate>Enabled</audio-only-stream-from-lowest-bitrate>
                </apple-hls-advanced-config>
            </advanced-configuration>
        </domain-version>
    </domain-versions>
</domain>

Sample HLS, HDS, and DASH Ingest Domain configuration

<?xml version="1.0" encoding="UTF-8"?>
<domain>
    <configuration-details>
        <configuration-name>TestConfig</configuration-name>
        <hostname>hello1234-i.akamaihd.net</hostname>
        <reporting-cpcode>125226</reporting-cpcode>
        <configuration-type>HD iPhone Live</configuration-type>
        <access-control-group>C-SYPLCV</access-control-group>
    </configuration-details>
    <archive-configuration>
        <archive-cpcode>22307</archive-cpcode>
        <archive-storage-location>Asia/EU preferred</archive-storage-location>
    </archive-configuration>
    <domain-versions>
        <domain-version>
            <segment-duration>11</segment-duration>
            <security>
                <securehd-policy-editor>Enabled</securehd-policy-editor>
                <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
            </security>
            <ingest-settings>
                <encoder-ips-allow-all>Enabled</encoder-ips-allow-all>
                <encoder-ips-cidr-blocks-list>
                    <encoder-ips-cidr-block>
                        <ip-or-cidr-block>1.2.43.5</ip-or-cidr-block>
                    </encoder-ips-cidr-block>
                </encoder-ips-cidr-blocks-list>
            </ingest-settings>
        </domain-version>
    </domain-versions>
</domain>

Domain tags

Tag Type Description
Required
archive-configuration Domain.archive-configuration Contains details about the archive, such as archive CP code, archive name, domain name, and DVR pathname.
configuration-details Domain.configuration-details Contains details about the configuration, such as its name, hostname, reporting CP code, configuration type, and access control group.
domain-versions DomainVersion Specifies a set of domain versions.

Domain.archive-configuration

Contains details about the archive, such as archive CP code, archive name, domain name, and DVR pathname.

Tag Type Description
Required
archive-cpcode Number The storage group CP code associated with the configuration.
archive-name String The name of your domain archive configuration.
domain-name String The name of the domain you are connecting to.
dvr-path String The pathname of the digital video recorder.

Domain.configuration-details

Contains details about the configuration, such as its name, hostname, reporting CP code, configuration type, and access control group.

Tag Type Description
Required
access-control-group String If you have multiple contracts, specify which group you want the stream to be configured in.
configuration-name String The unique name that you give the configuration.
configuration-type String Type of configuration: Universal Streaming Live or On-Demand for Stream Packaging, or HD iPhone Live for HLS, HDS, and DASH ingest.
hostname String The hostname that you use for your domain. Ensure that this is a name that you own to prevent duplication with other users.
reporting-cpcode Number The CP code used for reporting and billing your streams.

DomainVersion

If you change the configuration’s security features, the system creates a new version of the configuration.

Sample Stream Packaging domain version configuration:

<?xml version="1.0" encoding="UTF-8"?>
<domain-version>
    <delivery-formats>
        <hd-flash-1.0>Disabled</hd-flash-1.0>
        <adobe-hds>Disabled</adobe-hds>
        <apple-hls>Enabled</apple-hls>
    </delivery-formats>
    <security>
        <securehd-policy-editor>Enabled</securehd-policy-editor>
        <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
    </security>
    <advanced-configuration>
        <adobe-hds-advanced-config>
            <hds-segment-duration>6</hds-segment-duration>
        </adobe-hds-advanced-config>
        <apple-hls-advanced-config>
            <hls-segment-duration>10</hls-segment-duration>
            <audio-only-stream-from-lowest-bitrate>Enabled</audio-only-stream-from-lowest-bitrate>
        </apple-hls-advanced-config>
    </advanced-configuration>
</domain-version>

Sample HLS, HDS, and DASH ingest domain version configuration:

<?xml version="1.0" encoding="UTF-8"?>
<domain-version>
    <segment-duration>12</segment-duration>
    <security>
        <securehd-policy-editor>Enabled</securehd-policy-editor>
        <securehd-policy-editor-default-policy>allow all (preset)</securehd-policy-editor-default-policy>
    </security>
    <ingest-settings>
        <encoder-ips-allow-all>Enabled</encoder-ips-allow-all>
    </ingest-settings>
</domain-version>

DomainVersion tags

Tag Type Description
Required
security DomainVersion.security Encapsulates security features for your configuration.
Optional
advanced-configuration DomainVersion.advanced-configuration Specifies advanced configuration for HDS and HLS. Required only for packaging streams.
delivery-formats DomainVersion.delivery-formats Enables or disables one of the following delivery formats: hd-flash-1.0 to enable FLV-delivery URLs, adobe-hds to enable Adobe HTTP Dynamic Streaming, or apple-hls to enable Apple HTTP Live Streaming. Required only for packaging streams.
ingest-settings Object Specifies the way you would like to authorize (by IP address) the encoder ability to broadcast streams associated with the configuration. Either allow all IPs with no restrictions, or add allowed encoder IP or IP Ranges (CIDR blocks), up to 50 entries allowed. Required only for passthrough streams.
segment-duration Number Specifies the length of your segment in seconds. This must be any value greater than 10. Required only for passthrough streams.

DomainVersion.advanced-configuration

Specifies advanced configuration for HDS and HLS. Required only for packaging streams.

Tag Type Description
Required
adobe-hds-advanced-config DomainVersion.advanced-configuration-hds Enables Adobe HTTP Dynamic Streaming advanced configuration.
apple-hls-advanced-config DomainVersion.advanced-configuration-hls Enables Apple HTTP Live Streaming advanced configuration.

DomainVersion.advanced-configuration-hds

Tag Type Description
Required
hds-segment-duration Number Specify a duration (between 2 and 6 seconds) for your segments/fragment. This value should be equal to, or a multiple of, your GOP interval. The default value is six seconds, which would work for one-, two-, three-, and six-second GOP sizes. If your interval is different from these values, set the appropriate value in this field. Setting this value incorrectly could cause undesirable bit rate switch downs in HDCore versions lower than 2.8.

DomainVersion.advanced-configuration-hls

Tag Type Description
Required
hls-segment-duration Number Specify a duration (between 2 and 60 seconds) for your segments/fragment.
audio-only-stream-from-lowest-bitrate Enumeration Specifies whether audio only stream from lowest bitrate is Enabled or Disabled. If it is enabled, Media Services Live automatically extracts an audio-only stream from your lowest published bit rate.

DomainVersion.delivery-formats

Enables or disables one of the following delivery formats: hd-flash-1.0 to enable FLV-delivery URLs, adobe-hds to enable Adobe HTTP Dynamic Streaming, or apple-hls to enable Apple HTTP Live Streaming. Required only for packaging streams.

Tag Type Description
Required
adobe-hds Enumeration Specifies whether Adobe HTTP Dynamic Streaming is Enabled or Disabled.
apple-hls Enumeration Specifies whether Apple Live Streaming is Enabled or Disabled.
hd-flash-1.0 Enumeration Specifies whether Flash delivery is Enabled or Disabled.

DomainVersion.security

Encapsulates security features for your configuration.

Tag Type Description
Required
securehd-policy-editor Enumeration Specifies whether the SecureHD policy editor is Enabled or Disabled. The SecureHD policy editor (SPE) is available only if this feature is included in your contract. For details about the SPE, see the SecureHD Policy Editor User Guide.
Optional
hd-flash DomainVersion.security.hd-flash Enables Flash (Media Services Live stream packaging) delivery.

DomainVersion.security.hd-flash

Tag Type Description
Required
player-verification Enumeration Specifies whether Player Verification is Enabled or Disabled. This option ensures that only player files you authorized are allowed to connect to your streams.
token-authorization Enumeration Specifies whether Token Authorization is Enabled or Disabled. Enable this option and specify the Token Authorization password. This is the shared secret between you and Media Services Live. If you enable Token Authorization for your configuration, it will apply on a URL basis to all streams using the configuration.
Optional
geo-blocking Enumeration Specifies whether Geo Blocking is Enabled or Disabled. Enables or disables blocking users based on their geographical location.

Stream

Stream resources enable you to add a new stream for an existing domain, edit a stream, and delete a stream. The Stream object encapsulates data for both packaged and passthrough stream types, including the encoder-settings tag required only for packaged stream types.

Sample HLS, HDS, and DASH stream configuration:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
    <stream-type>HD iPhone/iPad Live</stream-type>
    <stream-name>Streamhls</stream-name>
    <primary-contact-name>Jack King</primary-contact-name>
    <secondary-contact-name>Jane Doe</secondary-contact-name>
    <notification-email>jking@example.com</notification-email>
    <dvr-settings>
        <dvr>Enabled</dvr>
        <dvr-window>24</dvr-window>
    </dvr-settings>
</stream>

Sample Stream Packaging configuration, showing additional encoder-settings:

<?xml version="1.0" encoding="UTF-8"?>
<stream>
    <stream-type>Universal Streaming Live</stream-type>
    <stream-name>MyStream</stream-name>
    <primary-contact-name>Jack King</primary-contact-name>
    <secondary-contact-name>Jane Doe</secondary-contact-name>
    <notification-email>jking@example.com</notification-email>
    <encoder-settings>
        <primary-encoder-ip>1.2.3.4</primary-encoder-ip>
        <backup-encoder-ip>8.8.8.8</backup-encoder-ip>
        <password>secret</password>
    </encoder-settings>
    <dvr-settings>
        <dvr>Enabled</dvr>
        <dvr-window>36</dvr-window>
    </dvr-settings>
</stream>

Stream tags

Tag Type Description
Required
dvr-settings Stream.dvr-settings Specifies the amount of DVR time in your stream.
notification-email String The email that you send to notify the customer that the stream is successfully provisioned.
primary-contact-name String The primary person in your organization to contact regarding entry point availability issues.
secondary-contact-name String The secondary person in your organization to contact regarding entry point availability issues.
stream-id String A unique ID for your stream.
stream-name String The name for your stream. The stream name can be up to 20 characters long and can only include alphanumeric and underscore characters.
stream-type String Stream delivery type: HLS, HDS, or DASH.
Optional
encoder-settings Stream.encoder-settings Specifies the IP address of your primary and backup encoders used for the stream. Required for packaged stream types, not for passthrough streams.
entrypoints Stream.entrypoints[] Specifies the IP address of the primary and backup entrypoints that are obtaining the stream on Media Services Live.
hd-flash-1.0-playback-url String The URL that you use for playback. This is the value that you use in your client side Flash application’s connect() and play() methods.
hds-playback-url String The URL that you use for playback. This is the value that you use in your client side Flash application’s connect() and play() methods.
hls-playback-url String The URL that you use for playback.
security-1.0 Stream.security–1.0 Specifies security features (such as player verification and token authorization) for your configuration.
status String The status of the stream: Provisioned, Encoder IP Not Pingable, or Not Yet Provisioned.

Stream.dvr-settings

Specifies the amount of DVR time in your stream.

Tag Type Description
Required
dvr Enumeration The amount of DVR time in your stream. The values are: No DVR: Disables DVR and Archive/NetStorage. Use this setting only for 24x7 events. Unlimited DVR: Enables unlimited DVR time. Use this setting only for one-off events. Limited DVR: Enables you to specify the amount of DVR time. Use this setting only for 24x7 events. If your DVR time is greater than 30 minutes, archive storage on NetStorage is required.

Stream.encoder-settings

Specifies the IP address of your primary and backup encoders used for the stream. Required for packaged stream types, not for passthrough streams.

Tag Type Description
Required
backup-encoder-ip String The backup video encoder IP address.
password String Optionally, type a password for your encoder to use to access the entrypoints. Passwords can be made up of any character type, but must be no more than ten characters long. Leave this option blank if you want the system to generate a password.
primary-encoder-ip String The primary encoder IP address. Use two encoders with separate IP addresses for primary and backup for redundancy.
Optional
username String Type a user name that the encoder must use to access the entrypoints.

Stream.entrypoints[]  

Specifies the IP address of the primary and backup entrypoints that are obtaining the stream on Media Services Live.

Tag Type Description
Required
domain-name String The name of the domain in which you publish your stream.
type Enumeration The domain type: Primary or Backup.

Stream.security–1.0

Specifies security features (such as player verification and token authorization) for your configuration.

Tag Type Description
Required
player-verification Enumeration Indicates whether player verification is is Enabled or Disabled.
token-authorization Enumeration Indicates whether token authorization is is Enabled or Disabled.

Event

The Event resources enable you to specify details about your streaming event.

Sample event configuration:

<?xml version="1.0" encoding="UTF-8"?>
<event>
    <stream-id>10005</stream-id>
    <event-name>news_event</event-name>
    <primary-event>
        <archive-start-time>05/14/2015 19:42:10 AM</archive-start-time>
        <archive-end-time>06/14/2015 07:37:42 PM</archive-end-time>
    </primary-event>
    <backup-event>
        <archive-start-time>05/13/2015 19:42:10 AM</archive-start-time>
        <archive-end-time>06/15/2015 07:37:42 PM</archive-end-time>
    </backup-event>
</event>

Event tags

Tag Type Description
Required
backup-event Event.* The backup event start date and time and end date and time.
event-name String The name of the event.
primary-event Event.* The primary event start date and time and end date and time.
stream-id String The numerical stream ID.

Event.*

Specifies the primary or backup event start and end time.

Tag Type Description
Required
archive-end-time String The date and time when the archive must end.
archive-start-time String The date and time when the archive must end.

Archive

Archive management resources enable you to view and update events for a stream.

Sample archive configuration:

<?xml version="1.0" encoding="UTF-8"?>
<archive-storage-locations>
    <archive-storage-location>
        <name>EU/EU preferred</name>
    </archive-storage-location>
</archive-storage-locations>

Archive tags

Tag Type Description
Required
name String Name of the archived storage location.

Contact

Use the contact tags to configure the name of the people responsible for the stream entrypoints.

Sample Contact configuration:

<?xml version="1.0" encoding="UTF-8"?>
<contacts>
    <contact>
        <name>John Doe</name>
    </contact>
</contacts>

Contact tags

Tag Type Description
Required
name String The name of the person responsible for the stream entrypoint’s availability.

Country

Use the country tag to specify the Country name and code.

Sample country configuration:

<?xml version="1.0" encoding="UTF-8"?>
<countries>
    <country>
        <country-code>AL</country-code>
        <country-name>ALBANIA</country-name>
    </country>
</countries>

Country tags

Tag Type Description
Required
country-code String The two letter country code.
country-name String The country name.

CPCode

CP code resources enable you to specify the Content Provider code associated with the stream.A Content Provider code is necessary to track all web traffic handled by Akamai servers. It is supplied to you when you purchase a product, and you need it to activate any associated properties. You can generate additional CP codes, typically to implement more detailed billing and reporting functions and assign to custom properties.

Sample CP code configuration:

<?xml version="1.0" encoding="UTF-8"?>
<available-cpcode-list>
    <reporting-cpcode-list>
        <cpcode-list>
            <cpcode>567891</cpcode>
            <cpcode-name>MYCPCODE - Media Services Live</cpcode-name>
            <network-service-list>
                <USS_LIVE_SERVICE_TYPES>HD_Live::Universal_Streaming</USS_LIVE_SERVICE_TYPES>
                <network-service>
                    <service>Universal Streaming Live (Adobe Flash)</service>
                </network-service>
            </network-service-list>
            <top-level-group-list>
                <top-level-group>1-ABCDEF</top-level-group>
            </top-level-group-list>
        </cpcode-list>
    </reporting-cpcode-list>
</available-cpcode-list>

CPCode tags

Tag Type Description
Required
cpcode Number The Content Provider code associated with the stream.
cpcode-name String The Content Provider code name associated with the stream.
network-service-list CPCode.network-service-list The network service list.
top-level-group-list Object The top-level CP code directory list.

CPCode.network-service-list

Tag Type Description
Required
IPHONE_LIVE_SERVICE_TYPES String The HLS service types.
NS_SERVICE_TYPES Array The Net Storage service types.
USS_LIVE_SERVICE_TYPES String The stream packaging service types.
network-service String The CP code network service types.

CPCode.network-service-list.network-service

Tag Type Description
Required
service String The CP code service: uss_live_service_types for Stream Packaging, iphone_live_service_type for Media Services Live, netstorage_services for Net Storage services.

Errors

This section details the Media Services API error response formats, lists specific error messages you might encounter, and the API’s complete range of HTTP response codes.

Error responses

This API’s error responses conform to the JSON problem specification. The following shows a typical Media Services API error response:

{
    "type": "https://problems.luna.akamaiapis.net/-/resource-impl/forward-origin-error",
    "title": "Bad Request",
    "status": 400,
    "instance": "https://akab-we62bufgzvfmaj5f-3rtepafiil5ulp4p.luna.akamaiapis.net/config-media-live/v1/live/abcd-lh.akamaihd.n1et/stream",
    "method": "GET",
    "serverIp": "184.1.2.3",
    "clientIp": "60.2.3.4",
    "requestId": "14d35d3a",
    "requestTime": "2016-04-19T13:04:20Z"
}

Errors when adding a domain

The following errors might appear if the API fails while adding a domain:

  • Empty Configuration Name.
  • Maximum Configuration Name: (30)
  • HostName must be specified.
  • Reporting CPCode is required.
  • Version details missing.
  • CPCode not available for creating domain configuration.
  • User does not have edit permission for CPCode.
  • Hostname should not be more than 18 characters.
  • Archive configuration missing.
  • Multiple archive feature currently not supported.
  • Storage Group CPCode missing.
  • No CPCodes available to create a storage group.
  • The archive CPCode is not available.
  • Hostname format is not valid.

Errors when creating a new domain version

The following errors might appear if the API fails while creating a new domain version:

  • Domain cannot be empty.
  • Please specify only a single activate environment either staging or production.
  • Invalid activate environment. Please specify either staging or production.
  • Domain has been converted to ‘advanced configuration’. You cannot add new versions to this domain.

Errors when activating domain versions

The following errors might appear if the API fails while activating a domain version and getting the version status:

  • Invalid version ID
  • Please specify a valid environment.
  • Environment must be either production or staging.

Errors when deleting domains

The following errors might appear if the API fails while deleting a domain:

  • Domain cannot be empty.
  • Domain Name must be specified.

Errors when creating streams

The following errors might appear if the API fails while creating a stream:

  • Domain Name must be specified.
  • For creating new stream, please do not specify a stream ID.
  • Stream Format does not match with domain supported stream format.
  • No configuration found for specified domain.
  • User does not have permission to create IPhone streams.
  • User does not have permission to create Flash streams.
  • Unable to find Storage group from configuration.
  • The stream end date should be later than today.
  • Please specify stream end date between tomorrow and 5 years from today.
  • Please specify a valid value for DVR window.
  • DVR window should be between 5 and 30 minutes.
  • DVR window should be less than 30 minutes when Netstorage is disabled.
  • Please enter stream name.
  • Please re-enter stream name in the valid format.
  • Please do not specify the username field.
  • For IPhone streams please do not specify the primary or backup encoder IP
  • Please specify a valid value for Segment Interval (Integer no less than 2).
  • Please enter a valid primary encoder IP. This IP is restricted.
  • Please enter a valid secondary encoder IP. This IP is restricted.
  • Please specify a password in encoder settings.
  • Please specify a primary contact.
  • Unable to find Primary Contact. Please check your input.
  • Please specify a secondary contact
  • Unable to find Secondary Contact. Please check your input.
  • Please specify a Notification Email.
  • Invalid Notification email format. Please specify a valid email address.

Errors when editing or deleting streams

The following error might appear if the API fails while editing or deleting a stream:

  • Incorrect Stream ID

HTTP status codes

The API produces the following set of HTTP status codes for both success and failure scenarios.

Code Description
200 Request OK
201 Resource Created
400 Bad Request
401 Unauthorized Request
402 Failed Request
403 Forbidden
404 Resource not found
405 Method not allowed
415 Unsupported Media Type
422 Unprocessable entity
429 Too many requests
500 Server Error

Last modified: 12/13/2016