Learn more:

• Media Services Live

• Download this API’s RAML and JSON schema descriptors.

Overview

The Media Services Live (MSL) Stream Provisioning API lets you publish live streaming media content and retrieve it through the Akamai Intelligent Edge Platform or any content delivery network (CDN). These operations are targeted primarily for Over-the-top (OTT) applications, but can also be used for other live streaming events.

There are two main parts of the workflow:

• Publish - directly push content from encoders into liveOrigin™ through the Akamai ingest server.

• Delivery - pull the content that was earlier published into liveOrigin through a CDN.

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

Who should use this API

Use this API to set up and manage live media streaming events.

Get started

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

• Make sure that your contract includes MediaServicesLive4::MediaServicesLive4. Contact your Akamai representative to enable it for your account.

• You need different permissions to access API functions. You can manage permissions available in Control Center. Learn more about the access control model.

• Review Get Started with APIs for details on how to set up client tokens to access any Akamai API.

• To enable this API, choose the API service called 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.

• X-RateLimit-Next. An ISO 8601 timestamp that indicates when you can next make a request.

Once X-RateLimit-Remaining becomes 0, you get a 429 error the next time you make an API call. The response header contains X-RateLimit-Next, indicating when you can next make a request.

If you don’t 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 concepts

• Stream. A URL for a live streaming event. You can create a stream, get a list of streams, retrieve stream details, and edit or delete a stream. See the Stream object type for details.

• Origin. The source location for your live streaming media. You can directly push content from encoders into the origin through the Akamai ingest server, then pull the content through a CDN. See the Origin object type for details.

• Contract. Contains information about MSL contracts for your account. See the Contract object type for details.

• CDN providers. Returns a list of CDN providers. See the Cdn object type for details.

• CP codes. Displays the CP codes tied to the MSL contract. A CP code is a unique identifier for reporting, billing, and monitoring traffic served over the Akamai network. See the CpCode object type for details.

• Keys. Shared keys with partners enable authentication between the Origin Shield and the Adaptive Media Delivery (AMD) configuration. See Generate a key for details.

• Authentication. If you enable HTTP digest authentication for your stream, you can update the username and password combinations to prevent unauthorized access to your streaming media content. You’re limited to two authentication keys for a given stream, only one of which will be active. Before deleting a previous authentication set, ensure that you update your encoder to avoid inadvertently making your stream inaccessible. See Rotate HTTP digest authentication settings for details.

API workflow

Follow these steps to use the MSL Stream Provisioning API:

1. Create a new MSL origin and select 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:

• Run List CP codes to get the value of the CP code.

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

• Run Generate a key to obtain the key.

• Run List CDNs to obtain the CDN code.

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

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

API summary

Download the RAML descriptors for this API.

List streams

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

{
    "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,
            "encoderZone": "EUROPE",
            "backupStorageCpcode": null,
            "primaryStorageCpcode": 514779,
            "createdDate": "2017-11-14T07:06:25.794Z",
            "createdBy": "abcd",
            "modifiedBy": "def",
            "streamAuth": true,
            "provisionDetail": {
                "status": "PROVISIONED",
                "message": "Provisioned"
            }
        },
        {
            "id": 232123,
            "name": "DemoStream2",
            "format": "HLS",
            "cpcode": 987654,
            "originHostName": "demo-host2.akamaiorigin.net",
            "modifiedDate": "2017-05-25T06:30:48.215Z",
            "dvrWindowInMin": 5,
            "encoderZone": "EUROPE",
            "backupStorageCpcode": null,
            "primaryStorageCpcode": 558239,
            "createdDate": "2017-11-14T07:06:25.794Z",
            "createdBy": "abcd",
            "modifiedBy": "def",
            "streamAuth": false,
            "provisionDetail": {
                "status": "FAILED",
                "message": "Stream provisioning failed"
            }
        },
        {
            "id": 324453,
            "name": "DemoStream3",
            "format": "HLS",
            "cpcode": 123455,
            "originHostName": "demo-host3.akamaiorigin.net",
            "modifiedDate": "2017-05-25T06:13:13.436Z",
            "dvrWindowInMin": 9,
            "encoderZone": "EUROPE",
            "backupStorageCpcode": null,
            "primaryStorageCpcode": 678779,
            "createdDate": "2017-11-14T07:06:25.794Z",
            "createdBy": "abcd",
            "modifiedBy": "def",
            "streamAuth": true,
            "provisionDetail": {
                "status": "PENDING"
            }
        }
    ]
}

Create a stream

Provisions a new stream. To create an ingest stream using Media Services Live 4, you need to:

• Set up ingest for the stream.
• Set up archive for the stream. For details on the types of archive you can specify, see Archive stream members.
• 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 steps are complete, the stream status changes to PROVISIONED. If any of the steps fail, the stream status changes to FAILED. It takes two to three hours to provision a stream.

{
    "name": "Demostream",
    "contractId": "ABC-123",
    "format": "HLS",
    "cpcode": 123445,
    "ingestAccelerated": false,
    "encoderZone": "EUROPE",
    "backupEncoderZone": "AUSTRALIA",
    "isDedicatedOrigin": false,
    "activeArchiveDurationInDays": 2,
    "allowedIps": [
        "1.2.3.4"
    ],
    "additionalEmailIds": [
        "xyz@akamai1.com"
    ],
    "origin": {
        "hostName": "demo-host1"
    },
    "streamAuth": {
        "username": "ajones",
        "password": "123abc!",
        "algorithm": "SHA512"
    },
    "groupId": 1234
}

Location: /streams/123

Archive stream members

You can create a stream with these archive types:

• No archive
• Basic archive with automatic purge disabled
• Basic archive with automatic purge enabled
• Event purge
• Specific stream purge

This table shows the archive stream members you can use to create a stream with specific archive settings.

• ✗ indicates that you need not specify the option.
• ✓ indicates that you specify the option.

Get a stream

Retrieves detailed information about the requested stream.

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

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 members. If you try to edit any other member, the API returns a 400 error. If you want to update the HTTP digest authentication username, password, or expiryDate for a live stream, refer to these examples Rotate HTTP digest authentication settings.

{
    "id": 723456,
    "name": "DemostreamEdit",
    "format": "HLS",
    "cpcode": 123456,
    "ingestAccelerated": true,
    "password": 346789999,
    "dvrWindow": 10,
    "encoderZone": "US_EAST",
    "allowedIps": [
        "1.2.3.4",
        "2.5.6.7"
    ],
    "additionalEmailIds": [
        "xyz@akamai1.com",
        "efg@akamai.com"
    ],
    "origin": {
        "hostName": "demoHost.akamaiorigin.net"
    }
}

Rotate HTTP digest authentication settings

You can add authentication for a stream as shown:

{
  "id": 723456,
  "name": "DemostreamEdit",
  "format": "HLS",
  "cpcode": 123456,
  "ingestAccelerated": false,
  "dvrWindow": 10,
  "encoderZone": "US_EAST",
  "allowedIps": [
    "1.2.3.4",
    "2.5.6.7"
  ],
  "additionalEmailIds": [
    "xyz@akamai1.com",
    "efg@akamai.com"
  ],
  "origin": {
    "hostName": "demoHost.akamaiorigin.net"
  },
  "streamAuth": {
    "username": "ajones",
    "password": "123abc!",
    "algorithm": "MD5"
  }
}

If you want to rotate the authentication settings for a given stream, choose one of these options. You’re limited to two authentication keys for a stream, only one of which will be active.

Important: Make sure to update your encoder with the new authentication information within the auto-expiry time period. You’ll receive an Ingest Auth failure alert email if this expires.

Rotate the stream authentication settings and specify an expiration date in the payload:

{
  "id": 723456,
  "name": "DemostreamEdit",
  "format": "HLS",
  "cpcode": 123456,
  "ingestAccelerated": false,
  "dvrWindow": 10,
  "encoderZone": "US_EAST",
  "allowedIps": [
    "1.2.3.4",
    "2.5.6.7"
  ],
  "additionalEmailIds": [
    "xyz@akamai1.com",
    "efg@akamai.com"
  ],
  "origin": {
    "hostName": "demoHost.akamaiorigin.net"
  },
  "streamAuth": {
    "username": "newAuthSettings",
    "password": "123abc!",
    "algorithm": "MD5"
  },
  "streamAuthPrevious": {
    "expiryDate": "2020-10-02T23:59:59.999Z"
  }
}

Rotate the stream authentication settings without specifying an expiration date in the payload. By default, expiration is two days from the current time in UTC.

{
  "id": 723456,
  "name": "DemostreamEdit",
  "format": "HLS",
  "cpcode": 123456,
  "ingestAccelerated": false,
  "dvrWindow": 10,
  "encoderZone": "US_EAST",
  "allowedIps": [
    "1.2.3.4",
    "2.5.6.7"
  ],
  "additionalEmailIds": [
    "xyz@akamai1.com",
    "efg@akamai.com"
  ],
  "origin": {
    "hostName": "demoHost.akamaiorigin.net"
  },
  "streamAuth": {
    "username": "newAuthSettings",
    "password": "123abc!",
    "algorithm": "MD5"
  }
}

Once you’ve successfully rotated the initial authentication settings, you can subsequently edit them in one of these ways. Issue separate PUT requests for each operation.

Edit the current stream authentication settings by retaining the previous authentication settings:

{
  "id": 723456,
  "name": "DemostreamEdit",
  "format": "HLS",
  "cpcode": 123456,
  "ingestAccelerated": false,
  "dvrWindow": 10,
  "encoderZone": "US_EAST",
  "allowedIps": [
    "1.2.3.4",
    "2.5.6.7"
  ],
  "additionalEmailIds": [
    "xyz@akamai1.com",
    "efg@akamai.com"
  ],
  "origin": {
    "hostName": "demoHost.akamaiorigin.net"
  },
  "streamAuth": {
    "username": "newAuthSettingsEdited",
    "password": "123abc!",
    "algorithm": "SHA256"
  },
  "streamAuthPrevious": {
    "retain": true
  }
}

Edit the previous stream authentication setting’s expiration date, but retain the current authentication settings:

{
  "id": 723456,
  "name": "DemostreamEdit",
  "format": "HLS",
  "cpcode": 123456,
  "ingestAccelerated": false,
  "dvrWindow": 10,
  "encoderZone": "US_EAST",
  "allowedIps": [
    "1.2.3.4",
    "2.5.6.7"
  ],
  "additionalEmailIds": [
    "xyz@akamai1.com",
    "efg@akamai.com"
  ],
  "origin": {
    "hostName": "demoHost.akamaiorigin.net"
  },
  "streamAuth": {
    "username": "newAuthSettingsEdited",
    "algorithm": "SHA256"
  },
  "streamAuthPrevious": {
    "expiryDate": "2020-10-06T23:59:59.999Z"
  }
}

Delete the previous stream authentication settings. Will only take effect, if multiple keys are active.

{
  "id": 723456,
  "name": "DemostreamEdit",
  "format": "HLS",
  "cpcode": 123456,
  "ingestAccelerated": false,
  "dvrWindow": 10,
  "encoderZone": "US_EAST",
  "allowedIps": [
    "1.2.3.4",
    "2.5.6.7"
  ],
  "additionalEmailIds": [
    "xyz@akamai1.com",
    "efg@akamai.com"
  ],
  "origin": {
    "hostName": "demoHost.akamaiorigin.net"
  },
  "streamAuth": {
    "username": "newAuthSettingsEdited",
    "algorithm": "SHA256"
  },
  "streamAuthPrevious": {
    "delete": true
  }
}

Delete and disable all stream authentication settings, including active as well as prior settings:

{
  "id": 723456,
  "name": "DemostreamEdit",
  "format": "HLS",
  "cpcode": 123456,
  "ingestAccelerated": false,
  "dvrWindow": 10,
  "encoderZone": "US_EAST",
  "allowedIps": [
    "1.2.3.4",
    "2.5.6.7"
  ],
  "additionalEmailIds": [
    "xyz@akamai1.com",
    "efg@akamai.com"
  ],
  "origin": {
    "hostName": "demoHost.akamaiorigin.net"
  },
  "streamAuth": {
    "delete": true
  }
}

Note: During a password rotation period, two sets of authentication keys may be active at the same time. The server validates all incoming authorization headers against both sets, and issues a successful authorization response if validation of any incoming authorization header succeeds against any one of the active credentials.

Remove a stream

Deletes the specified stream. If you delete an archived stream, but set purgeContent=false the stream will be permanently deleted, but any archived content saved on NetStorage will continue to incur billing. If you set purgeContent=true, the stream will be permanently deleted and any archived content saved on NetStorage for this stream will also be deleted and cannot be restored.

List live origins

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

[
    {
        "status": "PENDING",
        "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"
        }
    },
    {
        "status": "PROVISIONED",
        "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"
        }
    }
]

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.

{
    "contractId": "C-Contract-123",
    "hostName": "demohost",
    "cpcode": 123456,
    "encoderZone": "US_EAST",
    "backupEncoderZone": "EUROPE",
    "thirdPartyCdnCpcode": 654321,
    "emailIds": [
        "email1",
        "email2"
    ],
    "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"
        }
    ],
    "groupId": 1234
}

Location: /api/v2/origins/123

Get an origin

Retrieves detailed information about the requested origin.

{
    "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": "ajones",
    "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"
        }
    ]
}

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.

{
    "id": 101,
    "emailIds": [
        "email1",
        "email2"
    ],
    "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"
        }
    ]
}

Remove an origin

Deletes the specified origin.

List CP codes per origin

Fetches available CP codes for a new origin.

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

List contracts

Fetch MSL contracts.

[
    {
        "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
    }
]

List CDNs

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

[
    {
        "code": "dn002",
        "name": "L3"
    },
    {
        "code": "dn003",
        "name": "Fastly"
    },
    {
        "code": "dn004",
        "name": "Cloudfront"
    }
]

Generate a key

Specify either an AKAMAI or THIRD_PARTY key format.

{
    "key": "Ab+DgsTEL6t5Trcv5KYUZw=="
}

List CP codes

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

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

Create a CP code

Creates a new MSL CP code. You need a CP code to create a stream or an origin.

{
    "name": "Cpcode 1",
    "contractId": "A-BCDE12-3"
}

{
    "id": 12345,
    "name": "Cpcode 1",
    "contractId": "A-BCDE12-3"
}

List VOD origins

List all of the VOD origins.

[
    {
        "cpcode": 1234,
        "name": "SG-1-1234",
        "streamCount": 2
    },
    {
        "cpcode": 1235,
        "name": "SG-1-1235",
        "streamCount": 10
    }
]

List publishing locations

Get valid encoder locations.

[
    {
        "location": "EUROPE",
        "code": "001",
        "netstorageZone": "europe",
        "geoCountries": [
            {
                "name": "DE",
                "states": [
                    {
                        "name": "HE",
                        "cities": [
                            {
                                "name": "FRANKFURT"
                            }
                        ]
                    }
                ]
            },
            {
                "name": "NL",
                "states": [
                    {
                        "name": "N/A",
                        "cities": [
                            {
                                "name": "SCHIPHOL"
                            },
                            {
                                "name": "AMSTERDAM"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "NORTH_AMERICA",
        "code": "002",
        "netstorageZone": "us",
        "geoCountries": [
            {
                "name": "US",
                "states": [
                    {
                        "name": "CA",
                        "cities": [
                            {
                                "name": "LOSANGELES"
                            },
                            {
                                "name": "SANJOSE"
                            }
                        ]
                    },
                    {
                        "name": "IL",
                        "cities": [
                            {
                                "name": "CHICAGO"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "INDIA",
        "code": "012",
        "netstorageZone": "asia",
        "geoCountries": [
            {
                "name": "IN",
                "states": [
                    {
                        "name": "N/A",
                        "cities": [
                            {
                                "name": "MUMBAI"
                            },
                            {
                                "name": "CHENNAI"
                            },
                            {
                                "name": "BANGALORE"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "AUSTRALIA",
        "code": "010",
        "netstorageZone": "AU",
        "geoCountries": [
            {
                "name": "AU",
                "states": [
                    {
                        "name": "N/A",
                        "cities": [
                            {
                                "name": "SYDNEY"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "TAIWAN",
        "code": "016",
        "netstorageZone": "asia"
    },
    {
        "location": "MEXICO",
        "code": "015",
        "netstorageZone": "us"
    }
]

Data

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

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

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,
    "encoderZone": "EUROPE",
    "backupEncoderZone": "AUSTRALIA",
    "createdDate": "2017-11-14T07:06:25.794Z",
    "modifiedDate": "2017-11-14T07:20:12.359Z",
    "createdBy": "abc",
    "modifiedBy": "def",
    "primaryPublishingUrl": "test1.akamaientrypoint.net",
    "backupPublishingUrl": "test2.akamaientrypoint.net",
    "isDedicatedOrigin": false,
    "allowedIps": [],
    "events": [],
    "additionalEmailIds": [
        "xyz@akamai1.com"
    ],
    "origin": {
        "hostName": "demo-host1.akamaiorigin.net"
    },
    "backupOrigin": {
        "hostName": "demo-host2.akamaiorigin.net"
    },
    "provisionDetail": {
        "streamId": 745645,
        "status": "PENDING"
    },
    "storageGroup": {
        "cpcode": 125334
    },
    "backupStorageGroup": {
        "cpcode": 124
    },
    "streamAuth": {
        "username": "asmith",
        "algorithm": "SHA256"
    }
}

Stream members

Origin

Configures a Media Services Live origin for the stream and lets you to 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": "ajones",
    "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

Contract

The contract ID to associate with the origin. The system filters the CP codes based on the contract ID that you specify. It associates the NetStorage CP code, if there is one, with the same contract as the ingest CP code.

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

Cdn

Contains information about the CDN.

Download schema: CdnResourceDTO.json

Sample GET response:

[
    {
        "code": "dn002",
        "name": "L3"
    },
    {
        "code": "dn003",
        "name": "Fastly"
    },
    {
        "code": "dn004",
        "name": "Cloudfront"
    }
]

Cdn members

CpCode

Specifies the origin CP code.

Download schema: CpcodeDTO.json

Sample GET response:

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

CpCode members

PublishingLocation

Specifies details about the location where the stream is published.

Download schema: PublishingLocationDTO.json

Sample GET response:

[
    {
        "location": "EUROPE",
        "code": "001",
        "netstorageZone": "europe",
        "geoCountries": [
            {
                "name": "DE",
                "states": [
                    {
                        "name": "HE",
                        "cities": [
                            {
                                "name": "FRANKFURT"
                            }
                        ]
                    }
                ]
            },
            {
                "name": "NL",
                "states": [
                    {
                        "name": "N/A",
                        "cities": [
                            {
                                "name": "SCHIPHOL"
                            },
                            {
                                "name": "AMSTERDAM"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "NORTH_AMERICA",
        "code": "002",
        "netstorageZone": "us",
        "geoCountries": [
            {
                "name": "US",
                "states": [
                    {
                        "name": "CA",
                        "cities": [
                            {
                                "name": "LOSANGELES"
                            },
                            {
                                "name": "SANJOSE"
                            }
                        ]
                    },
                    {
                        "name": "IL",
                        "cities": [
                            {
                                "name": "CHICAGO"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "INDIA",
        "code": "012",
        "netstorageZone": "asia",
        "geoCountries": [
            {
                "name": "IN",
                "states": [
                    {
                        "name": "N/A",
                        "cities": [
                            {
                                "name": "MUMBAI"
                            },
                            {
                                "name": "CHENNAI"
                            },
                            {
                                "name": "BANGALORE"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "AUSTRALIA",
        "code": "010",
        "netstorageZone": "AU",
        "geoCountries": [
            {
                "name": "AU",
                "states": [
                    {
                        "name": "N/A",
                        "cities": [
                            {
                                "name": "SYDNEY"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "location": "TAIWAN",
        "code": "016",
        "netstorageZone": "asia"
    },
    {
        "location": "MEXICO",
        "code": "015",
        "netstorageZone": "us"
    }
]

PublishingLocation members

VodOrigin

Contains information about the origin for the VOD streams.

Download schema: VODOriginDTO.json

Sample GET response:

[
    {
        "cpcode": 1234,
        "name": "SG-1-1234",
        "streamCount": 2
    },
    {
        "cpcode": 1235,
        "name": "SG-1-1235",
        "streamCount": 10
    }
]

VodOrigin members

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 in which the ok member is false. It also includes an error code and error message.

This 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 this set of HTTP status codes for both success and failure scenarios: