Live Archive Management API v1

If using Media Services Live v4, this API lets you list, modify, and manage your live archives.

Learn more:


Overview

Media Services Live 4 lets you archive live streams in HLS and DASH formats for use as video on demand (VOD) content. You can use the Live Archive Management (LAM) API to do multiple things:

  • Get details about the content you archived.

  • Understand all the objects that are part of an archive or endpoint.

  • Gather specific information from an archive for use in a URL that’ll serve as a “live clip.”

  • Use the Live Clipping export functionality to generate physical VOD assets from your live archives.

  • Delete an endpoint and all the objects belonging to that endpoint.

Get started

These are the prerequisites to get you started:

  • Ensure that your contract includes MediaServicesLive4::MediaServicesLive4.

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

  • To enable this API, choose the API service named MSL4 Live Archive APIs, and set the access level to READ-WRITE.

You need “Advanced Archives”

You need to enable Advanced Archive for your MSL streams to generate the archives that you manage with this API.

You need the “streamId”

Several operations require the unique, numeric streamId that Akamai assigns to a stream when you generate it.

  • You can run the list streams operation in the Media Services Live Stream Provisioning API, and store the id value for the desired stream.

  • You can view your streams in the Media Services Live 4 interface in Akamai Control Center. Note the value listed as the (Stream ID).

Concepts

To run this API, you need to familiarize yourself with the following concepts that the API represents in its URL resources and exchanges as data:

  • Archives: An archive is a live encoding session that Akamai stores for up to 31 days. Sessions run from the time at which the encoder starts publishing an event until an end signal specified by HLS or DASH-IF standards. For example, an EXT-X-ENDLIST tag may signal the end of an event in a media playlist.

  • Endpoints: An endpoint represents the URL path of any object ingested in Akamai for a specific stream. They have a near one-to-one correspondence to the way the encoder publishes objects of a stream into Akamai.

  • VOD Asset: A physical on demand video asset that you generate from a live archive and store in Akamai NetStorage. We also refer to this as Live-to-VOD Export.

NOTE: While this documentation lists the API’s URLs as endpoints, the API itself allows access to resources of the same name. These endpoints refer to URL server paths that contain media file assets.

These examples show the endpoints for different objects.

Object Endpoint
/hls/708976/helloworld/master.m3u8 708976/helloworld/master.m3u8
/hls/708976/helloworld/bitrate_500K/playlist_500.m3u8 708976/helloworld/bitrate_500K/playlist_500.m3u8
/hls/708976/bitrate_500K/dir1/segment_101.ts 708976/bitrate_500K/dir1

Sample usage: Create a live-to-VOD clip

You can use the LAM API to view your archives and gather specific information that you can use to generate a live-to-VOD clip:

  1. List Archives to determine the archives that have been published on a stream ID.

  2. Store the streamId, archiveStartTime and archiveEndTime for the relevant archive.

  3. Use the stored values to generate the clip.

Resources

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

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List archives GET /live-archive/v1/streams/{streamId}/archives{?startTime,endTime}
List endpoints GET /live-archive/v1/streams/{streamId}/endpoints
Remove objects DELETE /live-archive/v1/streams/{streamId}/endpoints/{endpoint}
Create a VOD asset POST /live-archive/v1/vod/
Get VOD status GET /live-archive/v1/vod/{EID}

List archives

Lists all archives, or optionally those created within a specified time range.

GET /live-archive/v1/streams/{streamId}/archives{?startTime,endTime}

Sample: /live-archive/v1/streams/609993/archives?startTime=1524997000&endTime=1524997933

Parameter Type Sample Description
URL path parameters
streamId Integer 609993 Uniquely identifies the stream from which this archive derives.
Optional query parameters
endTime Integer 1524997933 End time of the required time range in Unix epoch time.
startTime Integer 1524997000 Start time of the required time range in Unix epoch time.

Status 200 application/json

Object type: Archives

Download schema: archives.json

Response body:

{
    "archives": [
        {
            "name": "master.m3u8",
            "uri": "609993/1523371274.347/master.m3u8",
            "archiveStartTime": "1523371274",
            "archiveEndTime": "1523371284",
            "manifestUpdateTimes": []
        },
        {
            "name": "master.m3u8",
            "uri": "609993/1523371482.096/master.m3u8",
            "archiveStartTime": "1523371482",
            "archiveEndTime": "0",
            "manifestUpdateTimes": [
                1523371492,
                1523371502
            ]
        }
    ]
}
  1. Get the unique streamId assigned to the applicable stream.

  2. Determine an appropriate startTime and endTime time range using UNIX epoch time.

  3. Make a GET request to /live-archive/v1/streams/{streamId}/archives{?startTime,endTime}.

  4. The operation responds with an Archives object.

List endpoints

Lists all the endpoints per stream.

GET /live-archive/v1/streams/{streamId}/endpoints

Sample: /live-archive/v1/streams/609993/endpoints

Parameter Type Sample Description
URL path parameters
streamId Integer 609993 Uniquely identifies the stream from which this archive derives.

Status 200 application/json

Object type: Endpoints

Download schema: endpoints.json

Response body:

{
    "endpoints": [
        "609993/l2v_no_timestamp3/bitrate_500k.m3u8",
        "609993/l2v_no_timestamp3",
        "609993/l2v_no_timestamp7",
        "609993/l2v_no_timestamp7/bitrate_1500k.m3u8",
        "609993/streamcat",
        "609993/streamcat123abc"
    ]
}
  1. Get the unique streamId assigned to the applicable stream.

  2. Make a GET request to /live-archive/v1/streams/{streamId}/endpoints.

  3. The operation responds with a Endpoints object.

Remove objects

Delete all objects under this endpoint.

DELETE /live-archive/v1/streams/{streamId}/endpoints/{endpoint}

Sample: /live-archive/v1/streams/609993/endpoints/609993/streamcat

Parameter Type Sample Description
URL path parameters
streamId Integer 609993 Uniquely identifies the stream from which this archive derives.
endpoint String 609993/streamcat The URL path for which all objects need to be deleted. This is URL-encoded.

Status 200

  1. Get the unique streamId assigned to the applicable stream.

  2. Run the list endpoints operation and store the appropriate entry from the endpoints array.

  3. Make a DELETE request to /live-archive/v1/streams/{streamId}/endpoints/{endpoint}.

Create a VOD asset

For beta customers only. Akamai is no longer accepting new members for this beta program. When you enable archiving for an MSL live stream, you can retain it for a maximum of 31 days. To retain archived content beyond 31 days, use this operation to create a separate VOD asset that MSL stores in Akamai NetStorage. You need to set up the desired NetStorage storage group using the Live-to-VOD Export option in Akamai Control Center.

POST /live-archive/v1/vod/

Content-Type: application/json

Object type: VodAsset

Download schema: vod-create-request.json

Request body:

{
    "startTime": 1552933300,
    "endTime": 1552933330,
    "assetId": "ABCD1234567890123456",
    "maxFileSize": 100,
    "preserveKeys": true,
    "URI": "/dash/609978/DevtestDashStream1/dash.mpd"
}

Status 202 application/json

Object type: VodAsset

Download schema: vod-create-response.json

Response body:

{
    "EID": "553960_244dcbf53b61f4ea62dc650425858424"
}
  1. Run the List archives operation and store the archiveStartTime, archiveEndTime, and uri values for the applicable archive. Respectively, these are the Unix epoch times the archive started and ended, and the URL path used to fetch the bit rates published for the archive’s master playlist.

  2. Build a new VodAsset object. The assetId is a value you determine. The stored archiveStartTime serves as the startTime, the archiveEndTime serves as the endTime, and uri serves as the URI. All other members are optional.

  3. POST the object to /live-archive/v1/vod/.

  4. The operation returns a VodAsset “POST response” object.

Get VOD status

For beta customers only. Akamai is no longer accepting new members for this beta program. Use this to query the status of a VOD asset creation operation, using its export ID (EID).

GET /live-archive/v1/vod/{EID}

Sample: /live-archive/v1/vod/809269_8749e87de8bbf429e5486b41ca6f9f87

Parameter Type Sample Description
URL path parameters
EID String 809269_8749e87de8bbf429e5486b41ca6f9f87 A unique ID assigned to the export.

Status 200 application/json

Object type: VodAsset

Download schema: vod-status-response.json

Response body:

{
    "status": "ready"
}
  1. Run the create a VOD asset operation and store the EID from the response.

  2. Make a GET request to /live-archive/v1/vod/{EID}.

  3. The operation returns a VodAsset “GET response” object.

Data

This section provides you with the data model for the Live Archive Management (LAM) 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.

Archives

Response to a request for all the archives for a stream ID or archives within a specified time range

Download schema: archives.json

Sample GET:

{
    "archives": [
        {
            "name": "master.m3u8",
            "uri": "609993/1523371274.347/master.m3u8",
            "archiveStartTime": "1523371274",
            "archiveEndTime": "1523371284",
            "manifestUpdateTimes": []
        },
        {
            "name": "master.m3u8",
            "uri": "609993/1523371482.096/master.m3u8",
            "archiveStartTime": "1523371482",
            "archiveEndTime": "0",
            "manifestUpdateTimes": [
                1523371492,
                1523371502
            ]
        }
    ]
}

Archives members

Member Type Required Description
Archives: Response to a request for all the archives for a stream ID or archives within a specified time range
archives Archives.archives[] An archive on storage for the specified stream ID and name.
Archives.archives[]: An archive on storage for the specified stream ID and name.
archiveEndTime String Time at which the stream is not archived, “End of Stream” detected from manifests. The value is a Unix epoch timestamp.
archiveStartTime String Time at which the stream starts to be archived. The value is a Unix epoch timestamp.
manifestUpdateTimes Array This is a Unix epoch timestamp that represents when MSL updated and published the master manifest file during the live stream.
name String The name of the manifest.
uri String The URL path used to fetch the bit rates published for this master playlist. For example, this could be {event_name}/master.m3u8.

Endpoints

Details about an endpoint.

Download schema: endpoints.json

Sample GET:

{
    "endpoints": [
        "609993/l2v_no_timestamp3/bitrate_500k.m3u8",
        "609993/l2v_no_timestamp3",
        "609993/l2v_no_timestamp7",
        "609993/l2v_no_timestamp7/bitrate_1500k.m3u8",
        "609993/streamcat",
        "609993/streamcat123abc"
    ]
}

Endpoints members

Member Type Required Description
Endpoints: Details about an endpoint.
endpoints Array The set of URL paths available for each stream for the specified time range.

VodAsset

When you enable archiving for an MSL live stream, you can tell Akamai to keep the live archive for a maximum of 31 days. A VOD Asset is physical on-demand video content that you create from a live archive and store in Akamai NetStorage. This lets you preserve live archive content for longer than 31 days.

Download schema: vod-create-request.json, vod-create-response.json, vod-status-response.json

Sample POST:

{
    "startTime": 1552933300,
    "endTime": 1552933330,
    "assetId": "ABCD1234567890123456",
    "maxFileSize": 100,
    "preserveKeys": true,
    "URI": "/dash/609978/DevtestDashStream1/dash.mpd"
}

Sample POST response:

{
    "EID": "553960_244dcbf53b61f4ea62dc650425858424"
}

Sample GET response:

{
    "status": "ready"
}

VodAsset members

Member Type POST POST response GET response Description
VodAsset: When you enable archiving for an MSL live stream, you can tell Akamai to keep the live archive for a maximum of 31 days. A VOD Asset is physical on-demand video content that you create from a live archive and store in Akamai NetStorage. This lets you preserve live archive content for longer than 31 days.
assetId String This is a unique identifier you set for a VOD asset. Start it with four alphanumeric characters followed by 16 numeric characters.
EID String This is a unique identifier that Akamai applies to a request to create a new VOD asset.
endTime Integer The Unix epoch timestamp that marks the end time of the VOD clip. The value needs to be greater than the startTime by at least 30 seconds and no more than 43200 seconds, representing the clip’s maximum allowed duration of 12 hours. There is a 30 minute latency. So, this needs to be less than the current epoch time by at least 1800 seconds.
maxFileSize Integer The maximum exported segment size in MB. The default value is 100 MB. This only applies to HLS VOD assets.
preserveKeys Boolean When set to true, MSL won’t export keys and won’t change key metadata in the manifests. When set to false, MSL exports keys and may change metadata in the manifests to accommodate. The default value is false. This only applies to HLS VOD assets.
startTime Integer The Unix epoch timestamp that marks the start time of the VOD clip.
status Enumeration The status of a request to create a new VOD asset. It can be ready, in_progress, or failed.
URI String This is the URL for the live stream archive, using the form /{format}/{streamId}/{eventName}/{manifestName}. In it, format is either hls or dash, streamId is the unique, numeric identifier that’s been assigned to the stream, eventName is the name of the event that you’ve assigned to the stream, and manifestName is the manifest filename. For example, /hls/708976/helloworld/master.m3u8 is an HLS master manifest URL and /dash/708976/helloworld/hello.mpd is a DASH manifest URL.

Errors

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

Error responses

If you encounter any errors when running the Live Archive Management API, the API responds with an error code and an error message that provides details useful for debugging.

This shows a typical error response you get when a request is made for a stream ID for which you don’t have read permission:

{
  "type": "https://problems.luna-dev.akamaiapis.net/-/resource-impl/forward-origin-error",
  "title": "Forbidden",
  "status": 403,
  "instance": "https://akaa-bcvzkpmpmke7ljco-imsshpx75pzckhdq.luna-dev.akamaiapis.net/live-archive/v1/streams/60997988/endpoints",
  "method": "GET",
  "serverIp": "104.125.223.90",
  "clientIp": "23.79.233.23",
  "requestId": "142558a",
  "requestTime": "2018-06-22T10:41:58Z"
}

If you encounter any errors when running the VOD management operations, the API responds with an error code.

HTTP status codes

Archive management operations generate these HTTP status codes for both success and failure scenarios:

Code Description
200 The operation was successful.
400 Bad request
403 Access is forbidden.
500 Internal server error
501 Functionality is not supported.
504 Gateway timeout

VOD management operations generate these HTTP status codes for both success and failure scenarios.

Errors when running the Create a VOD asset operation:

Code Description
202 The operation was successful and the VOD asset creation launches.
400 The URL is not formed correctly or the POST body is not valid.
403 VOD Management is not enabled, either globally or for this stream.
405 The HTTP method is not allowed.
500 Internal server error

Errors when running the Get VOD status operation:

Code Description
200 The operation was successful. The status is returned in the JSON response.
400 Bad request. The URL is not formed correctly.
403 The VOD management operation is not enabled, either globally or for this stream.
405 The HTTP method is not allowed.
500 Internal server error. The export ID doesn’t exist or is invalid.