Media Services Live Stream Provisioning API v2

Push live content from encoders and deliver it either through Akamai or any content delivery network.

Learn more:


Overview

The Media Services Live (MSL) Stream Provisioning API allows you to publish live content and retrieve it for delivery either through Akamai or any content delivery network (CDN). You use MSL primarily for over-the-top (OTT) applications, but you can also use it for other live streaming events. To publish content, you push media content directly from encoders into a live origin through the Akamai ingest server. To deliver it, you pull the content into the origin through a CDN.

The API mirrors the functionality of MSL 4 available in the Luna Control Center.

This API supports the multiple CDN feature, which allows you to use any CDN to deliver your media content, while still using Akamai for ingest and origination. It also supports multi-account access, which allows you to use origin keys to deliver streams defined in one Akamai account in other account configurations, to better syndicate your content for all your customers.

In MSL 4.1, Media Services Live is split from Adaptive Media Delivery, so that you can use MSL 4 with all AMD features. The multi-account feature further allows you to deploy many AMD configurations for many customer accounts, all from a single MSL origin.

Who should use this API

Use this API to access and provision media streaming using customized interfaces.

Getting started

To configure this API for the first time:

  • Contact your Akamai representative to enable it for your account.

  • Ensure that your contract includes MediaServicesLive4::MediaServicesLive4.

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

  • Choose the API service named Media Streaming, and set the access level to READ-WRITE.

Rate limiting

The MSL Stream Provisioning API imposes a rate limiting constraint. Exceeding that limit results in a 429 error response. Consider this especially when calling successive operations as part of a loop.

Responses contain these headers to specify rate limit information:

  • X-RateLimit-Limit: The maximum number of tokens allowed.

  • X-RateLimit-Remaining: The number of tokens remaining.

Once X-RateLimit-Remaining becomes 0, you get a 429 error the next time you make an API call. The response header also displays the time when you can make one more request. For example: X-RateLimit-Next: 2018-05-11T07:04:40.004Z.

If you do not make any more API calls after you receive a 429 error, the X-RateLimit-Remaining gradually increases and becomes equal to X-RateLimit-Limit.

API workflow

Follow these steps to use the MSL Stream Provisioning API:

  1. Create a new MSL origin and optionally use MSL features such as multi-account and multi-CDN.

  2. Create a stream using the origin that you created. Get all of the origins from List live origins and provide the CP code associated with the origin in the stream creation request. The encoder zone should also match the origin location. or Create a stream with a new MSL origin along with the stream settings. Get an unused CP code from List CP codes and provide it in the stream creation request.

  3. Create the Adaptive Media Delivery (AMD) property with the Origin Type as Media Services Live in the Origin Server Behavior section.

You can retrieve these fields to create a stream:

To disable the multi-account and multi-CDN features, make a PUT call with an empty object in the request body.

NOTE: These endpoints are deprecated. Do not use them:

  • /msl-origin/origins/{id}/versions
  • /msl-origin/origins/{id}/versions/{version}/activate

Resources

You deal with various conceptual objects when interacting with the MSL Stream Provisioning API.

  • Streams. Contains configuration details for ingest streams. Stream resources let you create an ingest stream, get a list of streams, get stream details, edit a stream, and delete a stream. See the Stream object type.

  • Origins. Contains configuration for the origin of a stream. With the Media Services Live origin feature, you can publish live content, and retrieve it for delivery through the Akamai content delivery network (CDN). The feature is targeted primarily for OTT applications, but can also be used for other live specific events. Live origin has a publishing workflow and a delivery workflow. See the Origin object type. In the publishing workflow, you can directly push content from encoders into the live origin through the Akamai ingest server. In the delivery workflow, you can pull the content that was earlier published into origin through a CDN.

  • Versions. Contains the Media Services live origin version

  • Activations. Contains activation information for the live origin version

  • Contracts. Contains information about MSL contracts

  • CDN providers. Contains the list of CDN providers

  • CP codes. Displays the CP codes tied to the MSL contract

  • Keys. Shared keys with partners enable authentication between the Origin Shield and the Adaptive Media Delivery (AMD) configuration.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List streams GET /config-media-live/v2/msl-origin/streams{?page,pageSize,sortKey,sortOrder}
Create a stream POST /config-media-live/v2/msl-origin/streams
Get a stream GET /config-media-live/v2/msl-origin/streams/{streamId}
Update a stream PUT /config-media-live/v2/msl-origin/streams/{streamId}
Remove a stream DELETE /config-media-live/v2/msl-origin/streams/{streamId}
List live origins GET /config-media-live/v2/msl-origin/origins{?encoderLocation,cpcode}
Create a new origin POST /config-media-live/v2/msl-origin/origins
Get an origin GET /config-media-live/v2/msl-origin/origins/{originId}
Update an origin PUT /config-media-live/v2/msl-origin/origins/{originId}
List contracts GET /config-media-live/v2/msl-origin/contracts
List CDNs GET /config-media-live/v2/msl-origin/cdns
Generate a key GET /config-media-live/v2/msl-origin/generate-key{?type}
List CP codes GET /config-media-live/v2/msl-origin/cpcodes{?encoderLocation,unused}
List publishing locations GET /config-media-live/v2/msl-origin/publishing-locations

List streams

Retrieves a list of all streams available to a user. Supports optional URL Parameters for pagination and sorting of the results.

GET /config-media-live/v2/msl-origin/streams{?page,pageSize,sortKey,sortOrder}

Sample: /config-media-live/v2/msl-origin/streams?page=2&pageSize=10&sortKey=createdDate&sortOrder=ASC

Parameter Type Sample Description
Optional query parameters
page Integer 2 Specifies the page number to view, starting at 1.
pageSize Integer 10 Indicates the number of data points that are displayed per page. The default is to display all data if you do not specify the page size.
sortKey Enumeration createdDate Sorts the fields displayed based on the key that you specify, either cpcode, createdDate, dvrWindowInMin, format, modifiedDate, name, originHostName, status, or zone.
sortOrder Enumeration ASC Sorts the streams list in ascending (ASC) or descending (DESC) order.

Status 200 application/json

Response Body:

{
    "totalSize": 5,
    "page": 1,
    "pageSize": 10,
    "streams": [
        {
            "id": 123456,
            "name": "DemoStream1",
            "format": "HLS",
            "cpcode": 234567,
            "originHostName": "demo-host1.akamaiorigin.net",
            "modifiedDate": "2017-05-25T07:38:18.003Z",
            "dvrWindowInMin": -1,
            "provisionDetail": {
                "status": "PROVISIONED",
                "message": "Provisioned"
            },
            "encoderZone": "EUROPE",
            "backupStorageCpcode": null,
            "primaryStorageCpcode": 514779,
            "createdDate": "2017-11-14T07:06:25.794Z",
            "createdBy": "abcd",
            "modifiedBy": "def"
        },
        {
            "id": 232123,
            "name": "DemoStream2",
            "format": "HLS",
            "cpcode": 987654,
            "originHostName": "demo-host2.akamaiorigin.net",
            "modifiedDate": "2017-05-25T06:30:48.215Z",
            "dvrWindowInMin": 5,
            "provisionDetail": {
                "status": "FAILED",
                "message": "Stream provisioning failed"
            },
            "encoderZone": "EUROPE",
            "backupStorageCpcode": null,
            "primaryStorageCpcode": 558239,
            "createdDate": "2017-11-14T07:06:25.794Z",
            "createdBy": "abcd",
            "modifiedBy": "def"
        },
        {
            "id": 324453,
            "name": "DemoStream3",
            "format": "HLS",
            "cpcode": 123455,
            "originHostName": "demo-host3.akamaiorigin.net",
            "modifiedDate": "2017-05-25T06:13:13.436Z",
            "dvrWindowInMin": 9,
            "provisionDetail": {
                "status": "PENDING"
            },
            "encoderZone": "EUROPE",
            "backupStorageCpcode": null,
            "primaryStorageCpcode": 678779,
            "createdDate": "2017-11-14T07:06:25.794Z",
            "createdBy": "abcd",
            "modifiedBy": "def"
        }
    ]
}

You can optionally use the following parameters for pagination and sorting of the response:

  • The pagequery parameter specifies the number of pages. The default value is 1.

  • The pageSize query parameter indicates the number of data points that are displayed per page. The default is to display all data if you do not specify the page size.

  • The sortKey query parameter sorts the fields based on any of the following criteria: name, id, format, cpcode, encoderZone, originHostName, isTranscodingEnabled, streamStatus, dvrWindowInMin, createdDate, or modifiedDate.

  • The sortOrderquery parameter sorts the list of streams, either in ASC for ascending order, or DESC for descending order. The default value is DESC.

  • Make a GET request to /config-media-live/v2/msl-origin/streams{?page,pageSize,sortKey,sortOrder}.

The response yields a list of streams.

Create a stream

Provisions a new stream.

POST /config-media-live/v2/msl-origin/streams

Content-Type: application/json

Request Body:

{
    "name": "Demostream",
    "contractId": "ABC-123",
    "format": "HLS",
    "cpcode": 123445,
    "ingestAccelerated": false,
    "allowedIps": [
        "1.2.3.4"
    ],
    "encoderZone": "EUROPE",
    "backupEncoderZone": "AUSTRALIA",
    "origin": {
        "hostName": "demo-host1"
    },
    "additionalEmailIds": [
        "xyz@akamai1.com"
    ],
    "isDedicatedOrigin": false,
    "activeArchiveDurationInDays": 2
}

Status 202

Headers:

Location: /streams/123

To create an ingest stream using Media Services Live 4, you must set up the following:

  • Set up basic stream parameters.
  • Set up archive for the stream.
  • Set up Media Services Live origin for the stream.

The process of creating or updating any stream changes its status to PENDING. When all of the above steps complete, the stream status changes to PROVISIONED. If any of the above steps fail, the stream status changes to FAILED. The typical time for any stream to get provisioned is two to three hours.

  1. Run List CP codes to get the value of the cpcode.

  2. Run List contracts to get the value of the contractId.

  3. Form a Stream object for the request.

  4. POST the object to /config-media-live/v2/msl-origin/streams.

The Location field in the response provides a path where you can access the newly created object.

Get a stream

Retrieves detailed information about the requested stream.

GET /config-media-live/v2/msl-origin/streams/{streamId}

Sample: /config-media-live/v2/msl-origin/streams/50005

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

Status 200 application/json

Response Body:

{
    "id": 745645,
    "name": "DemoStream",
    "format": "HLS",
    "cpcode": 123321,
    "ingestAccelerated": false,
    "dvrWindow": 5,
    "allowedIps": [],
    "encoderZone": "EUROPE",
    "backupEncoderZone": "AUSTRALIA",
    "origin": {
        "hostName": "demo-host1.akamaiorigin.net"
    },
    "backupOrigin": {
        "hostName": "demo-host2.akamaiorigin.net"
    },
    "events": [],
    "createdDate": "2017-11-14T07:06:25.794Z",
    "modifiedDate": "2017-11-14T07:20:12.359Z",
    "createdBy": "abc",
    "modifiedBy": "def",
    "provisionDetail": {
        "streamId": 745645,
        "status": "PENDING"
    },
    "additionalEmailIds": [
        "xyz@akamai1.com"
    ],
    "storageGroup": {
        "cpcode": 125334
    },
    "backupStorageGroup": {
        "cpcode": 124
    },
    "primaryPublishingUrl": "test1.akamaientrypoint.net",
    "backupPublishingUrl": "test2.akamaientrypoint.net",
    "isDedicatedOrigin": false
}
  1. Run List streams to get the value of the streamId URL parameter.

  2. Make a GET request to /config-media-live/v2/msl-origin/streams/{streamId}.

Update a stream

Modifies an existing stream. Specify the same Stream object in the request that’s available from the Get a stream operation’s response.

PUT /config-media-live/v2/msl-origin/streams/{streamId}

Sample: /config-media-live/v2/msl-origin/streams/50005

Content-Type: application/json

Request Body:

{
    "id": 723456,
    "name": "DemostreamEdit",
    "format": "HLS",
    "cpcode": 123456,
    "ingestAccelerated": true,
    "password": 346789999,
    "dvrWindow": 10,
    "allowedIps": [
        "1.2.3.4",
        "2.5.6.7"
    ],
    "encoderZone": "US_EAST",
    "origin": {
        "hostName": "demoHost.akamaiorigin.net"
    },
    "additionalEmailIds": [
        "xyz@akamai1.com",
        "efg@akamai.com"
    ]
}
Parameter Type Sample Description
URL parameters
streamId Integer 50005 Unique identifier for each stream.

Status 202

  1. Run List streams to get the value of the streamId URL parameter.

  2. Make a GET request to /config-media-live/v2/msl-origin/streams/{streamId}.

  3. Modify the Stream response object for your request.

  4. PUT the object to /config-media-live/v2/msl-origin/streams/{streamId}.

Remove a stream

Deletes the specified Stream.

DELETE /config-media-live/v2/msl-origin/streams/{streamId}

Sample: /config-media-live/v2/msl-origin/streams/50005

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

Status 200

  1. Run List streams to get the value of the streamId URL parameter.

  2. Make a DELETE request to /config-media-live/v2/msl-origin/streams/{streamId}.

List live origins

Retrieves a list of all live origins associated with the profile by default, or optionally filtered live origins.

GET /config-media-live/v2/msl-origin/origins{?encoderLocation,cpcode}

Sample: /config-media-live/v2/msl-origin/origins?encoderLocation=Europe&cpcode=876213

Parameter Type Sample Description
Optional query parameters
cpcode Integer 876213 The Media Services Live Content Provider code.
encoderLocation String Europe Specifies the geographical region where the origin is located.

Status 200 application/json

Response Body:

[
    {
        "hostName": "demoHost1.akamaiorigin.net",
        "hostNameIdentifier": "demoHost1",
        "cpcode": 938401,
        "id": 7345,
        "storageCpcode": 0,
        "location": "EUROPE",
        "resourceGroup": "resGrp01",
        "createdDate": "2018-03-12T13:14:02.607Z",
        "modifiedDate": "2018-03-12T13:14:02.607Z",
        "createdBy": "user123",
        "modifiedBy": "user123",
        "otherCdnCpcode": 978902,
        "backupOriginHost": {
            "storageCpcode": null,
            "location": "AUSTRALIA",
            "backupHostName": "demoHost2.akamaiorigin.net"
        }
    },
    {
        "hostName": "demo-host3.akamaiorigin.net",
        "hostNameIdentifier": "demo-host3",
        "cpcode": 966957,
        "id": 5909,
        "storageCpcode": 978765,
        "location": "EUROPE",
        "resourceGroup": "resGrp01",
        "createdDate": "2017-06-09T20:46:34.000Z",
        "modifiedDate": "2017-06-09T20:46:34.000Z",
        "createdBy": "user456",
        "modifiedBy": "user456",
        "otherCdnCpcode": 954371,
        "backupOriginHost": {
            "storageCpcode": null,
            "location": "GERMANY",
            "backupHostName": "demo-host4.akamaiorigin.net"
        }
    }
]
  1. Run List streams to get the value of the encoderLocation and cpcode query parameters.

  2. Make a GET request to /config-media-live/v2/msl-origin/origins{?encoderLocation,cpcode}.

Create a new origin

Create a Media Services live origin for the stream. You can associate this origin hostname with an Adaptive Media Delivery configuration.

POST /config-media-live/v2/msl-origin/origins

Content-Type: application/json

Request Body:

{
    "contractId": "C-Contract-123",
    "hostName": "demohost",
    "cpcode": 123456,
    "encoderZone": "US_EAST",
    "backupEncoderZone": "EUROPE",
    "thirdPartyCdnCpcode": 654321,
    "sharedKeys": [
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "SomeName01",
            "key": "7153f558f89e058ae",
            "enabled": true
        },
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "nonce2",
            "key": "2557f557f39e025db",
            "enabled": false
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName03",
            "cdnCode": "dn00x",
            "enabled": false,
            "guid": "402254d3-e75e-4501-8709-5a3a2211f79",
            "key": "h0BhBScF1Wb3y1r8clJqqg==",
            "expiryDate": "2018-12-12T06:15:00.000Z"
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName04",
            "cdnCode": "dn00x",
            "enabled": true,
            "guid": "105254f3-e75e-4501-8709-5a3a2277d09",
            "key": "h2MhYEcH1Wu3z1r9clJoob==",
            "expiryDate": "2017-09-25T18:33:00.000Z"
        }
    ]
}

Status 202

Headers:

Location: /api/v2/origins/123
  1. Create a Media Services Live Origin object for the request.

  2. Make a POST request to /config-media-live/v2/msl-origin/origins.

Get an origin

Retrieves detailed information about the requested Origin.

GET /config-media-live/v2/msl-origin/origins/{originId}

Sample: /config-media-live/v2/msl-origin/origins/123456

Parameter Type Sample Description
URL parameters
originId Integer 123456 Unique identifier for each Origin.

Status 200 application/json

Response Body:

{
    "id": 101,
    "hostName": "001-dn001-demohost.akamaiorigin.net",
    "backupHostName": "003-dn001-demohost.akamaiorigin.net",
    "cpcode": 123456,
    "encoderZone": "US_EAST",
    "backupEncoderZone": "EUROPE",
    "format": "HLS",
    "status": "SUCCEEDED",
    "modifiedDate": "2017-03-04T02:41:27.964Z",
    "modifiedBy": "ddinakar",
    "activeVersion": "3",
    "thirdPartyCdnCpcode": 654321,
    "sharedKeys": [
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "SomeName01",
            "key": "7153f558f89e058ae",
            "enabled": true
        },
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "nonce2",
            "key": "2557f557f39e025db",
            "enabled": false
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName03",
            "cdnCode": "dn00x",
            "enabled": false,
            "guid": "402254d3-e75e-4501-8709-5a3a2211f79",
            "key": "h0BhBScF1Wb3y1r8clJqqg==",
            "expiryDate": "2018-12-12T06:15:00.000Z",
            "previousKey": "a2BhDFcH1Wu6y1r8clJllm==",
            "previousKeyExpiryDate": "2017-11-22T12:33:00.000Z",
            "hostName": "001-dn00x-demohost.akamaiorigin.net",
            "backupHostName": "003-dn00x-demohost.akamaiorigin.net"
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName04",
            "cdnCode": "dn00x",
            "enabled": true,
            "guid": "105254f3-e75e-4501-8709-5a3a2277d09",
            "key": "h2MhYEcH1Wu3z1r9clJoob==",
            "expiryDate": "2017-09-25T18:33:00.000Z",
            "hostName": "001-dn00x-demohost.akamaiorigin.net",
            "backupHostName": "003-dn00x-demohost.akamaiorigin.net"
        }
    ]
}
  1. Run List live origins to get the value of the originId URL parameter.

  2. Make a GET request to /config-media-live/v2/msl-origin/origins/{originId}.

Update an origin

Updates certain fields of the origin. You can also use this API to rotate keys. Populate previousKey and previousKeyExpiryDate fields if you need your old keys to be valid for a certain amount of time even after rotating.

PUT /config-media-live/v2/msl-origin/origins/{originId}

Sample: /config-media-live/v2/msl-origin/origins/123456

Content-Type: application/json

Request Body:

{
    "id": 101,
    "sharedKeys": [
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "SomeName01",
            "key": "7153f558f89e058ae",
            "enabled": true
        },
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "nonce2",
            "key": "2557f557f39e025db",
            "enabled": false
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName03",
            "cdnCode": "dn00x",
            "enabled": false,
            "guid": "402254d3-e75e-4501-8709-5a3a2211f79",
            "key": "h0BhBScF1Wb3y1r8clJqqg==",
            "expiryDate": "2018-12-12T06:15:00.000Z",
            "previousKey": "a2BhDFcH1Wu6y1r8clJllm==",
            "previousKeyExpiryDate": "2017-11-22T12:33:00.000Z"
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName04",
            "cdnCode": "dn00x",
            "enabled": true,
            "guid": "105254f3-e75e-4501-8709-5a3a2277d09",
            "key": "h2MhYEcH1Wu3z1r9clJoob==",
            "expiryDate": "2017-09-25T18:33:00.000Z"
        }
    ]
}
Parameter Type Sample Description
URL parameters
originId Integer 123456 Unique identifier for each Origin.

Status 202

  1. Run Get an origin to obtain the value of the originId URL parameter.

  2. Make a PUT request to /config-media-live/v2/msl-origin/origins/{originId}.

List contracts

Fetch MSL contracts.

GET /config-media-live/v2/msl-origin/contracts

Status 200 application/json

Response Body:

[
    {
        "contractId": "A-225678B",
        "accountId": "E-A-VC678R",
        "parentContractId": null,
        "contractTypeId": "R-T746",
        "expired": false,
        "childContractIds": null
    },
    {
        "contractId": "A-BVIUED",
        "accountId": "K-J-CA909R",
        "parentContractId": null,
        "contractTypeId": "I-K1YX",
        "expired": false,
        "childContractIds": null
    }
]
  1. Make a GET request to /config-media-live/v2/msl-origin/contracts.

The response yields a list of contracts associated with the origin.

List CDNs

Fetch predefined list of CDN providers. You can configure your MSL origin to include multiple CDN providers.

GET /config-media-live/v2/msl-origin/cdns

Status 200 application/json

Response Body:

[
    {
        "code": "dn002",
        "name": "L3"
    },
    {
        "code": "dn003",
        "name": "Fastly"
    },
    {
        "code": "dn004",
        "name": "Cloudfront"
    }
]
  1. Make a GET request to /config-media-live/v2/msl-origin/cdns.

The response yields an array of CDN objects with a unique code and name.

Generate a key

Specify either an AKAMAI or THIRD_PARTY key format.

GET /config-media-live/v2/msl-origin/generate-key{?type}

Sample: /config-media-live/v2/msl-origin/generate-key?type=AKAMAI

Parameter Type Sample Description
Optional query parameters
type Enumeration AKAMAI Specifies either an AKAMAI or THIRD_PARTY key format.

Status 200 application/json

Response Body:

{
    "key": "Ab+DgsTEL6t5Trcv5KYUZw=="
}
  1. Specify the type as AKAMAI if you are using an Akamai CDN, or THIRD-PARTY if you are using a third-party CDN.

  2. Make a GET request to /config-media-live/v2/msl-origin/generate-key{?type}.

List CP codes

Obtains the CP code based on the service. You need a CP code to create a stream.

GET /config-media-live/v2/msl-origin/cpcodes{?encoderLocation,unused}

Sample: /config-media-live/v2/msl-origin/cpcodes?encoderLocation=EUROPE&unused=true

Parameter Type Sample Description
Optional query parameters
encoderLocation String EUROPE Specifies the geographical region where the origin is located.
unused Boolean true When enabled, lists only CP codes that have not already been used to provision an origin.

Status 200 application/json

Response Body:

[
    {
        "id": 321234,
        "name": "Test",
        "contracts": [
            {
                "contractId": "Z-AAAVOB"
            }
        ],
        "isUsed": false
    }
]
  1. Run List publishing locations to get the value of the encoderLocation URL parameter.

  2. Specify unused in the query to ensure that the CP code is not used already.

  3. Make a GET request to /config-media-live/v2/msl-origin/cpcodes{?encoderLocation,unused}.

List publishing locations

Get valid encoder locations.

GET /config-media-live/v2/msl-origin/publishing-locations

Status 200 application/json

Response Body:

[
    {
        "location": "EUROPE",
        "code": "001",
        "netstorageZone": "europe"
    },
    {
        "location": "NORTH_AMERICA",
        "code": "002",
        "netstorageZone": "us"
    },
    {
        "location": "LATIN_AMERICA",
        "code": "003",
        "netstorageZone": "us"
    },
    {
        "location": "SOUTH_AMERICA",
        "code": "004",
        "netstorageZone": "us"
    },
    {
        "location": "NORDICS",
        "code": "005",
        "netstorageZone": "europe"
    },
    {
        "location": "ASIA_PACIFIC",
        "code": "006",
        "netstorageZone": "asia"
    },
    {
        "location": "OTHER_AMERICAS",
        "code": "007",
        "netstorageZone": "us"
    },
    {
        "location": "OTHER_APJ",
        "code": "008",
        "netstorageZone": "asia"
    },
    {
        "location": "OTHER_EMEA",
        "code": "009",
        "netstorageZone": "europe"
    },
    {
        "location": "GERMANY",
        "code": "011",
        "netstorageZone": "europe"
    },
    {
        "location": "INDIA",
        "code": "012",
        "netstorageZone": "asia"
    },
    {
        "location": "ITALY",
        "code": "013",
        "netstorageZone": "europe"
    },
    {
        "location": "JAPAN",
        "code": "014",
        "netstorageZone": "asia"
    },
    {
        "location": "MEXICO",
        "code": "015",
        "netstorageZone": "us"
    },
    {
        "location": "TAIWAN",
        "code": "016",
        "netstorageZone": "asia"
    },
    {
        "location": "UNITED_KINGDOM",
        "code": "017",
        "netstorageZone": "europe"
    },
    {
        "location": "US_EAST",
        "code": "018",
        "netstorageZone": "useast"
    },
    {
        "location": "US_CENTRAL",
        "code": "019",
        "netstorageZone": "useast"
    },
    {
        "location": "US_WEST",
        "code": "020",
        "netstorageZone": "us"
    },
    {
        "location": "AUSTRALIA",
        "code": "010",
        "netstorageZone": "AU"
    }
]
  1. Make a GET request to /config-media-live/v2/msl-origin/publishing-locations.

The response yields a list of locations from which the stream is published.

Data

This section provides you with the data model for the Media Services Live Stream Provisioning API.

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.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Stream

Encapsulates stream configuration and version information. You can list, create, edit, delete, and get details of streams.

Download schema: StreamDetailsPostDTO.json, StreamDetailsDTO.json, StreamDetailsPutDTO.json

Sample GET response:

{
    "id": 745645,
    "name": "DemoStream",
    "format": "HLS",
    "cpcode": 123321,
    "ingestAccelerated": false,
    "dvrWindow": 5,
    "allowedIps": [],
    "encoderZone": "EUROPE",
    "backupEncoderZone": "AUSTRALIA",
    "origin": {
        "hostName": "demo-host1.akamaiorigin.net"
    },
    "backupOrigin": {
        "hostName": "demo-host2.akamaiorigin.net"
    },
    "events": [],
    "createdDate": "2017-11-14T07:06:25.794Z",
    "modifiedDate": "2017-11-14T07:20:12.359Z",
    "createdBy": "abc",
    "modifiedBy": "def",
    "provisionDetail": {
        "streamId": 745645,
        "status": "PENDING"
    },
    "additionalEmailIds": [
        "xyz@akamai1.com"
    ],
    "storageGroup": {
        "cpcode": 125334
    },
    "backupStorageGroup": {
        "cpcode": 124
    },
    "primaryPublishingUrl": "test1.akamaientrypoint.net",
    "backupPublishingUrl": "test2.akamaientrypoint.net",
    "isDedicatedOrigin": false
}

Stream members

Member Type POST GET PUT Description
activeArchiveDurationInDays Integer Specify 1 through 31 to archive your active content for 1 through 31 days. This option is available only for HLS and DASH streams. It appears if you have MediaServicesLive4::LiveToVOD in your contract. There is no default value.
additionalEmailIds Array Specify email IDs of users who should receive the stream configuration details and status notification email.
allowedIps Array Specify the encoder IP addresses. You can enter up to 50 comma-separated IP addresses.
backupEncoderZone String Specify the backup encoder’s geographical location.
backupOrigin Origin Specify the backup origin hostname to be associated with the stream.
backupPublishingUrl String Specify the encoder’s backup publishing URL. For example, if the stream format is HLS, streamId is 5002, and event is test79, the backup publishing URL is http://b-ep50002.i.akamaientrypoint.net/50002-b/test79.
backupStorageGroup Stream.backupStorageGroup Specify the backup storage group to be associated with the stream.
contractId String Specify a contract ID to indicate the contract to associate with the stream. The system filters the ingest CP code based on the contract ID that you specify. The NetStorage CP code (if created) is also associated with the same contract as the ingest CP code (the contract ID that you enter). If you do not specify a contract ID, then the first valid contract is used.
cpcode Integer CP code resources let you 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.
createdBy String Specify the username who created the stream.
createdDate String Specify the date on which you create the stream.
dvrWindow Integer An archive window is the length of time that content is available as DVR content, from 5 to 30 minutes. A 30 minute scrub back window is enabled for all streams.
encoderZone String Specify the primary encoder’s geographical location. Choose an encoder that is close to your location.
events Stream.events[] Specify the name of the event and the number of days of data (pertaining to the event) that you want to purge.
format Enumeration The ingest format for Apple HTTP Live Streaming (HLS), Adobe HTTP Dynamic Streaming (HDS), Dynamic Adaptive Streaming over HTTP (DASH), or Common Media Application Format (CMAF).
id Integer Specify an ID for the stream.
ingestAccelerated Boolean Specify whether to use the Media Services Live Ingest Acceleration feature. If you specify true, you must specify a password in the Password field below. The username is the Media Services Live CP code. The Ingest Acceleration feature improves encoder to Akamai ingest performance and provides more stability and reliability over the first mile.
isDedicatedOrigin Boolean Specify whether to use a dedicated origin hostname. You cannot edit an existing stream to make it dedicated, you can use this option only when you create a new stream. If you use a dedicated origin, the origin shield network has a new item called resource group to identify your company.
modifiedBy String Specify the username who edited the stream.
modifiedDate String Specify the date on which the stream is modified.
name String Specify the stream name. The name can be up to 90 characters long and can include alphanumeric, underscore, and dash characters.
origin Origin Specify the primary Media Services Live origin to be associated with the stream.
password String Specify a password for the Ingest Acceleration feature.
primaryPublishingUrl String Specify the encoder’s primary publishing URL. For example, if the stream format is HLS, streamId is 5002, and event is test79, the primary publishing URL is http://p-ep50002.i.akamaientrypoint.net/50002/test79.
provisionDetail Stream.provisionDetail Specify details about the stream provisioning.
storageGroup Stream.storageGroup A storage group is where you keep your content for distribution.
Stream.backupStorageGroup: Specify the backup storage group to be associated with the stream.
cpcode Integer Specify the Media Services Live CP code for the backup storage.
Stream.events[]: Specify the name of the event and the number of days of data (pertaining to the event) that you want to purge.
age Integer Specify the number of days of data (pertaining to the event) that you want to delete from storage.
event String Specify the name of the event that you want to purge.
Stream.provisionDetail: Specify details about the stream provisioning.
message String Specify a message about the stream status.
status Enumeration The status of the stream, either PENDING, PROVISIONED, FAILED, or NOT_STARTED.
streamId Integer A unique ID for your stream.
Stream.storageGroup: A storage group is where you keep your content for distribution.
cpcode Integer Specify at least one Akamai Content Provider code for the storage group.

Origin

Configures a Media Services Live origin for the stream and lets you share the origin with partner accounts within Akamai (using multi-account) as well as third-party delivery providers (using multi-CDN).

Download schema: OriginDetailDTOV2Post.json, OriginDetailDTOV2.json, OriginDetailDTOV2Put.json

Sample GET response:

{
    "id": 101,
    "hostName": "001-dn001-demohost.akamaiorigin.net",
    "backupHostName": "003-dn001-demohost.akamaiorigin.net",
    "cpcode": 123456,
    "encoderZone": "US_EAST",
    "backupEncoderZone": "EUROPE",
    "format": "HLS",
    "status": "SUCCEEDED",
    "modifiedDate": "2017-03-04T02:41:27.964Z",
    "modifiedBy": "ddinakar",
    "activeVersion": "3",
    "thirdPartyCdnCpcode": 654321,
    "sharedKeys": [
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "SomeName01",
            "key": "7153f558f89e058ae",
            "enabled": true
        },
        {
            "type": "AKAMAI",
            "authMethod": "MSL_MULTI_ACCOUNT",
            "name": "nonce2",
            "key": "2557f557f39e025db",
            "enabled": false
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName03",
            "cdnCode": "dn00x",
            "enabled": false,
            "guid": "402254d3-e75e-4501-8709-5a3a2211f79",
            "key": "h0BhBScF1Wb3y1r8clJqqg==",
            "expiryDate": "2018-12-12T06:15:00.000Z",
            "previousKey": "a2BhDFcH1Wu6y1r8clJllm==",
            "previousKeyExpiryDate": "2017-11-22T12:33:00.000Z",
            "hostName": "001-dn00x-demohost.akamaiorigin.net",
            "backupHostName": "003-dn00x-demohost.akamaiorigin.net"
        },
        {
            "type": "THIRD_PARTY",
            "authMethod": "SIMPLE_AKAMAI_HEADER_VERIFICATION",
            "name": "SomeName04",
            "cdnCode": "dn00x",
            "enabled": true,
            "guid": "105254f3-e75e-4501-8709-5a3a2277d09",
            "key": "h2MhYEcH1Wu3z1r9clJoob==",
            "expiryDate": "2017-09-25T18:33:00.000Z",
            "hostName": "001-dn00x-demohost.akamaiorigin.net",
            "backupHostName": "003-dn00x-demohost.akamaiorigin.net"
        }
    ]
}

Origin members

Member Type POST GET PUT Description
activeVersion Integer Specifiy the version of the origin that is enabled.
amdProperties Origin.amdProperties[] AMD properties associated with this origin in the current account.
backupEncoderZone String Specify the backup encoder’s geographical location.
backupHostName String Specify a backup hostname for the origin.
contractId String Specify the contract ID to associate with the origin. The CP code is filtered based on the contract ID that you specify. The system associates the NetStorage CP code (if created) with the same contract as the ingest CP code.
cpcode Integer Select the Media Services Live CP code. You use CP codes in the Akamai system to track and report delivered services.
encoderZone String Specify the primary encoder’s geographical location. Choose a location that is close to your encoder.
hostName String Specify the origin hostname.
id Integer Enter a unique identifier for the origin. The identifier must be unique, regardless of encoder locations and customers. The primary hostname and backup hostname are automatically derived from the origin identifier you specify.
isDedicatedOrigin Boolean Specify whether or not the origin is a dedicated origin. When you use a dedicated origin, you must create a new stream. You can’t edit an existing stream to make it dedicated. If you use a dedicated origin, the origin shield network has a new item called resource group to identify your company.
modifiedBy String Specify the user name of the person who changed the origin.
modifiedDate String Specify the date on which the origin was modified.
sharedKeys Origin.sharedKeys[] Shared keys enable you to share your MSL origin with partner accounts within Akamai (Multi-Account) or third-party delivery providers (Multi-CDN).
status String Specifies the origin creation status: SUCCEEDED or FAILED.
thirdPartyCdnCpcode Integer Specify the third-party CDN CP code.
Origin.amdProperties[]: AMD properties associated with this origin in the current account.
assetId Integer Asset ID of AMD property.
propertyName String Name of AMD property.
Origin.sharedKeys[]: Shared keys enable you to share your MSL origin with partner accounts within Akamai (Multi-Account) or third-party delivery providers (Multi-CDN).
amdProperties Origin.sharedKeys[].amdProperties[] AMD properties associated with this key in other accounts. It is only applicable for AKAMAI type of keys.
authMethod Enumeration Specify the authentication method as SIMPLE_AKAMAI_HEADER_VERIFICATION for Akamai partner accounts or MSL_MULTI_ACCOUNT for third-party CDN accounts.
backupHostName String Specify a backup hostname for the origin.
cdnCode String Auto-generated code for the CDN.
data String Auto-generated data field for the CDN.
enabled Boolean Specify enabled or disabled to activate or deactivate the CDN.
expiryDate String Specify a future date and time up to which the CDN provider configuration is valid. The time zone is the current time zone where you configure your settings.
guid String Auto-generated GUI ID for the CDN.
hostName String Specify the hostname for the CDN.
key String Auto-generated key to access the CDN.
name String Name to identify the CDN.
previousData String Auto-generated previous data field for the CDN.
previousKey String Displays the previously configured key to access the CDN.
previousKeyExpiryDate String Displays the expiry date for the previous key.
type Enumeration Specify AKAMAI if you are using an Akamai CDN or THIRD_PARTY if you are using some other CDN.
Origin.sharedKeys[].amdProperties[]: AMD properties associated with this key in other accounts. It is only applicable for AKAMAI type of keys.
accountId String Account ID where the AMD property has been created using this shared key.
accountName String Account name where the AMD property has been created using this shared key.
propertyName String Name of the AMD property created using this shared key.

Contract

Specify the contract ID to associate with the origin. The system filters the CP code based on the contract ID that you specify. It associates the NetStorage CP code (if created) with the same contract as the ingest CP code (the contract ID that you specify).

Download schema: BasicContractDTO.json

Sample GET response:

[
    {
        "contractId": "A-225678B",
        "accountId": "E-A-VC678R",
        "parentContractId": null,
        "contractTypeId": "R-T746",
        "expired": false,
        "childContractIds": null
    },
    {
        "contractId": "A-BVIUED",
        "accountId": "K-J-CA909R",
        "parentContractId": null,
        "contractTypeId": "I-K1YX",
        "expired": false,
        "childContractIds": null
    }
]

Contract members

Member Type Required Description
accountId String Customer account ID.
childContractIds Array, Null Value is null if no child contract ID is associated with the contract.
contractId String Specify the contract ID to associate with the origin.
contractTypeId String Specify the type of contract.
expired Boolean Indicates whether the contract has expired.
parentContractId String, Null Value is null if there is no parent contract ID associated with the contract.

CpCode

Specifies the origin CP code.

Download schema: CpcodeDTO.json

Sample GET response:

[
    {
        "id": 321234,
        "name": "Test",
        "contracts": [
            {
                "contractId": "Z-AAAVOB"
            }
        ],
        "isUsed": false
    }
]

CpCode members

Member Type Required Description
contracts CpCode.contracts[] CP code identifier.
id Integer CP code that you can use to create the origin.
isUsed Boolean Indicates whether the CP code is associated with an origin.
name String Name of the CP code.
CpCode.contracts[]: CP code identifier.
contractId String The ID of the contract associated with the CP code.

PublishingLocation

Specifies details about the location from which the stream is published.

Download schema: PublishingLocationDTO.json

Sample GET response:

[
    {
        "location": "EUROPE",
        "code": "001",
        "netstorageZone": "europe"
    },
    {
        "location": "NORTH_AMERICA",
        "code": "002",
        "netstorageZone": "us"
    },
    {
        "location": "LATIN_AMERICA",
        "code": "003",
        "netstorageZone": "us"
    },
    {
        "location": "SOUTH_AMERICA",
        "code": "004",
        "netstorageZone": "us"
    },
    {
        "location": "NORDICS",
        "code": "005",
        "netstorageZone": "europe"
    },
    {
        "location": "ASIA_PACIFIC",
        "code": "006",
        "netstorageZone": "asia"
    },
    {
        "location": "OTHER_AMERICAS",
        "code": "007",
        "netstorageZone": "us"
    },
    {
        "location": "OTHER_APJ",
        "code": "008",
        "netstorageZone": "asia"
    },
    {
        "location": "OTHER_EMEA",
        "code": "009",
        "netstorageZone": "europe"
    },
    {
        "location": "GERMANY",
        "code": "011",
        "netstorageZone": "europe"
    },
    {
        "location": "INDIA",
        "code": "012",
        "netstorageZone": "asia"
    },
    {
        "location": "ITALY",
        "code": "013",
        "netstorageZone": "europe"
    },
    {
        "location": "JAPAN",
        "code": "014",
        "netstorageZone": "asia"
    },
    {
        "location": "MEXICO",
        "code": "015",
        "netstorageZone": "us"
    },
    {
        "location": "TAIWAN",
        "code": "016",
        "netstorageZone": "asia"
    },
    {
        "location": "UNITED_KINGDOM",
        "code": "017",
        "netstorageZone": "europe"
    },
    {
        "location": "US_EAST",
        "code": "018",
        "netstorageZone": "useast"
    },
    {
        "location": "US_CENTRAL",
        "code": "019",
        "netstorageZone": "useast"
    },
    {
        "location": "US_WEST",
        "code": "020",
        "netstorageZone": "us"
    },
    {
        "location": "AUSTRALIA",
        "code": "010",
        "netstorageZone": "AU"
    }
]

PublishingLocation members

Member Type Required Description
code String Specifies an ID code for the location from which the stream is published.
location String Specifies the geographic location from which the stream is published.
netstorageZone String Specifies the NetStorage zone location that you can use to replicate your content.

Errors

This section provides details on the data object that reflect the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

When the API encounters an error, it responds with a JSON object whose ok member is false. It also includes an error code and error message.

The following example shows the 400 error code:

{
  "type": "bad-request",
  "title": "Erroneous data input",
  "instance": "8ed959ae-bc22-43f4-893c-2f293518f258",
  "status": 400,
  "errors": [
    {
      "type": "bad-request",
      "title": "Bad Request",
      "instance": "1664e1a7-d916-4cf9-944f-2d9f6d176f8f",
      "detail": "Expiry Date of Previous Key is required"
    }
  ]
}

HTTP status codes

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

Code Description
200 The operation was successful.
201 Resource created.
202 Resource successfully accepted. This is returned on an activation request. It does not mean that the activation was successful. It means that the API will act upon the request.
400 Bad Request.
401 Unauthorized request.
402 Failed request.
403 Access is forbidden. The user does not have access to the requested resource.
404 Resource not found.
405 Method not allowed.
415 Unsupported media type
422 Unprocessable entity.
429 Too many requests. See Rate limiting.
500 Internal server error. Unexpected error.

Last modified: 11/28/2018