
- Overview
- Resources
- API summary
- List streams
- Create a stream
- Get a stream
- Update a stream
- Remove a stream
- List live origins
- Create a new origin
- Get an origin
- Update an origin
- Remove an origin
- List CP codes per origin
- List contracts
- List CDNs
- Generate a key
- List CP codes
- Create a CP code
- List VOD origins
- List publishing locations
- Data
- Errors
Media Services Live Stream Provisioning API v2
Push live content from encoders and have it retrieved for delivering either through Akamai or any content delivery network.
Learn more:
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
andpassword
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:
Create a new MSL origin and select features such as multi-account and multi-CDN.
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.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.
Operation | Method | Endpoint |
---|---|---|
List streams | GET | /config-media-live/ |
Create a stream | POST | /config-media-live/ |
Get a stream | GET | /config-media-live/ |
Update a stream | PUT | /config-media-live/ |
Remove a stream | DELETE | /config-media-live/ |
List live origins | GET | /config-media-live/ |
Create a new origin | POST | /config-media-live/ |
Get an origin | GET | /config-media-live/ |
Update an origin | PUT | /config-media-live/ |
Remove an origin | DELETE | /config-media-live/ |
List CP codes per origin | GET | /config-media-live/ |
List contracts | GET | /config-media-live/ |
List CDNs | GET | /config-media-live/ |
Generate a key | GET | /config-media-live/ |
List CP codes | GET | /config-media-live/ |
Create a CP code | POST | /config-media-live/ |
List VOD origins | GET | /config-media-live/ |
List publishing locations | GET | /config-media-live/ |
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/
Sample: /config-media-live/
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 don’t 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,
"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"
}
}
]
}
You can use these parameters to paginate and sort the response:
page
specifies the number of pages. The default value is 1.pageSize
indicates the number of data points that are displayed per page. The default is to display all data if you don’t specify the page size.sortKey
sorts the fields based on:name
,id
,format
,cpcode
,encoderZone
,originHostName
,isTranscodingEnabled
,streamStatus
,dvrWindowInMin
,createdDate
, ormodifiedDate
.sortOrder
sorts the list of streams, either inASC
for ascending order, orDESC
for descending order. The default value isDESC
.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. 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.
POST /config-media-live/
Sample: /config-media-live/
Content-Type: application/json
Request body:
{
"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"
}
}
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
cloneInternalSettingsFromStreamId |
Integer | 175589 |
Specifies the stream to clone the internal settings from. |
Status 202
Headers:
Location: /streams/123
Run List CP codes to get the value of the
cpcode
.Run List contracts to get the value of the
contractId
.Form a Stream object for the request.
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.
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.
dvrWindow | stream |
active |
events | Create |
Stream |
|
---|---|---|---|---|---|---|
✗ or positive integer value | ✗ | ✗ | ✗ | 202 | No archive | |
–1 | ✗ | ✗ | ✗ | 202 | Basic archive with automatic purge disabled (unlimited archive) | |
–1 | ✗ | ✗ | ✓ | 202 | Event level purge | |
positive integer | ✗ | ✗ | ✓ | 400 | ||
–1 | ✓ | ✗ | ✗ | 202 | Stream level purge | |
positive integer | ✓ | ✗ | ✗ | 400 | ||
–1 | ✓ | ✗ | ✓ | 400 | ||
✗ | ✗ | ✓ | ✗ | 202 | Advanced archive | |
✓ | ✗ | ✓ | ✓ | 400 | ||
✗ | ✓ | ✓ | ✗ | 400 | ||
✗ | ✗ | ✓ | ✓ | 400 |
Get a stream
Retrieves detailed information about the requested stream.
GET /config-media-live/
Sample: /config-media-live/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path 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,
"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"
}
}
Run List streams to get the value of the
streamId
URL parameter.Make a GET request to
/config-media-live/
.v2/ 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
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.
PUT /config-media-live/
Sample: /config-media-live/
Content-Type: application/json
Request body:
{
"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"
}
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
streamId |
Integer | 50005 |
Unique identifier for each stream. |
Status 202
Run List streams to get the value of the
streamId
URL parameter.Make a GET request to
/config-media-live/
.v2/ msl-origin/ streams/ {streamId} Modify the Stream response object for your request.
PUT the object to
/config-media-live/
.v2/ msl-origin/ streams/ {streamId}
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.
DELETE /config-media-live/
Sample: /config-media-live/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
streamId |
Integer | 50005 |
Unique identifier for each stream. |
Optional query parameters | |||
purgeContent |
Boolean | true |
This value determines whether to delete archived content on NetStorage. |
Status 200
Run List streams to get the value of the
streamId
URL parameter.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/
Sample: /config-media-live/
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:
[
{
"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"
}
}
]
Run List streams to get the value of the
encoderLocation
andcpcode
query parameters.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/
Content-Type: application/json
Request body:
{
"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"
}
]
}
Status 202
Headers:
Location: /api/v2/origins/123
Create a Media Services Live Origin object for the request.
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/
Sample: /config-media-live/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
originId |
Integer | 123456 |
Unique identifier for each origin. |
Status 200
application/json
Object type: Origin
Download schema: OriginDetailDTOV2.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": "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"
}
]
}
Run List live origins to get the value of the
originId
URL parameter.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/
Sample: /config-media-live/
Content-Type: application/json
Request body:
{
"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"
}
]
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
originId |
Integer | 123456 |
Unique identifier for each origin. |
Status 202
Run Get an origin to obtain the value of the
originId
URL parameter.Make a PUT request to
/config-media-live/
.v2/ msl-origin/ origins/ {originId}
Remove an origin
Deletes the specified origin.
DELETE /config-media-live/
Sample: /config-media-live/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
originId |
Integer | 123456 |
Unique identifier for each origin. |
Status 202
List CP codes per origin
Fetches available CP codes for a new origin.
GET /config-media-live/
Sample: /config-media-live/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
type |
Enumeration | AKAMAI |
Specifies whether to retrieve AKAMAI or THIRD_PARTY CP codes. |
Status 200
application/json
Response body:
[
{
"id": 321234,
"name": "Test",
"contracts": [
{
"contractId": "Z-AAAVOB"
}
]
}
]
List contracts
Fetch MSL contracts.
GET /config-media-live/
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
}
]
- Make a GET request to
/config-media-live/
.v2/ msl-origin/ contracts
The response yields a list of contracts associated with the account.
List CDNs
Fetch predefined list of CDN providers. You can configure your MSL origin to include multiple CDN providers.
GET /config-media-live/
Status 200
application/json
Response body:
[
{
"code": "dn002",
"name": "L3"
},
{
"code": "dn003",
"name": "Fastly"
},
{
"code": "dn004",
"name": "Cloudfront"
}
]
- 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/
Sample: /config-media-live/
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=="
}
Specify the type as
AKAMAI
if you are using an Akamai CDN, orTHIRD-PARTY
if you are using a third-party CDN.Make a GET request to
/config-media-live/
.v2/ msl-origin/ generate-key{?type}
The response generates an authentication token for the stream.
List CP codes
Obtains the CP code based on the type. You need a CP code to create a stream.
GET /config-media-live/
Sample: /config-media-live/
Parameter | Type | Sample | Description |
---|---|---|---|
Required query parameters | |||
type |
Enumeration | INGEST |
Specify the type of CP code. Specify INGEST to obtain the INGEST CP codes, DELIVERY for the delivery CP codes, and STORAGE for the storage CP codes. |
Optional query parameters | |||
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"
}
]
}
]
- Make a GET request to
/config-media-live/
.v2/ msl-origin/ cpcodes{?type}
The response yields a list of CP codes associated with the account.
Create a CP code
Creates a new MSL CP code. You need a CP code to create a stream or an origin.
POST /config-media-live/
Content-Type: application/json
Request body:
{
"name": "Cpcode 1",
"contractId": "A-BCDE12-3"
}
Status 202
application/json
Response body:
{
"id": 12345,
"name": "Cpcode 1",
"contractId": "A-BCDE12-3"
}
List VOD origins
List all of the VOD origins.
GET /config-media-live/
Sample: /config-media-live/
Parameter | Type | Sample | Description |
---|---|---|---|
Required query parameters | |||
encoderLocation |
String | EUROPE |
Specifies the geographical region where the VOD origin is located. |
Status 200
application/json
Response body:
[
{
"cpcode": 1234,
"name": "SG-1-1234",
"streamCount": 2
},
{
"cpcode": 1235,
"name": "SG-1-1235",
"streamCount": 10
}
]
List publishing locations
Get valid encoder locations.
GET /config-media-live/
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"
}
]
- Make a GET request to
/config-media-live/
.v2/ msl-origin/ publishing-locations
The response yields a list of geographical 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.
This section’s data schema tables 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,
"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
Member | Type | POST | GET | PUT | Description | |||
---|---|---|---|---|---|---|---|---|
Stream : Encapsulates stream configuration and version information. You can list, create, edit, delete, and get details of streams. |
||||||||
active |
Integer | ○ | ○ | ○ | Specify from 1 to 31 to archive your active content. 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. |
|||
additional |
Array | ○ | ○ | ○ | Specify email addresses for people who should receive the stream configuration details and status notifications. | |||
allowedIps |
Array | ○ | ○ | ○ | Specify the IP addresses for your encoder. You can enter up to 50 IP addresses separated by commas. | |||
backup |
Stream. |
○ | ○ | ○ | Specify details about the backup stream direct connect settings. | |||
backup |
String | ○ | ○ | ✗ | Specify the geographical location of your backup encoder. | |||
backupOrigin |
Origin | ✗ | ○ | ✗ | Specify the backup origin hostname for the stream. | |||
backup |
String | ✗ | ○ | ✗ | Specify the encoder’s backup publishing URL. For example, if the stream format is HLS, streamId is 50002, and event is test79, the backup publishing URL is http://b-ep50002.i.akamaientrypoint.net/50002-b/test79 . |
|||
backup |
Stream. |
○ | ○ | ✗ | Specifies the details about the secondary storage group override. | |||
contractId |
String | ○ | ○ | ○ | Identifies the contract associated with the stream. The system filters the ingest CP code based on the contract ID that you specify. If you create a NetStorage CP code, it is associated with the same contract as the ingest CP code. If you do not specify a contract ID, the system uses the first valid contract. | |||
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 | ✗ | ○ | ✗ | The Control Center username for the person who created the stream. | |||
createdDate |
String | ✗ | ○ | ✗ | The date the stream was created. | |||
dvrWindow |
Integer | ○ | ○ | ○ | The length of time the streaming content is available in archive, 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. |
○ | ○ | ○ | 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 identifier for the stream. | |||
ingest |
Boolean | ○ | ○ | ○ | Specify whether to use the Media Services Live Ingest Acceleration feature. If you select true , enter a password in the Password field. 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. |
|||
is |
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 uses resource group to identify your company. |
|||
modifiedBy |
String | ✗ | ○ | ✗ | The Control Center username who edited the stream. | |||
modifiedDate |
String | ✗ | ○ | ✗ | The date the stream was changed or updated. | |||
name |
String | ○ | ○ | ○ | The name of the stream. 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 | ○ | ○ | ○ | Specifies the password for authentication. | |||
primary |
Stream. |
○ | ○ | ○ | Specify details about the primary stream direct connect settings. | |||
primary |
String | ✗ | ○ | ✗ | Specify the encoder’s primary publishing URL. For example, if the stream format is HLS, streamId is 50002, and event is test79, the primary publishing URL is http://p-ep50002.i.akamaientrypoint.net/50002/test79 . |
|||
provisionDetail |
Stream. |
✗ | ○ | ✗ | Specify details about the stream provisioning. | |||
storageGroup |
Stream. |
○ | ○ | ✗ | Specifies the details about the primary storage group override. | |||
streamAuth |
Stream. |
○ | ○ | ○ | Specifies details about the stream authentication settings. | |||
stream |
Stream. |
✗ | ✗ | ○ | Specify details about the stream authentication settings. | |||
stream |
Integer | ○ | ○ | ○ | Specify the archive duration value to purge the content for all the events. You need this value only when specifying the dvrWindow . You don’t need it when specifying activeArchiveDurationInDays . |
|||
vodOrigin |
Stream. |
○ | ○ | ○ | Enables you to record the video on demand. This option is available only for HLS and DASH streams and applies only when you include the activeArchiveDurationInDays member. You can include it if you have MediaServicesLive4::LiveToVOD or MediaServicesLive4::LiveToVodBeta2 in your contract. |
|||
Stream.backupDirectConnectSettings : Specify details about the backup stream direct connect settings. |
||||||||
locations |
Array | ○ | ○ | ○ | List of direct connect locations selected. | |||
penalty |
Integer | ○ | ○ | ○ | Specify the penalty value for the stream. | |||
pingPointIp |
String | ○ | ○ | ○ | Specify the ping point ipv4 address used to determine the health of path between the encoder and Akamai entrypoint. |
|||
Stream.backupStorageGroup : Specifies the details about the secondary storage group override. |
||||||||
cpcode |
Integer | ○ | ○ | ✗ | The storage group’s Content Provider code. | |||
isNew |
Boolean | ○ | ✗ | ✗ | Specify true or false to indicate whether a new storage CP code needs to be created as a part of stream creation. |
|||
name |
String | ○ | ✗ | ✗ | The name that identifies the Content Provider code. | |||
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 for the event that you want to delete from storage. | |||
event |
String | ○ | ○ | ○ | Specify the name of the event you want to purge. | |||
Stream.primaryDirectConnectSettings : Specify details about the primary stream direct connect settings. |
||||||||
locations |
Array | ○ | ○ | ○ | List of direct connect locations selected. | |||
penalty |
Integer | ○ | ○ | ○ | Specify the penalty value for the stream. | |||
pingPointIp |
String | ○ | ○ | ○ | Specify the ping point ipv4 address used to determine the health of path between the encoder and Akamai entrypoint. |
|||
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 identifier for your stream. | |||
Stream.storageGroup : Specifies the details about the primary storage group override. |
||||||||
cpcode |
Integer | ○ | ○ | ✗ | The storage group’s Content Provider code. | |||
isNew |
Boolean | ○ | ✗ | ✗ | Specify true or false to indicate whether a new storage CP code needs to be created as a part of stream creation. |
|||
name |
String | ○ | ✗ | ✗ | The name that identifies the Content Provider code. | |||
Stream.streamAuth : Specifies details about the stream authentication settings. |
||||||||
algorithm |
Enumeration | ○ | ○ | ○ | The algorithm used to generate the hash for authentication. Specify SHA256 , SHA512 , SHA512_256 , or MD5 . SHA256 is the Secure Hash Algorithm, which is a type of cryptographic hash function that generates a 256-bit (32-byte) hash. A cryptographic hash is like a signature for a text or a data file. SHA512 is a cryptographic hash function that when applied to the provided input results in a 128-digit hexadecimal number that is highly unlikely to match the value produced for a different input. The MD5 message-digest algorithm is a hash function producing a 128-bit hash value. It is less secure than SHA256 . |
|||
delete |
Boolean | ✗ | ✗ | ○ | Enable to delete the previous HTTP digest authentication settings. This will only take effect if multiple keys are active. | |||
password |
String | ○ | ✗ | ○ | Specify the password for authentication. | |||
username |
String | ○ | ○ | ○ | Specify the username for authentication. | |||
Stream.streamAuthPrevious : Specify details about the stream authentication settings. |
||||||||
delete |
Boolean | ✗ | ✗ | ○ | Enable to delete the previous HTTP digest authentication settings. | |||
expiryDate |
String | ✗ | ✗ | ○ | The expiration date for the previous HTTP digest authentication settings in UTC format. | |||
retain |
Boolean | ✗ | ✗ | ○ | Enable to retain the previous HTTP digest authentication settings. | |||
Stream.vodOrigin : Enables you to record the video on demand. This option is available only for HLS and DASH streams and applies only when you include the activeArchiveDurationInDays member. You can include it if you have MediaServicesLive4::LiveToVOD or MediaServicesLive4::LiveToVodBeta2 in your contract. |
||||||||
cpcode |
Integer | ○ | ○ | ○ | The CP code of an existing VOD origin. This is the NetStorage CP code that is used to archive the live recordings. The CP code name is mandatory when you create a new VOD origin, but its value is optional. | |||
name |
String | ○ | ○ | ○ | Name of your new VOD origin. |
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
Member | Type | POST | GET | PUT | Description | |||
---|---|---|---|---|---|---|---|---|
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). |
||||||||
activeVersion |
Integer | ✗ | ○ | ✗ | Specify the version of the origin that is enabled. | |||
amdProperties |
Origin. |
✗ | ○ | ✗ | AMD properties assigned to this origin in the current account. | |||
backup |
String | ○ | ○ | ✗ | Specify the backup encoder’s geographical location. | |||
backupHostName |
String | ✗ | ○ | ✗ | Specify a backup hostname for the origin. | |||
contractId |
String | ○ | ✓ | ✗ | Specify the contract ID to assign to the origin. The system filters CP codes based on the contract ID that you specify. If there is a NetStorage CP code, the system associates it with the same contract as the ingest CP code. | |||
cpcode |
Integer | ○ | ✓ | ✗ | Select the Media Services Live CP code. You use CP codes for reporting, billing, and monitoring traffic served over the intelligent edge platform. | |||
emailIds |
Array | ○ | ✗ | ○ | Specify the email addresses to receive details and status notifications for the live stream origin. | |||
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. | |||
is |
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 username of the person who changed the origin. | |||
modifiedDate |
String | ✗ | ○ | ✗ | Specify the date on which the origin was modified. | |||
sharedKeys |
Origin. |
○ | ✓ | ○ | 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 . |
|||
third |
Integer | ○ | ○ | ✗ | CP code to identify the third party CDN. | |||
Origin.amdProperties[] : AMD properties assigned to 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. |
✗ | ○ | ✗ | AMD properties assigned to 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 | ○ | ○ | ○ | Predefined code to identify 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. | |||
guid |
String | ○ | ○ | ○ | Automatically generated GUI ID for the CDN. | |||
hostName |
String | ✗ | ○ | ○ | Specify the hostname for the CDN. | |||
key |
String | ○ | ○ | ○ | Automatically 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. | |||
previous |
String | ✗ | ○ | ○ | Displays the expiration 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 assigned to 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 |
---|---|---|---|
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). |
|||
accountId |
String | ○ | Customer account ID. |
childContractIds |
Array, Null | ○ | Value is null if no child contract ID is assigned to the contract. |
contractId |
String | ○ | Specify the contract ID to assign to 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 assigned to the contract. |
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
Member | Type | Required | Description |
---|---|---|---|
Cdn : Contains information about the CDN. |
|||
code |
String | ○ | Predefined code to identify the CDN. |
name |
String | ○ | Name to identify the CDN. |
CpCode
Specifies the origin CP code.
Download schema:
CpcodeDTO.json
Sample GET response:
[
{
"id": 321234,
"name": "Test",
"contracts": [
{
"contractId": "Z-AAAVOB"
}
]
}
]
CpCode members
Member | Type | Required | Description |
---|---|---|---|
CpCode : Specifies the origin CP code. |
|||
contracts |
Cp |
○ | CP code identifier. |
id |
Integer | ○ | CP code that you can use to create the origin. |
isUsed |
Boolean | ○ | Indicates whether the CP code is assigned to 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 where 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 |
---|---|---|---|
PublishingLocation : Specifies details about the location where the stream is published. |
|||
code |
String | ○ | Specifies an identifier for the location where the stream is published. |
location |
String | ○ | Specifies the geographical location where the stream is published. |
netstorageZone |
String | ○ | Specifies the NetStorage zone location you can use to replicate your content. |
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
Member | Type | Required | Description |
---|---|---|---|
VodOrigin : Contains information about the origin for the VOD streams. |
|||
cpcode |
Integer | ○ | CP code identifier for the VOD origin. |
name |
String | ○ | Name to identify the VOD origin. |
streamCount |
Integer | ○ | Number of VOD streams. |
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:
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. In addition to a wide range of issues that can occur when parsing and validating the request, this could indicate that invalid stream authentication settings were passed. See Rotate HTTP digest authentication settings. |
401 | Unauthorized request. |
402 | Failed request. |
403 | Access is forbidden. The client 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. |