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 enables you to archive live streams in HLS and DASH formats and later export the archive into VOD assets. You can use the Live Archive Manager (LAM) API to list, modify, manage, and export your live archives. For details about MSL, see Media Services Live Stream Provisioning API.

Who should use this API

This API is useful for you to:

  • Get details about the content you archived.
  • Understand all the objects that are part of an archive or endpoint.
  • Delete an endpoint and all the objects belonging to that endpoint.
  • Export archived live streams into VOD assets.

Getting started

The following are the prerequisites to get you started:

  • Ensure that your contract includes MediaServicesLive4::LiveToVOD.

  • 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.

Resources

The Live Archive Management API enables you to access archives and endpoints. These are resources which will help you work with your archived content and very closely mirror how the content was ingested into Akamai.

  • Create a VOD asset: The MSL origin retains an active live archive for a maximum of 31 days. To retain the content beyond this period, you can create a VOD asset from the live archive using this operation. VOD assets are exported to a storage location provisioned from Akamai Control Center.

  • Archives: An archive is a live encoding session stored in Akamai NetStorage. Sessions run from the time at which the encoder starts publishing an event till 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.

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.

The following 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

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
            ]
        }
    ]
}

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

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

Create a VOD asset

Initiates VOD asset creation based on the POST body.

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"
}

Get VOD status

Query the status of VOD asset creation by the 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": "completed"
}

Data

This section provides you with the data model for the Live Archive Management API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

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 Time at which the master manifest file was updated and published during the live stream. The value is a Unix epoch timestamp.
name String The name of the manifest.
uri String The URL path used to fetch the bitrates published for this master playlist (for example, 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

The MSL origin retains an active live archive for a maximum of 31 days. To retain the content beyond this period, you can use this operation to create a VOD asset. VOD assets are exported to a storage location provisioned from Akamai Control Center.

Download schema: vod-create-request.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": "completed"
}

VodAsset members

Member Type Required Description
VodAsset: The MSL origin retains an active live archive for a maximum of 31 days. To retain the content beyond this period, you can use this operation to create a VOD asset. VOD assets are exported to a storage location provisioned from Akamai Control Center.
assetId String Uniquely identifies a VOD asset. Must be a string of 4 alphanumeric characters followed by 16 numeric characters with no spaces allowed.
endTime Integer 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. It needs to be less than the current epoch time by at least 1800 seconds, representing a latency of half an hour.
maxFileSize Integer Maximum exported segment size in MB. The default value is 100 MB. It is only applicable to HLS VOD jobs.
preserveKeys Boolean A true value means no key will be exported and the key metadata in the manifests is not changed. A false value means the keys will be exported, and key metadata in the manifests might be changed. The default value is false. It is only applicable to HLS VOD jobs.
startTime Integer Unix epoch timestamp that marks the start time of the VOD clip.
URI String Archived live stream URI of the form /{format}/{streamId}/{eventName}/{manifestName}, where format is either hls or dash. For example /hls/708976/helloworld/master.m3u8 is an HLS master manifest URI and /dash/708976/helloworld/hello.mpd is a DASH manifest URI.

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.

The following shows a typical error response when a request is made for a stream ID, which is not owned by the user:

{
  "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

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 does not exist or is invalid.

Last modified: 9/16/2019