Livepeer API Reference

Welcome to the Livepeer API reference docs. Here you'll find all the endpoints exposed on the standard Livepeer API, learn how to use them and what they return.

The Livepeer API is organized around REST, has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Just Getting Started?

Head over to Livepeer Studio, create an account and start building with Livepeer.

BASE URL

https://livepeer.studio/api

Create a stream

POST /stream creates a stream object. The configuration on this stream object is inherited by all live sessions using this stream's streamKey.

It is important to note, that the stream object is the core building block of the Livepeer Studio platform. In Livepeer Studio, the stream object has unique configuration data and metadata about all livestream sessions that are associated with the stream.

The only parameter you are required to set is the name of your stream, but we also highly recommend that you define transcoding profiles parameter that suits your specific broadcasting configuration.

If you do not define transcoding rendition profiles when creating the stream, a default set of profiles will be used. These profiles include 240p, 360p, 480p and 720p.

The playback policy is set to public by default for new streams. It can also be added upon the creation of a new stream by adding "playbackPolicy": {"type": "jwt"}

Parameters

namestring

creatorId

One of:

object

One of:

object

string

Helper syntax to specify an unverified creator ID, fully managed by the developer.

playbackPolicyobject

Whether the playback policy for a asset or stream is public or signed

profilesarray

LMPS ffmpeg profile

recordboolean

Should this stream be recorded? Uses default settings. For more customization, create and configure an object store.

multistreamobject

streamsonlystring

post/stream

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/stream

RESPONSE

[
  {
    "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "name": "test_stream",
    "creatorId": null,
    "lastSeen": 1587667174725,
    "sourceSegments": 1,
    "transcodedSegments": 2,
    "sourceSegmentsDuration": 1,
    "transcodedSegmentsDuration": 2,
    "sourceBytes": 1,
    "transcodedBytes": 2,
    "ingestRate": 1,
    "outgoingRate": 2,
    "isActive": null,
    "isHealthy": null,
    "issues": null,
    "createdByTokenName": null,
    "createdAt": 1587667174725,
    "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "streamKey": "hgebdhhigq",
    "playbackId": "eaw4nk06ts2d0mzb",
    "playbackPolicy": null,
    "profiles": [
      {
        "width": null,
        "name": "720p",
        "height": null,
        "bitrate": null,
        "fps": null,
        "fpsDen": null,
        "gop": null,
        "profile": null,
        "encoder": null
      }
    ],
    "record": null,
    "multistream": {
      "targets": [
        {
          "id": "PUSH123",
          "profile": "720p"
        }
      ]
    },
    "suspended": null
  }
]

Retrieve streams

GET /stream endpoint is used to retrieve all stream objects with the same userId. The response will include both parent stream objects and the historic stream objects with a parentId, which represent a single live stream session. Please note that the usage of these "child-session" stream objects is deprecated, and it is recommended to use the session endpoints instead.

To filter the API response and exclude the historic stream objects with a parentId, you can add the ?streamsonly=true query string.

GET /stream?streamsonly=1 This endpoint retrieves all stream objects with the same userId and excludes the historic stream objects with a parentId, which represent a single live stream session.

Quick Filters

Filter	Example	Description
All stream objects with the same userId	`/api/stream?streamsonly=1`	This filter excludes the historic stream objects with a parentId, which represent a single live stream session.
All active stream objects	`/api/stream?streamsonly=1&filters=[{"id": "isActive", "value": true}]`	This filter returns active stream objects. Setting the value to `false` returns idle stream objects. The default value for new stream objects is `false`. Note that the example shows a decoded JSON object, but in a URL, it should be URL-encoded.
All stream objects with recording on	`/api/stream?streamsonly=1&filters=[{"id": "record", "value": true}]`	This filter returns stream objects with recording turned on. The default value for new stream objects is `false`. Note that the example shows a decoded JSON object, but in a URL, it should be URL-encoded.

Parameters

streamsonlystring

get/stream

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/stream

RESPONSE

[
  {
    "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "name": "test_stream",
    "creatorId": null,
    "lastSeen": 1587667174725,
    "sourceSegments": 1,
    "transcodedSegments": 2,
    "sourceSegmentsDuration": 1,
    "transcodedSegmentsDuration": 2,
    "sourceBytes": 1,
    "transcodedBytes": 2,
    "ingestRate": 1,
    "outgoingRate": 2,
    "isActive": null,
    "isHealthy": null,
    "issues": null,
    "createdByTokenName": null,
    "createdAt": 1587667174725,
    "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "streamKey": "hgebdhhigq",
    "playbackId": "eaw4nk06ts2d0mzb",
    "playbackPolicy": null,
    "profiles": [
      {
        "width": null,
        "name": "720p",
        "height": null,
        "bitrate": null,
        "fps": null,
        "fpsDen": null,
        "gop": null,
        "profile": null,
        "encoder": null
      }
    ],
    "record": null,
    "multistream": {
      "targets": [
        {
          "id": "PUSH123",
          "profile": "720p"
        }
      ]
    },
    "suspended": null
  }
]

Retrieve a stream

In order to retrieve a specific stream, you can just pass the stream id to this API

Parameters

idstring

ID of the stream

get/stream/{id}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/stream/{id}

RESPONSE

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": "test_stream",
  "creatorId": null,
  "lastSeen": 1587667174725,
  "sourceSegments": 1,
  "transcodedSegments": 2,
  "sourceSegmentsDuration": 1,
  "transcodedSegmentsDuration": 2,
  "sourceBytes": 1,
  "transcodedBytes": 2,
  "ingestRate": 1,
  "outgoingRate": 2,
  "isActive": null,
  "isHealthy": null,
  "issues": null,
  "createdByTokenName": null,
  "createdAt": 1587667174725,
  "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "streamKey": "hgebdhhigq",
  "playbackId": "eaw4nk06ts2d0mzb",
  "playbackPolicy": null,
  "profiles": [
    {
      "width": null,
      "name": "720p",
      "height": null,
      "bitrate": null,
      "fps": null,
      "fpsDen": null,
      "gop": null,
      "profile": null,
      "encoder": null
    }
  ],
  "record": null,
  "multistream": {
    "targets": [
      {
        "id": "PUSH123",
        "profile": "720p"
      }
    ]
  },
  "suspended": null
}

Update a stream

PATCH /stream/{id} can be used to modify a stream object. It is a single endpoint that can update any of the mutable properties of a stream. Specifically:

record

suspended

multistream.targets

All fields in the request payload are optional, and any field that is not included will keep the same value as before in the saved object.

A 204 No Content status response indicates the stream was successfully updated

Parameters

creatorId

One of:

object

One of:

object

string

Helper syntax to specify an unverified creator ID, fully managed by the developer.

recordboolean

Should this stream be recorded? Uses default settings. For more customization, create and configure an object store.

suspendedboolean

If currently suspended

multistreamobject

playbackPolicyobject

Whether the playback policy for a asset or stream is public or signed

idstring

ID of the stream

patch/stream/{id}

curl -X PATCH -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/stream/{id}

RESPONSE

204 - No Content

Delete a stream

DELETE /stream/{id} deletes an existing stream object.

This will also suspend any active stream sessions, so make sure to wait until the stream has finished. To explicitly interrupt an active session, consider instead updating the suspended field in the stream using the PATCH stream API.

Parameters

idstring

ID of the stream

delete/stream/{id}

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/stream/{id}

RESPONSE

204 - No Content

Retrieve Multistream Targets

Use /multistream/target to a return a list of your existing multistream targets.

Parameters

No parameters available.

get/multistream/target

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/multistream/target

RESPONSE

[
  {
    "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
    "name": null,
    "url": "rtmps://live.my-service.tv/channel/secretKey",
    "disabled": null,
    "createdAt": 1587667174725
  }
]

Create a multistream target

Parameters

namestring

urlstring

Livepeer-compatible multistream target URL (RTMP(S) or SRT)

disabledboolean

If true then this multistream target will not be used for pushing even if it is configured in a stream object.

post/multistream/target

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/multistream/target

RESPONSE

[
  {
    "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
    "name": null,
    "url": "rtmps://live.my-service.tv/channel/secretKey",
    "disabled": null,
    "createdAt": 1587667174725
  }
]

Retrieve a multistream target

You can retrieve a multistream target from its ID with this API.

Parameters

idstring

ID of the multistream target

get/multistream/target/{id}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/multistream/target/{id}

RESPONSE

{
  "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "name": null,
  "url": "rtmps://live.my-service.tv/channel/secretKey",
  "disabled": null,
  "createdAt": 1587667174725
}

Update Multistream Target

PATCH /multistream/target/{id} updates an existing multistream target object. You can change any user-defined field in the current object, specifically name, url and disabled.

All fields are optional, and if any field is not included in the request payload it will be kept unchanged from the saved object.

You cannot access the current url field for updating it since we redact it from GET responses. If you want to update the URL you have to build it from scratch. You can also omit it from the PATCH payload to keep it as is.

A 204 No Content status response indicates the multistream target was successfully updated.

Parameters

idstring

ID of the multistream target

patch/multistream/target/{id}

curl -X PATCH -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/multistream/target/{id}

RESPONSE

204 - No Content

Delete a multistream target

DELETE /multistream/target/{id} deletes an existing multistream target object. Make sure to remove any references to the target on existing streams before actually deleting it from the API.

Parameters

idstring

ID of the multistream target

delete/multistream/target/{id}

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/multistream/target/{id}

RESPONSE

204 - No Content

Retrieve a Webhook

Parameters

No parameters available.

get/webhook

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/webhook

RESPONSE

[
  {
    "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "name": null,
    "createdAt": 1587667174725,
    "events": [
      null
    ],
    "url": null,
    "sharedSecret": null,
    "streamId": null,
    "status": {
      "lastFailure": {
        "timestamp": 1587667174725,
        "error": "Error message",
        "response": "Response body",
        "statusCode": 500
      },
      "lastTriggeredAt": 1587667174725
    }
  }
]

Create a webhook

To create a new webhook, you need to make an API call with the events you want to listen for and the URL that will be called when those events occur.

Types of Events

Name	Description
`stream.started`	The parent stream object's isActive value is marked as true and the .m3u8 HLS URL works
`stream.idle`	The parent stream object's isActive value should be marked as false and the .m3u8 HLS URL no longer works
`recording.ready`	This fires when a recording is ready to be downloaded
`recording.started`	This fires when recording has started on an active stream
`recording.waiting`	This fires after a stream with recording on has concluded and is not yet ready to be downloaded. Typically it takes 5 minutes for recordings to be ready for download
`multistream.connected`	This fires when we've successfully connected to the multistream target
`multistream.error`	This fires when we've encountered an error either while attempting to connect to the third-party streaming service or while broadcasting
`multistream.disconnected`	This fires when we are no longer sending video to the multistream target
`asset.created`	This fires when an On Demand asset is created
`asset.updated`	This fires when an On Demand asset is updated
`asset.ready`	This fires when an On Demand asset is ready
`asset.failed`	This fires when an On Demand asset fails during the upload or during processing
`asset.deleted`	This fires when an On Demand asset is deleted
`task.spawned`	This fires when a task is spawned (e.g., an On Demand upload)
`task.updated`	This fires when a task is updated
`task.completed`	This fires when a task completes its execution successfully
`task.failed`	This fires when a task has failed
`playback.accessControl`	A specialized webhook for playback access control. Unlike other events, this is only used for assets and streams that reference its ID on their playback policy

Parameters

No parameters available.

post/webhook

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/webhook

RESPONSE

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": null,
  "createdAt": 1587667174725,
  "events": [
    null
  ],
  "url": null,
  "sharedSecret": null,
  "streamId": null,
  "status": {
    "lastFailure": {
      "timestamp": 1587667174725,
      "error": "Error message",
      "response": "Response body",
      "statusCode": 500
    },
    "lastTriggeredAt": 1587667174725
  }
}

Retrieve a webhook

Parameters

idstring

get/webhook/{id}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/webhook/{id}

RESPONSE

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": null,
  "createdAt": 1587667174725,
  "events": [
    null
  ],
  "url": null,
  "sharedSecret": null,
  "streamId": null,
  "status": {
    "lastFailure": {
      "timestamp": 1587667174725,
      "error": "Error message",
      "response": "Response body",
      "statusCode": 500
    },
    "lastTriggeredAt": 1587667174725
  }
}

Update a webhook

You can update a webhook by calling the PATCH webhook endpoint with the webhookId. It is a single endpoint that can update any of the mutable properties of a webhook. Specifically:

name

url

events

Parameters

idstring

put/webhook/{id}

curl -X PUT -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/webhook/{id}

RESPONSE

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": null,
  "createdAt": 1587667174725,
  "events": [
    null
  ],
  "url": null,
  "sharedSecret": null,
  "streamId": null,
  "status": {
    "lastFailure": {
      "timestamp": 1587667174725,
      "error": "Error message",
      "response": "Response body",
      "statusCode": 500
    },
    "lastTriggeredAt": 1587667174725
  }
}

Delete a webhook

Parameters

idstring

delete/webhook/{id}

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/webhook/{id}

RESPONSE

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": null,
  "createdAt": 1587667174725,
  "events": [
    null
  ],
  "url": null,
  "sharedSecret": null,
  "streamId": null,
  "status": {
    "lastFailure": {
      "timestamp": 1587667174725,
      "error": "Error message",
      "response": "Response body",
      "statusCode": 500
    },
    "lastTriggeredAt": 1587667174725
  }
}

Retrieve assets

Parameters

No parameters available.

get/asset

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/asset

RESPONSE

[
  {
    "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
    "type": "video",
    "playbackId": "eaw4nk06ts2d0mzb",
    "staticMp4": null,
    "playbackUrl": "https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8",
    "downloadUrl": "https://livepeercdn.com/asset/eaw4nk06ts2d0mzb/video",
    "playbackPolicy": null,
    "source": null,
    "creatorId": null,
    "storage": null,
    "status": {
      "phase": null,
      "updatedAt": 1587667174725,
      "progress": null,
      "errorMessage": null
    },
    "name": "filename.mp4",
    "createdAt": 1587667174725,
    "size": 84934509,
    "hash": [
      {
        "hash": "9b560b28b85378a5004117539196ab24e21bbd75b0e9eb1a8bc7c5fd80dc5b57",
        "algorithm": "sha256"
      }
    ],
    "videoSpec": {
      "format": "mp4",
      "duration": 23.8328,
      "bitrate": 1000000,
      "tracks": [
        {
          "type": "video",
          "codec": "aac",
          "startTime": 23.8238,
          "duration": 23.8238,
          "bitrate": 1000000,
          "width": 1920,
          "height": 1080,
          "pixelFormat": "yuv420p",
          "fps": 30,
          "channels": 2,
          "sampleRate": 44100,
          "bitDepth": 16
        }
      ]
    }
  }
]

Upload an asset

To upload an asset, your first need to request for a direct upload URL and only then actually upload the contents of the asset.

Once you created a upload link, you have 2 options, resumable or direct upload. For a more reliable experience, you should use resumable uploads which will work better for users with unreliable or slow network connections. If you want a simpler implementation though, you should just use a direct upload.

Direct Upload

For a direct upload, make a PUT request to the URL received in the url field of the response above, with the raw video file as the request body. response above:

Resumable Upload

Livepeer supports resumable uploads via Tus. This section provides a simple example of how to use tus-js-client to upload a video file.

From the previous section, we generated a URL to upload a video file to Livepeer on POST /api/asset/request-upload. You should use the tusEndpoint field of the response to upload the video file and track the progress:

# This assumes there is an `input` element of `type="file"` with id
`fileInput` in the HTML


const input = document.getElementById('fileInput');

const file = input.files[0];

const upload = new tus.Upload(file, {
  endpoint: tusEndpoint, // URL from `tusEndpoint` field in the
`/request-upload` response
  metadata: {
    filename,
    filetype: 'video/mp4',
  },
  uploadSize: file.size,
  onError(err) {
    console.error('Error uploading file:', err);
  },
  onProgress(bytesUploaded, bytesTotal) {
    const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
    console.log('Uploaded ' + percentage + '%');
  },
  onSuccess() {
    console.log('Upload finished:', upload.url);
  },
});

const previousUploads = await upload.findPreviousUploads();

if (previousUploads.length > 0) {
  upload.resumeFromPreviousUpload(previousUploads[0]);
}

upload.start();

Note: If you are using tus from node.js, you need to add a custom URL storage to enable resuming from previous uploads. On the browser, this is enabled by default using local storage. In node.js, add urlStorage: new tus.FileUrlStorage("path/to/tmp/file"), to the UploadFile object definition above.

Parameters

namestring

Name of the asset. This is not necessarily the filename, can be a custom name or title

staticMp4boolean

Whether to generate MP4s for the asset.

playbackPolicyobject

Whether the playback policy for a asset or stream is public or signed

creatorId

One of:

object

One of:

object

string

Helper syntax to specify an unverified creator ID, fully managed by the developer.

storage

urlstring

URL where the asset contents can be retrieved. Only allowed (and also required) in the upload asset via URL endpoint.

encryptionobject

post/asset/request-upload

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/asset/request-upload

RESPONSE

{
  "errors": [
    [
      "id not provided",
      "user not found"
    ]
  ]
}

Upload asset via URL

Import a video Asset from an external URL through the POST /api/asset/upload/url API.

For rapid processing of assets that will also be archived on IPFS or Arweave, we strongly encourage uploading the raw file to Livepeer via a direct upload rather than passing the IPFS / Arweave gateway URL to this endpoint. The gateway URL will work, but may incur longer-than-usual processing time.

For IPFS HTTP gateway URLs, the API currently only supports “path style” URLs and does not support “subdomain style” URLs. The API will support both styles of URLs in a future update.

Parameters

namestring

Name of the asset. This is not necessarily the filename, can be a custom name or title

staticMp4boolean

Whether to generate MP4s for the asset.

playbackPolicyobject

Whether the playback policy for a asset or stream is public or signed

creatorId

One of:

object

One of:

object

string

Helper syntax to specify an unverified creator ID, fully managed by the developer.

storage

urlstring

URL where the asset contents can be retrieved. Only allowed (and also required) in the upload asset via URL endpoint.

encryptionobject

post/asset/upload/url

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/asset/upload/url

RESPONSE

{
  "errors": [
    [
      "id not provided",
      "user not found"
    ]
  ]
}

Retrieves an asset

Parameters

assetIdstring

ID of the asset

get/asset/{assetId}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/asset/{assetId}

RESPONSE

{
  "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "type": "video",
  "playbackId": "eaw4nk06ts2d0mzb",
  "staticMp4": null,
  "playbackUrl": "https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8",
  "downloadUrl": "https://livepeercdn.com/asset/eaw4nk06ts2d0mzb/video",
  "playbackPolicy": null,
  "source": null,
  "creatorId": null,
  "storage": null,
  "status": {
    "phase": null,
    "updatedAt": 1587667174725,
    "progress": null,
    "errorMessage": null
  },
  "name": "filename.mp4",
  "createdAt": 1587667174725,
  "size": 84934509,
  "hash": [
    {
      "hash": "9b560b28b85378a5004117539196ab24e21bbd75b0e9eb1a8bc7c5fd80dc5b57",
      "algorithm": "sha256"
    }
  ],
  "videoSpec": {
    "format": "mp4",
    "duration": 23.8328,
    "bitrate": 1000000,
    "tracks": [
      {
        "type": "video",
        "codec": "aac",
        "startTime": 23.8238,
        "duration": 23.8238,
        "bitrate": 1000000,
        "width": 1920,
        "height": 1080,
        "pixelFormat": "yuv420p",
        "fps": 30,
        "channels": 2,
        "sampleRate": 44100,
        "bitDepth": 16
      }
    ]
  }
}

Delete an asset

Parameters

assetIdstring

ID of the asset

delete/asset/{assetId}

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/asset/{assetId}

RESPONSE

204 - No Content

Create a room

Create a multiparticipant livestreaming room.

Parameters

No parameters available.

post/room

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room

RESPONSE

{
  "id": "d32ae9e6-c459-4931-9898-e86e2f5e7e16"
}

Retrieve a room

Parameters

idstring

get/room/{id}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}

RESPONSE

{
  "id": "d32ae9e6-c459-4931-9898-e86e2f5e7e16",
  "createdAt": 1587667174725,
  "updatedAt": 1587667174725,
  "egressId": null,
  "participants": {}
}

Delete a room

Parameters

idstring

delete/room/{id}

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}

RESPONSE

204 - No Content

Start room RTMP egress

Create a livestream for your room. This allows you to leverage livestreaming features like recording and HLS output.

Parameters

streamIdstring

The ID of the Livepeer Stream to stream to

idstring

post/room/{id}/egress

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}/egress

RESPONSE

204 - No Content

Stop room RTMP egress

Parameters

idstring

delete/room/{id}/egress

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}/egress

RESPONSE

204 - No Content

Create a room user

Call this endpoint to add a user to a room, specifying a display name at a minimum. The response will contain a joining URL for Livepeer's default meeting app. Alternatively the joining token can be used with a custom app.

Parameters

namestring

Display name

canPublishboolean

Whether a user is allowed to publish audio/video tracks

canPublishDataboolean

Whether a user is allowed to publish data messages to the room

metadatastring

User defined payload to store for the participant

idstring

post/room/{id}/user

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}/user

RESPONSE

{
  "id": "d32ae9e6-c459-4931-9898-e86e2f5e7e16",
  "joinUrl": "https://meet.livepeer.chat",
  "token": "token"
}

Get user details

Parameters

idstring

userIdstring

get/room/{id}/user/{userId}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}/user/{userId}

RESPONSE

{
  "id": "d32ae9e6-c459-4931-9898-e86e2f5e7e16",
  "joinedAt": 1687517025261,
  "name": "name",
  "isPublisher": true,
  "metadata": null
}

Update a room user

Update properties for a user.

Parameters

canPublishboolean

Whether a user is allowed to publish audio/video tracks (i.e. their microphone and webcam)

canPublishDataboolean

Whether a user is allowed to publish data messages to the room

metadatastring

User defined payload to store for the participant

idstring

userIdstring

put/room/{id}/user/{userId}

curl -X PUT -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}/user/{userId}

RESPONSE

204 - No Content

Remove a user from the room

Parameters

idstring

userIdstring

delete/room/{id}/user/{userId}

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/room/{id}/user/{userId}

RESPONSE

204 - No Content

Query viewership metrics

Allows querying any metric in its raw form. Requires a private (non-CORS) API key to be used.

Parameters

playbackIdstring

The playback ID to filter the query results. This can be a canonical playback ID from Livepeer assets or streams, or dStorage identifiers for assets

from

Start timestamp for the query range (inclusive)

One of:

string

integer

to

End timestamp for the query range (exclusive)

One of:

string

integer

timeStepstring

The time step to aggregate viewership metrics by

Enum: hourdayweekmonthyear

assetIdstring

The asset ID to filter metrics for

streamIdstring

The stream ID to filter metrics for

creatorIdstring

The creator ID to filter the query results

breakdownBy[]array

The list of fields to break down the query results. Specify this query-string multiple times to break down by multiple fields.

get/data/views/query

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/data/views/query

RESPONSE

[
  {
    "playbackId": null,
    "creatorId": null,
    "viewerId": null,
    "dStorageUrl": null,
    "timestamp": 1587667174725,
    "device": null,
    "deviceType": null,
    "cpu": null,
    "os": null,
    "browser": null,
    "browserEngine": null,
    "continent": null,
    "country": null,
    "subdivision": null,
    "timezone": null,
    "geohas": null,
    "viewCount": null,
    "playtimeMins": null,
    "ttffMs": null,
    "rebufferRatio": null,
    "errorRate": null,
    "exitsBeforeStart": null
  }
]

Query creator viewership metrics

Allows querying creator-specific metrics. Requires a proof of ownership to be sent in the request, which for now is just the assetId or streamId parameters (1 of those must be in the query-string). Returns only the higher level metrics like viewCount and platimeMins. Can be used from the frontend with a CORS key.

Parameters

from

Start timestamp for the query range (inclusive)

One of:

string

integer

to

End timestamp for the query range (exclusive)

One of:

string

integer

timeStepstring

The time step to aggregate viewership metrics by

Enum: hourdayweekmonthyear

assetIdstring

The asset ID to filter metrics for

streamIdstring

The stream ID to filter metrics for

creatorIdstring

The creator ID to filter the query results

breakdownBy[]array

The list of fields to break down the query results. Specify this query-string multiple times to break down by multiple fields.

get/data/views/query/creator

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/data/views/query/creator

RESPONSE

[
  {
    "playbackId": null,
    "creatorId": null,
    "viewerId": null,
    "dStorageUrl": null,
    "timestamp": 1587667174725,
    "device": null,
    "deviceType": null,
    "cpu": null,
    "os": null,
    "browser": null,
    "browserEngine": null,
    "continent": null,
    "country": null,
    "subdivision": null,
    "timezone": null,
    "geohas": null,
    "viewCount": null,
    "playtimeMins": null,
    "ttffMs": null,
    "rebufferRatio": null,
    "errorRate": null,
    "exitsBeforeStart": null
  }
]

Query public total views metrics

Allows querying for the public metrics for viewership about a video. This can be called from the frontend with a CORS key, or even unauthenticated.

Parameters

playbackIdstring

The playback ID to filter the query results. This can be a canonical playback ID from Livepeer assets or streams, or dStorage identifiers for assets

get/data/views/query/total/{playbackid}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/data/views/query/total/{playbackid}

RESPONSE

{
  "errors": [
    [
      "id not provided",
      "user not found"
    ]
  ]
}

Query usage metrics

Allows querying any metric in its raw form. This can be called from the frontend with a CORS key.

Parameters

frominteger

Start millis timestamp for the query range (inclusive)

tointeger

End millis timestamp for the query range (exclusive)

timeStepstring

The time step to aggregate viewership metrics by

Enum: hourday

creatorIdstring

The creator ID to filter the query results

get/data/usage/query

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/data/usage/query

RESPONSE

{
  "UserID": null,
  "CreatorID": null,
  "DeliveryUsageMins": null,
  "TotalUsageMins": null,
  "StorageUsageMins": null
}

Retrieve sessions

Parameters

No parameters available.

get/session

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/session

RESPONSE

[
  {
    "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "name": "test_session",
    "lastSeen": 1587667174725,
    "sourceSegments": 1,
    "transcodedSegments": 2,
    "sourceSegmentsDuration": 1,
    "transcodedSegmentsDuration": 2,
    "sourceBytes": 1,
    "transcodedBytes": 2,
    "ingestRate": 1,
    "outgoingRate": 2,
    "isHealthy": null,
    "issues": null,
    "createdAt": 1587667174725,
    "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "record": null,
    "recordingStatus": null,
    "recordingUrl": null,
    "mp4Url": null,
    "playbackId": "eaw4nk06ts2d0mzb",
    "profiles": [
      {
        "width": null,
        "name": "720p",
        "height": null,
        "bitrate": null,
        "fps": null,
        "fpsDen": null,
        "gop": null,
        "profile": null,
        "encoder": null
      }
    ]
  }
]

Retrieve a session

Parameters

idstring

ID of the session

get/session/{id}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/session/{id}

RESPONSE

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": "test_session",
  "lastSeen": 1587667174725,
  "sourceSegments": 1,
  "transcodedSegments": 2,
  "sourceSegmentsDuration": 1,
  "transcodedSegmentsDuration": 2,
  "sourceBytes": 1,
  "transcodedBytes": 2,
  "ingestRate": 1,
  "outgoingRate": 2,
  "isHealthy": null,
  "issues": null,
  "createdAt": 1587667174725,
  "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "record": null,
  "recordingStatus": null,
  "recordingUrl": null,
  "mp4Url": null,
  "playbackId": "eaw4nk06ts2d0mzb",
  "profiles": [
    {
      "width": null,
      "name": "720p",
      "height": null,
      "bitrate": null,
      "fps": null,
      "fpsDen": null,
      "gop": null,
      "profile": null,
      "encoder": null
    }
  ]
}

Retrieve Recorded Sessions

Parameters

parentIdstring

ID of the parent stream

recordinteger

Flag indicating if the response should only include recorded sessions

get/stream/{parentId}/sessions

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/stream/{parentId}/sessions

RESPONSE

[
  {
    "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "name": "test_session",
    "lastSeen": 1587667174725,
    "sourceSegments": 1,
    "transcodedSegments": 2,
    "sourceSegmentsDuration": 1,
    "transcodedSegmentsDuration": 2,
    "sourceBytes": 1,
    "transcodedBytes": 2,
    "ingestRate": 1,
    "outgoingRate": 2,
    "isHealthy": null,
    "issues": null,
    "createdAt": 1587667174725,
    "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
    "record": null,
    "recordingStatus": null,
    "recordingUrl": null,
    "mp4Url": null,
    "playbackId": "eaw4nk06ts2d0mzb",
    "profiles": [
      {
        "width": null,
        "name": "720p",
        "height": null,
        "bitrate": null,
        "fps": null,
        "fpsDen": null,
        "gop": null,
        "profile": null,
        "encoder": null
      }
    ]
  }
]

Create a signing key

A signing key is used to sign JWTs and are necessary to make a stream private.

When you create a signing key, the request returns a base64 encoded pem keypair, where

The publicKey is a representation of the public key, encoded as base 64 and is passed as a string,

The privateKey is displayed only on creation. This is the only moment where the client can save the private key, otherwise it will be lost. Remember to decode your string when signing JWTs.

Up to 10 signing keys can be generated, after that you must delete at least one signing key to create a new one.

Parameters

No parameters available.

post/access-control/signing-key

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/access-control/signing-key

RESPONSE

{
  "id": "78df0075-b5f3-4683-a618-1086faca35dc",
  "name": null,
  "createdAt": 1587667174725,
  "lastSeen": 1587667174725,
  "publicKey": null,
  "disabled": null
}

Retrieves signing keys

You can list all the signing keys in your account by making a GET request on /api/access-control/signing-key.

Parameters

No parameters available.

get/access-control/signing-key

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/access-control/signing-key

RESPONSE

[
  {
    "id": "78df0075-b5f3-4683-a618-1086faca35dc",
    "name": null,
    "createdAt": 1587667174725,
    "lastSeen": 1587667174725,
    "publicKey": null,
    "disabled": null
  }
]

Delete Signing Key

Parameters

keyIdstring

ID of the signing key

delete/access-control/signing-key/{keyId}

curl -X DELETE -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/access-control/signing-key/{keyId}

RESPONSE

204 - No Content

Retrieves a signing key

Parameters

keyIdstring

ID of the signing key

get/access-control/signing-key/{keyId}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/access-control/signing-key/{keyId}

RESPONSE

{
  "id": "78df0075-b5f3-4683-a618-1086faca35dc",
  "name": null,
  "createdAt": 1587667174725,
  "lastSeen": 1587667174725,
  "publicKey": null,
  "disabled": null
}

Update a signing key

PATCH /access-control/signing-key/{KEY_ID} updates an existing signing key. It is a single endpoint that can update any of the mutable properties of a stream. Specifically:

name

disabled

All fields are optional, and if any field is not included in the request payload it will be kept unchanged from the saved object.

Parameters

disabledboolean

namestring

keyIdstring

ID of the signing key

patch/access-control/signing-key/{keyId}

curl -X PATCH -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/access-control/signing-key/{keyId}

RESPONSE

204 - No Content

Retrieve Tasks

Parameters

No parameters available.

get/task

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/task

RESPONSE

[
  {
    "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
    "type": null,
    "createdAt": 1587667174725,
    "scheduledAt": 1587667174725,
    "inputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
    "outputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
    "params": {
      "upload": {
        "url": "https://cdn.livepeer.com/ABC123/filename.mp4",
        "encryption": null
      },
      "export": null,
      "exportData": {
        "content": {},
        "ipfs": null,
        "type": null,
        "id": null
      },
      "transcode-file": {
        "input": {
          "url": "https://cdn.livepeer.com/ABC123/filename.mp4"
        },
        "storage": {
          "url": "s3+https://accessKeyId:secretAccessKey@s3Endpoint/bucket"
        },
        "outputs": {
          "hls": {
            "path": "/samplevideo/hls"
          },
          "mp4": {
            "path": "/samplevideo/mp4"
          }
        },
        "profiles": [
          {
            "width": null,
            "name": "720p",
            "height": null,
            "bitrate": null,
            "fps": null,
            "fpsDen": null,
            "gop": null,
            "profile": null,
            "encoder": null
          }
        ],
        "targetSegmentSizeSecs": null,
        "creatorId": null
      },
      "clip": null
    },
    "status": {
      "phase": null,
      "updatedAt": 1587667174725,
      "progress": null,
      "errorMessage": null,
      "retries": null,
      "step": null
    },
    "output": {
      "upload": {
        "videoFilePath": null,
        "metadataFilePath": null,
        "assetSpec": null
      },
      "export": {
        "ipfs": {
          "videoFileCid": null,
          "videoFileUrl": null,
          "videoFileGatewayUrl": null,
          "nftMetadataCid": null,
          "nftMetadataUrl": null,
          "nftMetadataGatewayUrl": null
        }
      },
      "exportData": {
        "ipfs": {
          "cid": null
        }
      }
    }
  }
]

Retrieve a Task

Retrieves the details of a Task, including progress updates and status. Supply the unique Task ID that was returned from your previous request or from an Asset export.

Parameters

taskIdstring

ID of the task

get/task/{taskId}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/task/{taskId}

RESPONSE

{
  "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "type": null,
  "createdAt": 1587667174725,
  "scheduledAt": 1587667174725,
  "inputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "outputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "params": {
    "upload": {
      "url": "https://cdn.livepeer.com/ABC123/filename.mp4",
      "encryption": null
    },
    "export": null,
    "exportData": {
      "content": {},
      "ipfs": null,
      "type": null,
      "id": null
    },
    "transcode-file": {
      "input": {
        "url": "https://cdn.livepeer.com/ABC123/filename.mp4"
      },
      "storage": {
        "url": "s3+https://accessKeyId:secretAccessKey@s3Endpoint/bucket"
      },
      "outputs": {
        "hls": {
          "path": "/samplevideo/hls"
        },
        "mp4": {
          "path": "/samplevideo/mp4"
        }
      },
      "profiles": [
        {
          "width": null,
          "name": "720p",
          "height": null,
          "bitrate": null,
          "fps": null,
          "fpsDen": null,
          "gop": null,
          "profile": null,
          "encoder": null
        }
      ],
      "targetSegmentSizeSecs": null,
      "creatorId": null
    },
    "clip": null
  },
  "status": {
    "phase": null,
    "updatedAt": 1587667174725,
    "progress": null,
    "errorMessage": null,
    "retries": null,
    "step": null
  },
  "output": {
    "upload": {
      "videoFilePath": null,
      "metadataFilePath": null,
      "assetSpec": null
    },
    "export": {
      "ipfs": {
        "videoFileCid": null,
        "videoFileUrl": null,
        "videoFileGatewayUrl": null,
        "nftMetadataCid": null,
        "nftMetadataUrl": null,
        "nftMetadataGatewayUrl": null
      }
    },
    "exportData": {
      "ipfs": {
        "cid": null
      }
    }
  }
}

Transcode a video

POST /transcode transcodes a video file and uploads the results to the specified storage service.

Transcoding is asynchronous so you will need to check the status of the task in order to determine when transcoding is complete. The id field in the response is the unique ID for the transcoding Task. The task status can be queried using the GET tasks endpoint:

When status.phase is completed, transcoding will be complete and the results will be stored in the storage service and the specified output location.

The results will be available under params.outputs.hls.path and params.outputs.mp4.path in the specified storage service.

Input

This endpoint currently supports the following inputs:

HTTP

S3 API Compatible Service

HTTP
A public HTTP URL can be used to read a video file.

{
    "url": "https://www.example.com/video.mp4"
}

Name	Type	Description
url	string	A public HTTP URL for the video file.

Note: For IPFS HTTP gateway URLs, the API currently only supports “path style” URLs and does not support “subdomain style” URLs. The API will support both styles of URLs in a future update.

S3 API Compatible Service

S3 credentials can be used to authenticate with a S3 API compatible service to read a video file.

{
    "type": "s3",
    "endpoint": "https://gateway.storjshare.io",
    "credentials": {
        "accessKeyId": "$ACCESS_KEY_ID",
        "secretAccessKey": "$SECRET_ACCESS_KEY"
    },
    "bucket": "inbucket",
    "path": "/video/source.mp4"
}

Name	Type	Description
type	string	The type of storage service. Supported: "s3".
endpoint	string	The S3 endpoint.
credentials.accessKeyId	string	The S3 access key ID.
credentials.secretAccessKey	string	The S3 access key secret.
bucket	string	The name of the S3 bucket.
path	string	The path within the S3 bucket of the video file.

Storage

This endpoint currently supports the following storage services:

S3 API Compatible Service

Web3 Storage

S3 API Compatible Service

{
  "type": "s3",
    "endpoint": "https://gateway.storjshare.io",
    "credentials": {
        "accessKeyId": "$ACCESS_KEY_ID",
        "secretAccessKey": "$SECRET_ACCESS_KEY"
    },
    "bucket": "mybucket"
}

Name	Type	Description
type	string	The type of storage service.
endpoint	string	The S3 endpoint.
credentials.accessKeyId	string	The S3 access key ID.
credentials.secretAccessKey	string	The S3 access key secret.
bucket	string	The path within the S3 bucket of the video file.

Web3 Storage

{
  "type": "web3.storage",
    "credentials": {
        "proof": "$UCAN_DELEGATION_PROOF",
    }
}

Name	Type	Description
type	string	The type of storage service.
credentials.proof	string	Base64-encoded UCAN delegation proof.

Outputs

This endpoint currently supports the following output types:

HLS

MP4

HLS

{
  "hls": {
        "path": "/samplevideo/hls"
    }
}

Name	Type	Description
path	string	The path of the directory that HLS playlists and mpegts segments will be stored in.

MP4

{
  "mp4": {
        "path": "/samplevideo/mp4"
    }
}

Name	Type	Description
path	string	The path of the directory that MP4 output videos will be stored in.

Parameters

input

One of:

object

URL input video

object

S3-like storage input video

storage

One of:

object

Storage for the output files

object

Storage for the output files

outputsobject

Output formats

profilesarray

Transcode API profile

targetSegmentSizeSecsnumber

How many seconds the duration of each output segment should be

creatorId

One of:

object

One of:

object

string

Helper syntax to specify an unverified creator ID, fully managed by the developer.

post/transcode

curl -X POST -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/transcode

RESPONSE

{
  "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "type": null,
  "createdAt": 1587667174725,
  "scheduledAt": 1587667174725,
  "inputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "outputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "params": {
    "upload": {
      "url": "https://cdn.livepeer.com/ABC123/filename.mp4",
      "encryption": null
    },
    "export": null,
    "exportData": {
      "content": {},
      "ipfs": null,
      "type": null,
      "id": null
    },
    "transcode-file": {
      "input": {
        "url": "https://cdn.livepeer.com/ABC123/filename.mp4"
      },
      "storage": {
        "url": "s3+https://accessKeyId:secretAccessKey@s3Endpoint/bucket"
      },
      "outputs": {
        "hls": {
          "path": "/samplevideo/hls"
        },
        "mp4": {
          "path": "/samplevideo/mp4"
        }
      },
      "profiles": [
        {
          "width": null,
          "name": "720p",
          "height": null,
          "bitrate": null,
          "fps": null,
          "fpsDen": null,
          "gop": null,
          "profile": null,
          "encoder": null
        }
      ],
      "targetSegmentSizeSecs": null,
      "creatorId": null
    },
    "clip": null
  },
  "status": {
    "phase": null,
    "updatedAt": 1587667174725,
    "progress": null,
    "errorMessage": null,
    "retries": null,
    "step": null
  },
  "output": {
    "upload": {
      "videoFilePath": null,
      "metadataFilePath": null,
      "assetSpec": null
    },
    "export": {
      "ipfs": {
        "videoFileCid": null,
        "videoFileUrl": null,
        "videoFileGatewayUrl": null,
        "nftMetadataCid": null,
        "nftMetadataUrl": null,
        "nftMetadataGatewayUrl": null
      }
    },
    "exportData": {
      "ipfs": {
        "cid": null
      }
    }
  }
}

Retrieve Playback Info

You can retrieve the playback information about any playback identifier by calling this endpoint. It accepts playbackIds from any resource in the API as well as dStorage IDs for assets.

Parameters

idstring

The ID of the playback

get/playback/{id}

curl -X GET -H 'content-type: application/json' -d '{}' https://livepeer.studio/api/playback/{id}

RESPONSE

{
  "type": "vod",
  "meta": {
    "live": null,
    "playbackPolicy": null,
    "source": [
      {
        "hrn": "MP4",
        "type": "html5/video/mp4",
        "url": "https://asset-cdn.lp-playback.monster/hls/1bde4o2i6xycudoy/static360p0.mp4",
        "size": 494778,
        "width": 204,
        "height": 360,
        "bitrate": 449890
      }
    ],
    "dvrPlayback": [
      {
        "hrn": "MP4",
        "type": "html5/video/mp4",
        "url": "https://asset-cdn.lp-playback.monster/hls/1bde4o2i6xycudoy/static360p0.mp4",
        "error": null
      }
    ],
    "attestation": null
  }
}

Last updated on 6/1/2023

Contract Addresses Create a stream