Live Archive Management API v1

Overview

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

Getting started

The following are the prerequisites to get you started:

  • Ensure that your contract includes MediaServicesLive4::LiveToVOD.

  • Review Get Started on tools that Akamai provides for all its APIs.

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

  • While setting up your API client set Access level to READ-WRITE for MSL4 Live Archive APIs.

Resources

The LAM 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.

  • Archives: An archive is a live encoding session that’s saved on Akamai NetStorage. Sessions run from the time in which the encoder starts publishing an event to 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 with the way the encoder publishes objects for 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 example shows the endpoints for different objects.

Object Endpoint
/hls/708976/helloworld/master.m3u8 708976/helloworld
/hls/708976/helloworld/bitrate_500K/playlist_500.m3u8 708976/helloworld/bitrate_500K
/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/{path}

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 parameters
streamId String 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

Response Body:

{
    "archives": [
        {
            "name": "master.m3u8",
            "uri": "609979/1523371274.347/master.m3u8",
            "archiveStartTime": "1523371274",
            "archiveEndTime": "1523371284",
            "manifestUpdateTimes": []
        },
        {
            "name": "master.m3u8",
            "uri": "609979/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 parameters
streamId String 609993 Uniquely identifies the stream from which this archive derives.

Status 200 application/json

Response Body:

{
    "endpoints": [
        "609979/l2v_no_timestamp3",
        "609979/l2v_no_timestamp7",
        "609979/streamcat",
        "609979/streamcat123abc"
    ]
}

Remove objects

Delete all objects under this endpoint.

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

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

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

Status 200

Data

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

Download the JSON schemas for this API.

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": "609979/1523371274.347/master.m3u8",
            "archiveStartTime": "1523371274",
            "archiveEndTime": "1523371284",
            "manifestUpdateTimes": []
        },
        {
            "name": "master.m3u8",
            "uri": "609979/1523371482.096/master.m3u8",
            "archiveStartTime": "1523371482",
            "archiveEndTime": "0",
            "manifestUpdateTimes": [
                1523371492,
                1523371502
            ]
        }
    ]
}

Archives Members

Member Type Description
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": [
        "609979/l2v_no_timestamp3",
        "609979/l2v_no_timestamp7",
        "609979/streamcat",
        "609979/streamcat123abc"
    ]
}

Endpoints Members

Member Type Description
endpoints Array The set of URL paths available for each stream for the specified time range.

Errors

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

Error responses

When the API encounters an error, it responds with 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"
}

HTTP status codes

The API produces the following set of HTTP status codes for both success and failure scenarios:

Code Description
200 The operation was successful.
400 Bad Request.
403 Access is forbidden.

Last modified: 7/30/2018