Media Services Live Stream Provisioning API v1

Push live content from encoders and have it retrieved for delivering either through Akamai or any content delivery network.

Learn more:


Overview

The Media Services Live (MSL) Stream Provisioning API enables you to publish live content, and retrieves it for delivering either through Akamai or any content delivery network (CDN). These operations are 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.

In the publishing workflow, you can directly push content from encoders into 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.

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

Who should use this API

The MSL Stream Provisioning API enables developers and architects to access and provision media streaming using customized interfaces.

To use this API, ensure that your contract includes MediaServicesLive4::MediaServicesLive4.

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

Getting started

Before using the MSL Stream Provisioning API for the first time:

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

  • Review Get Started for tools that Akamai provides.

  • Review Authorize Your Client to create your Akamai API access credentials and authorizations. As detailed in The API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • Select the following when you configure your Akamai API client:

    • API Group: Luna
    • API Name: Media Streaming

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 have the following headers to specify rate limit information:

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

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

Resources

This section provides details on each API operation.

The following list provides a road map of all the conceptual objects you deal with when interacting with the MSL Stream Provisioning API, and provides pointers to where you can learn more.

  • Stream: This object contains configuration details for ingest streams. The Stream resources enables you to create an ingest stream, get a list of streams, get stream details, edit a stream, and delete a stream. See the Stream object type.

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

    • Set up basic stream parameters.
    • Set up DVR 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 around two to three hours.

  • Origin: This object contains configuration for the origin of a stream. The Media Services Live origin feature enables you to publish live content, and retrieves 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 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.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List Streams GET /config-media-live/v1/msl-origin/streams{?page,pageSize,sortKey,sortOrder}
Create a Stream POST /config-media-live/v1/msl-origin/streams
Get Stream Details GET /config-media-live/v1/msl-origin/streams/{streamId}
Update a Stream PUT /config-media-live/v1/msl-origin/streams/{streamId}
Remove a Stream DELETE /config-media-live/v1/msl-origin/streams/{streamId}
List All Live Origins GET /config-media-live/v1/msl-origin/origins{?region,cpcode}
Get Live Origin Details GET /config-media-live/v1/msl-origin/origins/{id}
Get Activation Status GET /config-media-live/v1/msl-origin/origins/{id}/status
Create an Origin Version PUT /config-media-live/v1/msl-origin/origins/{id}/versions{?activate}
Activate an Origin Version PUT /config-media-live/v1/msl-origin/origins/{id}/versions/{version}/activate

List streams

Retrieves a list of all streams available to a user. Supports an optional request object for pagination and sorting of the results.

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

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

Content-Type: application/json

Request Body:

{
    "pageSize": 25,
    "page": 1,
    "sortKey": "name",
    "sortOrder": "ASC"
}
Parameter Type Sample Description
Optional query parameters
page Integer 2 Specifies the number of pages.
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 or descending order, either ASC or DESC.

Status 200 application/json

Response Body:

{
    "totalSize": 5,
    "streams": [
        {
            "cpcode": 563423,
            "originHostName": "demo-host1.akamaiorigin.net",
            "name": "DemoStream1",
            "format": "HLS",
            "primaryStorageCpcode": 558779,
            "dvrWindowInMin": -1,
            "encoderZone": "EUROPE",
            "modifiedBy": "def",
            "modifiedDate": "2017-05-25T07:38:18.003Z",
            "createdBy": "abcd",
            "createdDate": "2017-11-14T07:06:25.794Z",
            "backupStorageCpcode": 199342,
            "id": 123456,
            "provisionDetail": {
                "status": "PROVISIONED",
                "message": "Provisioned"
            }
        },
        {
            "cpcode": 652345,
            "originHostName": "demo-host2.akamaiorigin.net",
            "name": "DemoStream2",
            "format": "HLS",
            "primaryStorageCpcode": 558779,
            "dvrWindowInMin": 5,
            "encoderZone": "EUROPE",
            "modifiedBy": "def",
            "modifiedDate": "2017-05-25T06:30:48.215Z",
            "createdBy": "abcd",
            "createdDate": "2017-11-14T07:06:25.794Z",
            "backupStorageCpcode": 199342,
            "id": 654768,
            "provisionDetail": {
                "status": "FAILED",
                "message": "Stream provisioning failed"
            }
        },
        {
            "cpcode": 123455,
            "originHostName": "demo-host3.akamaiorigin.net",
            "name": "DemoStream3",
            "format": "HLS",
            "primaryStorageCpcode": 558779,
            "dvrWindowInMin": 9,
            "encoderZone": "EUROPE",
            "modifiedBy": "def",
            "modifiedDate": "2017-05-25T06:13:13.436Z",
            "createdBy": "abcd",
            "createdDate": "2017-11-14T07:06:25.794Z",
            "backupStorageCpcode": 199342,
            "id": 3276426,
            "provisionDetail": {
                "status": "PENDING"
            }
        }
    ],
    "page": 1,
    "pageSize": 10
}
  1. Form an optional PagingAndSorting object for sorting pagination of the request.

  2. Make a GET request to /config-media-live/v1/msl-origin/streams.

Create a stream

Provisions a new stream.

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

Content-Type: application/json

Request Body:

{
    "origin": {
        "hostName": "demo-host1.akamaiorigin.net"
    },
    "encoderZone": "EUROPE",
    "isDedicatedOrigin": false,
    "backupEncoderZone": "EUROPE",
    "allowedIps": [],
    "ingestAccelerated": false,
    "additionalEmailIds": [
        "abc@akamai.com"
    ],
    "modifiedBy": "def",
    "events": [],
    "cpcode": 123321,
    "format": "HLS",
    "dvrWindow": 5,
    "backupOrigin": {
        "hostName": "demo-host2.akamaiorigin.net"
    },
    "modifiedDate": "2017-11-14T07:20:12.359Z",
    "createdBy": "abc",
    "createdDate": "2017-11-14T07:06:25.794Z",
    "primaryPublishingUrl": "test1.akamaientrypoint.net",
    "contractId": "C-12B45",
    "backupStorageGroup": {
        "isNew": true
    },
    "name": "DemoStream",
    "backupPublishingUrl": "test2.akamaientrypoint.net",
    "storageGroup": {
        "isNew": true
    }
}

Status 202

Headers:

Location: /streams/123
  1. Form a Stream object for the request.

  2. Make a POST request to /config-media-live/v1/msl-origin/streams.

Get stream details

Retrieves detailed information about the requested stream ID.

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

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

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

Status 200 application/json

Response Body:

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

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

Update a stream

Modifies an existing stream. The request body object must be identical in structure to the Get Stream Details response object.

You can edit the name, ingestAccelerated, password, dvrWindow, allowedIps, and additionalEmailIds fields. If you try to edit any other field, the API returns a 400 - Bad Request.

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

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

Content-Type: application/json

Request Body:

{
    "cpcode": 123432,
    "origin": {
        "hostName": "demoHost1.akamaiorigin.net",
        "id": 541,
        "versions": []
    },
    "name": "DemoStream1",
    "format": "HLS",
    "dvrWindow": 5,
    "ingestAccelerated": false,
    "encoderZone": "EUROPE",
    "additionalEmailIds": [],
    "id": 345698
}
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/v1/msl-origin/streams/{streamId}.

  3. Modify the Stream response object for your request.

  4. Make a PUT request to /config-media-live/v1/msl-origin/streams/{streamId}.

Remove a stream

Deletes the specified Stream.

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

Sample: /config-media-live/v1/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/v1/msl-origin/streams/{streamId}.

List all live origins

Retrieves a list of all Live Origins associated with the profile.

GET /config-media-live/v1/msl-origin/origins{?region,cpcode}

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

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

Status 200 application/json

Response Body:

[
    {
        "cpcode": 765456,
        "storageCpcode": 987654,
        "hostName": "demo-host1.akamaiorigin.net",
        "resourceGroup": "demo-rg",
        "location": "GERMANY",
        "createdDate": "2017-05-05",
        "id": null,
        "backupOriginHost": {
            "storageCpcode": null,
            "location": "EUROPE",
            "backupHostName": "demo1.akamaiorigin.net"
        }
    },
    {
        "cpcode": 765987,
        "storageCpcode": 678765,
        "hostName": "demo-host2.akamaiorigin.net",
        "resourceGroup": "demo-rg",
        "location": "EUROPE",
        "createdDate": "2017-05-05",
        "id": null
    },
    {
        "cpcode": 146549,
        "storageCpcode": 678765,
        "hostName": "demo-host3.akamaiorigin.net",
        "resourceGroup": "demo-rg",
        "location": "EUROPE",
        "createdDate": "2017-05-03",
        "id": null
    }
]

Get live origin details

Retrieves the details of the specified Live Origin.

GET /config-media-live/v1/msl-origin/origins/{id}

Sample: /config-media-live/v1/msl-origin/origins/68

Parameter Type Sample Description
URL parameters
id Integer 68 Unique identifier for each origin.

Status 200 application/json

Response Body:

{
    "cpcode": 876213,
    "status": "SUCCEEDED",
    "hostName": "demoHost1.akamaiorigin.net",
    "id": 68,
    "versions": [
        {
            "additionalHostNames": [],
            "notes": "Initial Version",
            "sslEnabled": false,
            "version": 1,
            "createdBy": "username",
            "createdDate": "2017-06-12T17:28:19.825Z",
            "active": true
        }
    ]
}
  1. Run List All Live Origins to get the value of the id URL parameter.

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

Get activation status

Retrieves the activation status of an origin.

GET /config-media-live/v1/msl-origin/origins/{id}/status

Sample: /config-media-live/v1/msl-origin/origins/68/status

Parameter Type Sample Description
URL parameters
id Integer 68 Unique identifier for each origin.

Status 200 application/json

Response Body:

{
    "status": "PENDING"
}
  1. Run List All Live Origins to get the value of the id URL parameter.

  2. Make a GET request to /config-media-live/v1/msl-origin/origins/{id}/status.

Create an origin version

Creates a new live origin version. additionalHostnames enum values can have up to 16 alphanumeric and dot characters. Only alphabets, numerals and periods (.) are allowed.

PUT /config-media-live/v1/msl-origin/origins/{id}/versions{?activate}

Sample: /config-media-live/v1/msl-origin/origins/68/versions?activate=true

Content-Type: application/json

Request Body:

{
    "g2oKeys": [
        {
            "nonce": "k",
            "key": "c5d6987ba300b7029"
        }
    ],
    "notes": "Cloning from version 3"
}
Parameter Type Sample Description
URL parameters
id Integer 68 Unique identifier for each origin.
Required query parameters
activate Boolean true Enable this origin version.

Status 202 application/json

Response Body:

{
    "g2oKeys": [
        {
            "nonce": "key1",
            "key": "a4c4e2492e9114087"
        },
        {
            "nonce": "key2",
            "key": "9eb53670855ad3184"
        }
    ],
    "notes": "Cloning from version 1",
    "sslEnabled": false,
    "version": 2,
    "createdBy": "abcd",
    "createdDate": "2017-11-14T10:11:08.670Z",
    "active": false
}
  1. Run List All Live Origins to get the value of the id URL parameter.

  2. Specify true for the activate parameter.

  3. Form an Origin object for the request.

  4. Make a PUT request to /config-media-live/v1/msl-origin/origins/{id}/versions{?activate}.

Activate an origin version

Activates the specified version of Live Origin.

PUT /config-media-live/v1/msl-origin/origins/{id}/versions/{version}/activate

Sample: /config-media-live/v1/msl-origin/origins/68/versions/2/activate

Parameter Type Sample Description
URL parameters
id Integer 68 Unique identifier for each origin.
version Integer 2 Version of the origin.

Status 202 application/json

Response Body:

{
    "status": "PENDING"
}
  1. Run List All Live Origins to get the value of the id URL parameter.

  2. Make a GET request to /config-media-live/v1/msl-origin/origins/{id} to get the value of the version URL parameter.

  3. Make a PUT request to /config-media-live/v1/msl-origin/origins/{id}/versions/{version}/activate.

Data

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

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether the value is empty or null.
Member is optional, and may be omitted in some cases.

Download the JSON schemas for this API.

Stream

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

Download schema: StreamDTO.json

Sample GET:

{
    "id": 654345,
    "name": "DemoStream",
    "format": "HLS",
    "cpcode": 123321,
    "ingestAccelerated": false,
    "dvrWindow": 5,
    "allowedIps": [],
    "encoderZone": "EUROPE",
    "backupEncoderZone": "EUROPE",
    "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": 235235,
        "status": "PENDING"
    },
    "additionalEmailIds": [
        "abc@akamai.com"
    ],
    "storageGroup": {
        "cpcode": 125334
    },
    "backupStorageGroup": {
        "cpcode": 124
    },
    "primaryPublishingUrl": "test1.akamaientrypoint.net",
    "backupPublishingUrl": "test2.akamaientrypoint.net",
    "isDedicatedOrigin": false
}

Stream members

Member Type Required Description
backupStorageCpcode Integer Specify the Media Services Live CP code for the backup storage.
cpcode Integer 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.
createdBy String Specify the user name of the user who created the stream.
createdDate String Specifies the date on which the stream was created.
dvrWindowInMin Integer Specify a DVR Window value from 5 to 30 minutes. DVR Window is the length of time that content is available as DVR content.
encoderZone String Specify the encoder’s geographical location. Choose an encoder that is close to your location.
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). Enum values: CMAF, DASH, HDS, HLS.
id Integer Specify the stream ID. The stream ID must be identical between your primary and backup streams. The stream ID can be obtained from the Luna Control Center’s Manage HD Live Streams and Stream Details pages.
modifiedBy String Specify the user name of the user who edited the stream.
modifiedDate String Specify the date on which the stream is modified.
name String Specify a name for your stream. Your stream name can be up to 90 characters in length and can include the characters a-z, A-Z, 0–9, underscores ( _ ), and hyphens ( - ).
originHostName String Specify the origin hostname. This depends on the CDN that you use. For Akamai CDN, the hostname is origin.akamaized.net (AMD hostname).
primaryStorageCpcode Integer Specify the Media Services Live CP code for the primary storage.
provisionDetail Stream.provisionDetail Provides details about the stream provisioning status.
Stream.provisionDetail: Provides details about the stream provisioning status.
message String Specify a message about the stream status.
status Enumeration The status of the stream. Possible enum values are: PENDING, PROVISIONED, FAILED
streamId Integer A unique ID for your stream.

Origin

Encapsulates configuration and versions for an origin. You can list, create, edit, and get details of origins. You can also create and activate origin versions.

Download schema: OriginDetailsDTO.json

Sample GET:

{
    "id": 68,
    "hostName": "demoHost1.akamaiorigin.net",
    "cpcode": 876213,
    "versions": [
        {
            "additionalHostNames": [],
            "sslEnabled": false,
            "version": 1,
            "active": true,
            "notes": "Initial Version",
            "createdBy": "username",
            "createdDate": "2017-06-12T17:28:19.825Z"
        }
    ],
    "status": "SUCCEEDED"
}

Origin members

Member Type Required Description
cpcode Integer Specify the origin CP code.
createdDate Integer Specify the date on which the origin is created.
g2oKeys Origin.versions[].g2oKeys[] Specify the origin G2O key(s) name and value for multi account origin access. Multi Account Access enables you to allow Media Services Live streams defined in one account to be delivered by delivery configurations in other account(s). This is achieved by using manual access key(s) or G2O keys.
hostName String Specify the origin hostname. The hostname can have up to 16 alphanumeric characters and periods. Only alphabets, numerals and periods (.) are allowed. Do not use any other characters or consecutive periods.
id Integer Specify the origin ID.
notes String Notes about the origin (such as the version).
region String Origin location.
resourceGroup String Identifies logical grouping of resources of similar type that allows the MSL system to leverage or enforce specific behavior (such as mapping preferences for Dedicated Origin).
status String Origin status (such as SUCCEEDED or FAILED).
versions Origin.versions[] Encapsulates a version for an origin configuration. You can create, activate, and get details of origin versions.
Origin.g2oKeys[]: Specify the origin G2O key(s) name and value for multi account origin access. Multi Account Access enables you to allow Media Services Live streams defined in one account to be delivered by delivery configurations in other account(s). This is achieved by using manual access key(s) or G2O keys.
key String Specify the origin G2O key(s).
nonce String Enter a Name (up to 8 alphabets, numbers, or alphanumeric characters) for the G2O key to be generated.
Origin.versions[]: Encapsulates a version for an origin configuration. You can create, activate, and get details of origin versions.
active Boolean Specifies whether the origin is active.
additionalHostNames Array A list of additional origin hostnames.
createdBy String Specifies the user name of the person who created the origin.
createdDate String Specifies the date on which the origin was created.
g2oKeys Origin.versions[].g2oKeys[] Specify the origin G2O key(s) name and value for multi account origin access. Multi Account Access enables you to allow Media Services Live streams defined in one account to be delivered by delivery configurations in other account(s). This is achieved by using manual access key(s) or G2O keys.
notes String Displays notes about the origin.
sslEnabled Boolean Specifies whether SSL is enabled for the origin.
version Integer Specifies the origin version.
Origin.versions[].g2oKeys[]: Specify the origin G2O key(s) name and value for multi account origin access. Multi Account Access enables you to allow Media Services Live streams defined in one account to be delivered by delivery configurations in other account(s). This is achieved by using manual access key(s) or G2O keys.
key String Specify the origin G2O key(s).
nonce String Enter a Name (up to 8 alphabets, numbers, or alphanumeric characters) for the G2O key to be generated.

PagingAndSorting

Specifies pagination and sorting of request data.

Download schema: PagingAndSortingDTO.json

Sample GET:

{
    "page": 1,
    "pageSize": 25,
    "sortKey": "name",
    "sortOrder": "ASC"
}

PagingAndSorting members

Member Type Required Description
page Integer Optionally specifies the number of pages. The default value is 1.
pageSize Integer 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 Optionally sorts the fields displayed based on the key that you specify. The default value is the modified date. You can sort based on the following enum values: name, id, format, cpcode, zone, origin_hostname, transcoding_id, status, dvrWindowInMin, createdDate, or modifiedDate.
sortOrder Enumeration Sorts the streams displayed by the order you specify (ASC for ascending or DESC for descending). The default value is DESC.

Errors

This section provides details on the data object that reflects 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 property is false. Also included is an error code and error message.

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 activation will be acted upon by the system.
400 Bad Request.
401 Unauthorized request.
402 Failed request.
403 Access is forbidden. The user provided does not have access to the requested object and/or operation.
404 Resource not found.
405 Method not allowed.
415 Unsupported Media Type
422 Unprocessable entity.
429 Too many requests.
500 Internal server error. Unexpected error.

Last modified: 12/6/2017