loading

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 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), enabling 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 lets you stream live media to appropriate devices running iOS version 3.0 or higher

Who should use this API

Developers and architects can use this API to access and provision media streaming using customized interfaces.

Getting started

To configure the Media Services API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Media Services, and set the access level to READ-WRITE.

  • 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 Akamai Control Center.

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

Dual data formats

Media Services Live Stream Packaging and HLS/HDS/DASH ingest APIs support only XML. However, MSL RTMP Streaming supports JSON.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

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}
Modify a stream PUT /config-media-live/v1/live/{domain}/stream/{streamId}
Remove a stream DELETE /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{?environment}
Activate a version PUT /config-media-live/v1/live/{domain}/version/{versionId}/activation{?environment}
Utilities  
List archive locations GET /config-media-live/v1/live/utils/archivelocation
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
RTMP Streaming  
List configurations GET /config-media-live/v1/live/rtmp/configuration
Create a configuration POST /config-media-live/v1/live/rtmp/configuration
Get a configuration GET /config-media-live/v1/live/rtmp/configuration/{cpcode}
Update a configuration PUT /config-media-live/v1/live/rtmp/configuration/{cpcode}
Delete a configuration DELETE /config-media-live/v1/live/rtmp/configuration/{cpcode}
List RTMP CP codes GET /config-media-live/v1/live/rtmp/cpcode
List RTMP contacts GET /config-media-live/v1/live/rtmp/contacts
List RTMP streams GET /config-media-live/v1/live/rtmp/stream
Create an RTMP stream POST /config-media-live/v1/live/rtmp/stream
Get an RTMP stream GET /config-media-live/v1/live/rtmp/stream/{streamId}
Update an RTMP stream PUT /config-media-live/v1/live/rtmp/stream/{streamId}
Delete an RTMP stream DELETE /config-media-live/v1/live/rtmp/stream/{streamId}
List storage groups GET /config-media-live/v1/live/rtmp/storage-group

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 Body:

<?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 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 might 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 Body:

<domain>
    <configuration-details>
        <configuration-name>manch_123</configuration-name>
        <hostname>open736833-lh.edgeflash.qa.akamai.com</hostname>
        <reporting-cpcode>736833</reporting-cpcode>
        <configuration-type>Universal Streaming Live</configuration-type>
        <access-control-group>C-C8KEVT</access-control-group>
    </configuration-details>
    <archive-configuration>
        <archive-cpcode>736847</archive-cpcode>
        <archive-zones>
            <archive-zone>
                <zone>asia</zone>
            </archive-zone>
        </archive-zones>
    </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>
                    <hds-live-delay>2</hds-live-delay>
                </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>
            <edge-hostname-map>w17</edge-hostname-map>
        </domain-version>
    </domain-versions>
</domain>

Status 200 application/xml

Response Body:

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

  1. Build a new Domain object.

  2. POST the object to /config-media-live/v1/live.

  3. The response produces an Domain object.

Get a domain

Get the profile settings.

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

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

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

Status 200 application/xml

Response Body:

<?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}

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

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

Status 200 application/xml

Response Body:

<?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

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

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

Status 200 application/xml

Response Body:

<?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>test.user.1</primary-contact-name>
      <secondary-contact-name>test.user.2</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>username</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 hostname from the appropriate listed object.

  2. Make a GET request to /config-media-live/v1/live/{hostname}/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

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

Content-Type: application/xml

Request Body:

<?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
URL parameters
domain String domain.com Unique identifier for each domain.

Status 200 application/xml

Response Body:

<?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>Stream User1</primary-contact-name>
   <secondary-contact-name>Stream User2</secondary-contact-name>
   <status>Not yet 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>12345</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 hostname from the appropriate listed object.

  2. Create a Stream object.

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

Get a stream

Get the stream’s details.

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

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

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

Status 200 application/xml

Response Body:

<?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>test.user.1</primary-contact-name>
      <secondary-contact-name>test.user.2</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>username</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 hostname 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/{hostname}/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}

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

Content-Type: application/xml

Request Body:

<?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
URL parameters
domain String domain.com Unique identifier for each domain.
streamId Number 10000 Unique identifier for each stream.

Status 200 application/xml

Response Body:

<stream>
    <stream-id>12345</stream-id>
   <stream-type>Universal Streaming Live</stream-type>
   <stream-name>STREAM1</stream-name>
   <primary-contact-name>Stream User1</primary-contact-name>
   <secondary-contact-name>Stream User2</secondary-contact-name>
   <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>
      <password>password</password>
   </encoder-settings>
   <dvr-settings>
      <dvr>Disabled</dvr>
   </dvr-settings>
</stream>

  1. Run List domains and store the hostname 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/{hostname}/stream/{streamId}.

Remove a stream

Delete a stream.

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

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

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

Status 200 application/xml

Response Body:

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

  1. Run List domains and store the hostname 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/{hostname}/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

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

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

Status 200 application/xml

Response Body:

<?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 hostname 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/{hostname}/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}

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

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

Status 200 application/xml

Response Body:

<?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 hostname 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/{hostname}/stream/{streamId}/event/{eventName}.

Modify an event

Update a stream event. The off-air-time element corresponds to the On Air End field in 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}

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

Content-Type: application/xml

Request Body:

<?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
URL parameters
domain String domain.com Unique identifier for each domain.
streamId Number 10000 Unique identifier for each stream.
eventName String event_name Human-readable event name.

Status 200 application/xml

Response Body:

<?xml version="1.0" encoding="UTF-8"?>
<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>

  1. Run List domains and store the hostname 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/{hostname}/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}

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

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

Status 200 application/xml

Response Body:

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

  1. Run List domains and store the hostname 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/{hostname}/stream/{streamId}/event/{eventName}.

Create a new version

Create a new profile version.

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

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

Content-Type: application/xml

Request Body:

<?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
URL parameters
domain String domain.com Unique identifier for each domain.

Status 200 application/xml

Response Body:

<?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 hostname from the appropriate listed object.

  2. Create a DomainVersion object.

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

Get a version

Profile version settings.

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

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

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

Status 200 application/xml

Response Body:

<?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 hostname 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/{hostname}/version/{versionId}.

Get activation status

Get activation status of the profile version.

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

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

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

Status 200 application/xml

Response Body:

<?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 hostname from the appropriate listed object.

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

  3. Set the value of environment to production (to go live) or staging (for testing).

  4. Make a GET request to /config-media-live/v1/live/{hostname}/version/{versionId}/activation{?environment}.

Activate a version

Activate profile version on an environment.

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

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

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

Status 200 application/xml

Response Body:

<?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}.

List archive locations

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

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

Status 200 application/xml

Response Body:

<?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>Hong Kong/Malaysia</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 Body:

<contacts>
   <contact>
      <name>NAME- 1</name>
   </contact>
   <contact>
      <name>NAME -2</name>
   </contact>
   <contact>
      <name>Name -3</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 Body:

<?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 CPCodes available to be used for provisioning.

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

Status 200 application/xml

Response Body:

<?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 Body:

<?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 Body:

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

List configurations

Retrieves a set of all RTMP configurations available to you.

GET /config-media-live/v1/live/rtmp/configuration

Status 200 application/json

Object type: Configuration

Download schema: getRTMPConfigurationsListDTO.json

Response Body:

{
    "configurations": [
        {
            "swfLocation": "123456.download.example.com/123456/",
            "isSecure": false,
            "isHDConfig": false,
            "name": "testConfig",
            "cpcode": 654321,
            "usePreSpreadSerial": true,
            "hostAliases": [
                "default.host.net (default)"
            ],
            "isRtmpe": true,
            "isMbr": true
        }
    ]
}

Create a configuration

Provisions a new RTMP configuration.

POST /config-media-live/v1/live/rtmp/configuration

Content-Type: application/json

Object type: Configuration

Download schema: postRTMPConfigurationDTO.json

Request Body:

{
    "name": "testConfig123",
    "cpcode": 12345,
    "usePreSpreadSerial": true,
    "hostAliases": [
        "testHost1",
        "testHost2",
        "testHost3"
    ],
    "isRtmpe": false,
    "isMbr": false,
    "isSecure": true,
    "swfPath": "temp",
    "swfLocation": "123456.download.example.com/123456/",
    "authProfiles": [
        {
            "eTokenType": "NEW",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "name": "temp",
            "password": "abc123",
            "cidr": "1.2.3.4/32"
        }
    ]
}

Status 201

Headers:

Location: /configuration/123

  1. Build a Configuration object.

  2. POST the object to /config-media-live/v1/live/rtmp/configuration.

Get a configuration

Retrieves detailed information about the requested RTMP configuration.

GET /config-media-live/v1/live/rtmp/configuration/{cpcode}

Sample: /config-media-live/v1/live/rtmp/configuration/123456

Parameter Type Sample Description
URL parameters
cpcode Integer 123456 Unique identifier for each RTMP configuration.

Status 200 application/json

Object type: Configuration

Download schema: getRTMPConfigurationDTO.json

Response Body:

{
    "name": "samplename",
    "cpcode": 12345,
    "isSecure": true,
    "authProfiles": [
        {
            "name": "temp",
            "password": "abc123",
            "eTokenType": "NO_CHANGE",
            "requireIP": true,
            "requirePath": false,
            "requirePayload": true,
            "cidr": "1.2.3.4-4.5.6.7"
        }
    ],
    "usePreSpreadSerial": true,
    "hostAliases": [
        "default.hostname.net (default)",
        "testHost1.com",
        "testHost2.com"
    ],
    "swfPath": "check123",
    "swfLocation": "654321.download.example.com/654321/",
    "isRtmpe": true,
    "isMbr": true
}

  1. Run List domains and store the cpcode from the appropriate listed object.

  2. Make a GET request to /config-media-live/v1/live/rtmp/configuration/{cpcode}.

Update a configuration

Updates certain fields of an existing RTMP configuration.

PUT /config-media-live/v1/live/rtmp/configuration/{cpcode}

Sample: /config-media-live/v1/live/rtmp/configuration/123456

Content-Type: application/json

Object type: Configuration

Download schema: putRTMPConfigurationDTO.json

Request Body:

{
    "name": "sampleConfig",
    "cpcode": 1234,
    "usePreSpreadSerial": true,
    "isRtmpe": true,
    "isMbr": true,
    "isSecure": true,
    "hostAliases": [
        "testHost1",
        "testHost2"
    ],
    "swfPath": "check123",
    "swfLocation": "654321.download.example.com/654321/",
    "authProfiles": [
        {
            "name": "tempAuthProf",
            "password": "abc123",
            "eTokenType": "NO_CHANGE",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "cidr": "1.2.3.4-1.2.3.4"
        }
    ]
}
Parameter Type Sample Description
URL parameters
cpcode Integer 123456 Unique identifier for each RTMP configuration.

Status 200

  1. Run List configurations and pick configuration to modify.

  2. Get a specific configuration Get a configuration and pick a CP code to modify.

  3. Modify the CP code.

  4. PUT the object to /config-media-live/v1/live/rtmp/configuration/{cpcode}. Use the cpcode that Akamai supplied to you.

Delete a configuration

Deletes an existing RTMP configuration.

DELETE /config-media-live/v1/live/rtmp/configuration/{cpcode}

Sample: /config-media-live/v1/live/rtmp/configuration/123456

Parameter Type Sample Description
URL parameters
cpcode Integer 123456 Unique identifier for each RTMP configuration.

Status 200

  1. Run List domains and store the cpcode from the appropriate listed object.

  2. Make a DELETE request to /config-media-live/v1/live/rtmp/configuration/{cpcode}.

List RTMP CP codes

Obtains available CP codes for new RTMP configurations.

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

Status 200 application/json

Object type: CpCode

Download schema: RTMPCpcodesDTO.json

Response Body:

{
    "used": [
        {
            "cpcode": 12345,
            "name": "cpcode1"
        },
        {
            "cpcode": 54321,
            "name": "cpcode2"
        },
        {
            "cpcode": 67890,
            "name": "cpcode3"
        }
    ],
    "unused": [
        {
            "cpcode": 24680,
            "name": "cpcode4"
        },
        {
            "cpcode": 13579,
            "name": "cpcode5"
        },
        {
            "cpcode": 21345,
            "name": "cpcode6"
        }
    ]
}

List RTMP contacts

Obtains a list of people in your organization to contact regarding entry point availability issues.

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

Status 200 application/json

Download schema: RTMPContactsDTO.json

Response Body:

{
    "contact": [
        {
            "name": "User1"
        },
        {
            "name": "User2"
        }
    ]
}

List RTMP streams

Retrieves a list of all RTMP streams available to a user.

GET /config-media-live/v1/live/rtmp/stream

Status 200 application/json

Object type: Stream

Download schema: getRTMPStreamsListDTO.json

Response Body:

{
    "streams": [
        {
            "isSecure": false,
            "createdDate": "2015-02-26T01:06:21.000Z",
            "primaryEntrypoint": "rtmp://p.ep123456.i.exampleentrypoint.net/EntryPoint",
            "backupEntrypoint": "rtmp://b.ep123456.i.exampleentrypoint.net/EntryPoint",
            "playbackSettings": [
                {
                    "connectionUrl": "rtmp://exampleConnectionUrl.net/live/",
                    "playbackUrl": "testStream1@123456"
                }
            ],
            "status": "Provisioned",
            "blocked": false,
            "id": 123456,
            "cpcode": 654321,
            "name": "testStream1",
            "dynamic": true,
            "encoder": {
                "primaryEncoderIP": "12.34.56.78",
                "backupEncoderIP": "78.56.34.12",
                "password": "test1"
            },
            "contactDetails": {
                "primary": "Test User",
                "secondary": "Test User"
            }
        }
    ]
}

Create an RTMP stream

Provisions a new RTMP stream.

POST /config-media-live/v1/live/rtmp/stream

Content-Type: application/json

Object type: Stream

Download schema: postRTMPStreamDTO.json

Request Body:

{
    "cpcode": 12345,
    "name": "testStream",
    "dynamic": true,
    "encoder": {
        "primaryEncoderIP": "1.1.1.1",
        "backupEncoderIP": "1.1.1.1",
        "password": "test123"
    },
    "contactDetails": {
        "primary": "User test",
        "secondary": "User test"
    },
    "email": "abc@example.com",
    "isSecure": true,
    "streamEndDate": "2019-02-27T18:30:00.000Z",
    "authProfiles": [
        {
            "eTokenType": "NEW",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "name": "temp",
            "password": "abc123",
            "cidr": "1.2.3.4-1.2.3.4"
        }
    ]
}

Status 202

Headers:

Location: /stream/123

  1. Create a Stream object.

  2. POST the object to /config-media-live/v1/live/rtmp/stream.

Get an RTMP stream

Retrieves detailed information about the requested RTMP stream.

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

Sample: /config-media-live/v1/live/rtmp/stream/12345

Parameter Type Sample Description
URL parameters
streamId Integer 12345 Unique identifier for each stream.

Status 200 application/json

Object type: Stream

Download schema: getRTMPStreamDTO.json

Response Body:

{
    "isSecure": true,
    "createdDate": "2018-10-15T10:18:23.000Z",
    "primaryEntrypoint": "rtmp://p.ep123456.i.exampleentrypoint.net/EntryPoint",
    "backupEntrypoint": "rtmp://b.ep123456.i.exampleentrypoint.net/EntryPoint",
    "playbackSettings": [
        {
            "connectionUrl": "rtmp://exampleConnectionUrl.net/live/",
            "playbackUrl": "StreamTemp123@s123456"
        }
    ],
    "status": "Not Yet Provisioned",
    "email": "user@example.com",
    "blocked": false,
    "id": 123456,
    "cpcode": 65432,
    "name": "StreamTemp123",
    "dynamic": true,
    "encoder": {
        "primaryEncoderIP": "1.1.1.1",
        "backupEncoderIP": "198.199.26.36",
        "password": "abc123"
    },
    "streamEndDate": "2019-03-30T18:30:00.000Z",
    "contactDetails": {
        "primary": "Jack King",
        "secondary": "Aditya Sharma"
    },
    "authProfiles": [
        {
            "name": "abctemp",
            "password": "abc123",
            "eTokenType": "NO_CHANGE",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "cidr": "1.2.3.4/12"
        }
    ]
}

  1. Run List streams and store the streamId from the appropriate listed object.

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

Update an RTMP stream

Modifies the specified RTMP stream.

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

Sample: /config-media-live/v1/live/rtmp/stream/12345

Content-Type: application/json

Object type: Stream

Download schema: putRTMPStreamDTO.json

Request Body:

{
    "cpcode": 123456,
    "name": "TempStream",
    "dynamic": true,
    "email": "abc@example.com",
    "streamEndDate": "2019-03-30T18:30:00.000Z",
    "encoder": {
        "password": "abc123",
        "primaryEncoderIP": "1.1.1.1",
        "backupEncoderIP": "1.1.1.1"
    },
    "contactDetails": {
        "primary": "user test",
        "secondary": "user test"
    },
    "authProfiles": [
        {
            "name": "abctemp",
            "password": "abc123",
            "eTokenType": "NO_CHANGE",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "cidr": "1.2.3.4/12"
        }
    ]
}
Parameter Type Sample Description
URL parameters
streamId Integer 12345 Unique identifier for each stream.

Status 200

  1. Run List streams and store the streamId from the appropriate listed object.

  2. Run the Get an RTMP stream operation.

  3. Modify the response’s Stream object.

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

Delete an RTMP stream

Deletes the specified RTMP stream.

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

Sample: /config-media-live/v1/live/rtmp/stream/12345

Parameter Type Sample Description
URL parameters
streamId Integer 12345 Unique identifier for each stream.

Status 200

  1. Run List streams and store the streamId from the appropriate listed object.

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

List storage groups

Provides a list of storage groups.

GET /config-media-live/v1/live/rtmp/storage-group

Status 200 application/json

Object type: StorageGroup

Download schema: RTMPStorageGroupDTO.json

Response Body:

[
    {
        "cpcode": 123456,
        "downloadDomain": "123456.download.example.com",
        "location": "123456.download.example.com/123456/"
    },
    {
        "cpcode": 654321,
        "downloadDomain": "654321.download.example.com",
        "location": "654321.download.example.com/654321/"
    },
    {
        "cpcode": 246813,
        "downloadDomain": "246813.download.example.com",
        "location": "246813.download.example.com/246813/"
    }
]

XML Data

This section describes the XML-based data objects the Media Services API exchanges. See JSON Data for information on the JSON-based data the API’s RTMP operations exchange.

Media Services Live Stream Packaging and HLS/HDS/DASH ingest APIs support only XML. However, MSL RTMP Streaming supports JSON.

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 Enabled or Disabled.
token-authorization Enumeration Indicates whether token authorization is Enabled or Disabled.

Event

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 NetStorage 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 NetStorage services.

JSON Data

This section provides details on the JSON-based data types the API’s RTMP operations exchange. See XML Data for information on the XML-based data the API’s other operations exchange.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

✓ Member is required in requests, or always present in responses, even if its value is empty or null.
○ Member is optional, and may be omitted in some cases.

Configuration

Before you can create new streams, you must create at least one RTMP configuration to establish parameters for RTMP streams, such as the CP code and hostname. NetStorage is used with 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 reported and billed.

Download schema: postRTMPConfigurationDTO.json

Sample POST request:

{
    "name": "testConfig123",
    "cpcode": 12345,
    "usePreSpreadSerial": true,
    "hostAliases": [
        "testHost1",
        "testHost2",
        "testHost3"
    ],
    "isRtmpe": false,
    "isMbr": false,
    "isSecure": true,
    "swfPath": "temp",
    "swfLocation": "123456.download.example.com/123456/",
    "authProfiles": [
        {
            "eTokenType": "NEW",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "name": "temp",
            "password": "abc123",
            "cidr": "1.2.3.4/32"
        }
    ]
}

Configuration members

Member Type Required Description
Configuration: Before you can create new streams, you must create at least one RTMP configuration to establish parameters for RTMP streams, such as the CP code and hostname. NetStorage is used with 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 reported and billed.
authProfiles Configuration.authProfiles[] ○ Authorization profiles that can access the configuration or the stream.
cpcode Integer ✓ The Content Provider code name that you use to provision your RTMP configuration.
createdDate String ○ Read-only. The date and time when the RTMP configuration was created. It’s an ISO 8601 timestamp.
hostAliases Array ✓ You link these aliases to the default hostname. To stream content using these hostnames, create them on your DNS server as CNAME records pointing to the default hostname.
isHDConfig Boolean ○ When enabled, it assigns the stream packaging type to your configuration.
isMbr Boolean ✓ Enables the Dynamic/MBR (multiple bit rate) feature for your stream.
isRtmpe Boolean ✓ Enables use of RTMPE/RTMPTE protocols. This denies all other protocols (RTMP/RTMPT).
isSecure Boolean ✓ Enables secure streaming, which ensures that only authorized users can access or download your media content.
name String ✓ The unique name that you create for your configuration.
swfLocation String ○ NetStorage location to which you upload your authorized SWF files. Streaming uses these to verify the validity of the SWF files requesting videos associated with the Flash configuration.
swfPath String ○ NetStorage location to which you upload your authorized SWF files. The streaming process uses these to validate the SWF files requesting videos in the Flash configuration.
usePreSpreadSerial Boolean ✓ Specify whether to use the standard protocol port for streaming.
Configuration.authProfiles[]: Authorization profiles that can access the configuration or the stream.
cidr String ✓ This option can be used if you would like to restrict viewing of a stream to end users in a certain IP range or CIDR block.
eTokenType Enumeration ✓ Specifies whether to create a new E-Token (NEW), keep the same E-Token (NO_CHANGE), or disable (DISABLE) an existing E-token. Enabling E-type token requires inclusion of a Rijndael key in your token. For details about E-tokens, see the Secure Streaming Integration Guide.
name String ✓ The unique name provided to the authorization profile, not more than 30 characters. If the auth profile names are duplicated then you can’t edit the profiles.
password String ✓ Password for each auth profile. Passwords can be made up of any character type, but must be no more than 10 characters.
requireIP Boolean ✓ Specify whether the authorization profile includes IP addresses in all tokens.
requirePath Boolean ✓ The path value in the token ties the token to a particular stream or piece of content. By removing the path from the token will reduce the security of the token.
requirePayload Boolean ✓ Enabling this value will reject any token that does not include a payload field.

StorageGroup

You can keep your content for distribution in a storage group.

Download schema: RTMPStorageGroupDTO.json

Sample GET response:

[
    {
        "cpcode": 123456,
        "downloadDomain": "123456.download.example.com",
        "location": "123456.download.example.com/123456/"
    },
    {
        "cpcode": 654321,
        "downloadDomain": "654321.download.example.com",
        "location": "654321.download.example.com/654321/"
    },
    {
        "cpcode": 246813,
        "downloadDomain": "246813.download.example.com",
        "location": "246813.download.example.com/246813/"
    }
]

StorageGroup members

Member Type Description
StorageGroup: You can keep your content for distribution in a storage group.
cpcode Integer The Content Provider code that Akamai supplies for RTMP streaming. You use CP codes in the Akamai system to track and report delivered services.
downloadDomain String The hostname of the machine in which you download the storage group and manage its content.
location String The storage group hostname and URL path.

Stream

Creates a new RTMP stream.

Download schema: getRTMPStreamDTO.json

Sample PUT request:

{
    "cpcode": 123456,
    "name": "TempStream",
    "dynamic": true,
    "email": "abc@example.com",
    "streamEndDate": "2019-03-30T18:30:00.000Z",
    "encoder": {
        "password": "abc123",
        "primaryEncoderIP": "1.1.1.1",
        "backupEncoderIP": "1.1.1.1"
    },
    "contactDetails": {
        "primary": "user test",
        "secondary": "user test"
    },
    "authProfiles": [
        {
            "name": "abctemp",
            "password": "abc123",
            "eTokenType": "NO_CHANGE",
            "requireIP": true,
            "requirePath": true,
            "requirePayload": true,
            "cidr": "1.2.3.4/12"
        }
    ]
}

Stream members

Member Type Required Description
Stream: Creates a new RTMP stream.
authProfiles Stream.authProfiles[] ✓ Authorization profiles that can access the configuration or the stream.
backupEntrypoint String ○ Specifies the RTMP URL of the backup entry point that obtain the stream in Media Services Live. You can use the backup entry point when the primary entry point fails.
blocked Boolean ○ Specify whether the stream is blocked or unblocked. Enable blocked to prevent end users from accessing the stream.
contactDetails Stream.contactDetails ✓ Provides information about the people in your organization responsible for entry point availability issues.
cpcode Integer ✓ The Content Provider code that you assign to the stream.
createdDate String ○ Read-only. The date and time when your stream is created. It’s an ISO 8601 timestamp.
dynamic Boolean ✓ Specifies if the stream can publish multiple bitrate streams.
email String ✓ The email address to notify that the stream is successfully provisioned.
encoder Stream.encoder ✓ Specifies the type of encoder: Name Server or manual configuration. For manual configurations, specify the IP address of the primary and backup encoders used for the stream.
id Integer ○ Read-only. A unique ID for your stream.
isSecure Boolean ○ Specify whether secure profiles are enabled on the stream.
name String ✓ The name of your stream. The stream name can be up to 100 characters long and can only include alphanumeric and underscore characters.
playbackSettings Stream.playbackSettings[] ○ Information about how to play the stream.
primaryEntrypoint String ○ Specifies the URL of the primary entry point that obtain the stream in Media Services Live.
status String ○ The status of the stream: Provisioned or Not Yet Provisioned.
streamEndDate String ✓ The date and time at which you expect your streaming event to end. It’s an ISO 8601 timestamp.
Stream.authProfiles[]: Authorization profiles that can access the configuration or the stream.
cidr String ✓ This option can be used if you would like to restrict viewing of a stream to end users in a certain IP range or CIDR block.
eTokenType Enumeration ✓ Specifies whether to create a new E-Token (NEW), keep the same E-Token (NO_CHANGE), or disable (DISABLE) an existing E-token. Enabling E-type token requires inclusion of a Rijndael key in your token. For details about E-tokens, see the Secure Streaming Integration Guide.
name String ✓ The unique name provided to the authorization profile, not more than 30 characters. If the auth profile names are duplicated then you can’t edit the profiles.
password String ✓ Password for each auth profile. Passwords can be made up of any character type, but must be no more than 10 characters.
requireIP Boolean ✓ Specify whether the authorization profile includes IP addresses in all tokens.
requirePath Boolean ✓ The path value in the token ties the token to a particular stream or piece of content. By removing the path from the token will reduce the security of the token.
requirePayload Boolean ✓ Enabling this value will reject any token that does not include a payload field.
Stream.contactDetails: Provides information about the people in your organization responsible for entry point availability issues.
primary String ✓ The primary person in your organization to contact regarding entry point availability issues.
secondary String ✓ The secondary person in your organization to contact regarding entry point availability issues.
Stream.encoder: Specifies the type of encoder: Name Server or manual configuration. For manual configurations, specify the IP address of the primary and backup encoders used for the stream.
backupEncoderIP String ○ Specifies the IP address of your backup encoders used for the stream. Required for packaged stream types, not for passthrough streams.
password String ○ Optionally, type a password for your encoder to use to access the entry points. Passwords can be made up of any character type, but must be no more than 10 characters long. Leave this option blank if you want the system to generate a password.
primaryEncoderIP String ○ Specifies the IP address of your primary encoders used for the stream. Required for packaged stream types, not for passthrough streams.
Stream.playbackSettings[]: Information about how to play the stream.
connectionUrl String ✓ Connection settings for your encoder to publish the stream.
playbackUrl String ✓ Playback settings for your player to play the stream.

CpCode

The list of used and unused Content Provider codes for creating RTMP configurations or streams.You use CP codes in the Akamai system to track and report delivered services. This CP code is based on JSON for RTMP ingest only. You cannot create two MSL RTMP configuration based on the same CP code.

Download schema: RTMPCpcodesDTO.json

Sample GET response:

{
    "used": [
        {
            "cpcode": 12345,
            "name": "cpcode1"
        },
        {
            "cpcode": 54321,
            "name": "cpcode2"
        },
        {
            "cpcode": 67890,
            "name": "cpcode3"
        }
    ],
    "unused": [
        {
            "cpcode": 24680,
            "name": "cpcode4"
        },
        {
            "cpcode": 13579,
            "name": "cpcode5"
        },
        {
            "cpcode": 21345,
            "name": "cpcode6"
        }
    ]
}

CpCode members

Member Type Description
CpCode: The list of used and unused Content Provider codes for creating RTMP configurations or streams.You use CP codes in the Akamai system to track and report delivered services. This CP code is based on JSON for RTMP ingest only. You cannot create two MSL RTMP configuration based on the same CP code.
unused CpCode.unused[] The list of unused CP codes available to provision RTMP configurations and streams.
used CpCode.used[] The list of unused CP codes available to provision RTMP configurations and streams.
CpCode.unused[]: The list of unused CP codes available to provision RTMP configurations and streams.
cpcode Integer The CP code that you can use to create an RTMP configuration or stream.
name String CP code name.
CpCode.used[]: The list of unused CP codes available to provision RTMP configurations and streams.
cpcode Integer The CP code that you can use to create an RTMP configuration or stream.
name String CP code name.

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 CP code is required.
  • Version details missing.
  • CP code not available for creating domain configuration.
  • User does not have edit permission for CP code.
  • Hostname should not be more than 18 characters.
  • Archive configuration missing.
  • Multiple archive feature currently not supported.
  • Storage Group CP code missing.
  • No CP codes available to create a storage group.
  • The archive CP code 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: 5/30/2019