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

You can use Media Services Live 4 to 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 these things:

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

Get started

These are the prerequisites to get you started:

  • Ensure that your contract includes MediaServicesLive4::LiveToVOD.

  • Review Get Started with APIs. You use the Identity and Access Management tool in Akamai Control Center to set up access for any Akamai API, as well as gather some information you’ll need:

    • Set up client tokens for access. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

    • Verify you have the API service named MSL4 Live Archive APIs, and its access level is set to READ-WRITE. This gives you access to all of the operations in this API.

You need “Advanced Archives”

You need to enable Advanced Archive for your MSL streams to review the archives associated 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 Control Center. Note the value listed as the (Stream ID).

Concepts

Familiarize yourself with these concepts that the API uses 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.

    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
  • VOD Asset: A physical on demand video asset that you generate from a live archive and store in Akamai NetStorage.

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}

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

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

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 when you don’t have read permission for the stream ID set in a request:

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