Skip to content
Welcome to the new, unified Livepeer documentation! 👋

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

No parameters available.

post/stream
RESPONSE
[]
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


FilterExampleDescription
All stream objects with the same userId/api/stream?streamsonly=1This 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
No parameters available.
get/stream
RESPONSE
[]
Retrieve a stream
In order to retrieve a specific stream, you can just pass the stream id
to this API
Parameters
No parameters available.
get/stream/{id}
RESPONSE
[]
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
    No parameters available.
    patch/stream/{id}
    RESPONSE
    []
    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
    No parameters available.
    delete/stream/{id}
    RESPONSE
    []
    Retrieve Multistream Targets
    Use /multistream/target to a return a list of your existing multistream
targets.
    Parameters
    No parameters available.
    get/multistream/target
    RESPONSE
    []
    Create a multistream target
    Parameters
    No parameters available.
    post/multistream/target
    RESPONSE
    []
    Retrieve a multistream target
    You can retrieve a multistream target from its ID with this API.
    Parameters
    No parameters available.
    get/multistream/target/{id}
    RESPONSE
    []
    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
    No parameters available.
    patch/multistream/target/{id}
    RESPONSE
    []
    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
    No parameters available.
    delete/multistream/target/{id}
    RESPONSE
    []
    Retrieve a Webhook
    Parameters
    No parameters available.
    get/webhook
    RESPONSE
    []
    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
    

    NameDescription
    stream.startedThe parent stream object's isActive value is marked as true and the .m3u8 HLS URL works
    stream.idleThe parent stream object's isActive value should be marked as false and the .m3u8 HLS URL no longer works
    recording.readyThis fires when a recording is ready to be downloaded
    recording.startedThis fires when recording has started on an active stream
    recording.waitingThis 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.connectedThis fires when we've successfully connected to the multistream target
    multistream.errorThis fires when we've encountered an error either while attempting to connect to the third-party streaming service or while broadcasting
    multistream.disconnectedThis fires when we are no longer sending video to the multistream target
    asset.createdThis fires when an On Demand asset is created
    asset.updatedThis fires when an On Demand asset is updated
    asset.readyThis fires when an On Demand asset is ready
    asset.failedThis fires when an On Demand asset fails during the upload or during processing
    asset.deletedThis fires when an On Demand asset is deleted
    task.spawnedThis fires when a task is spawned (e.g., an On Demand upload)
    task.updatedThis fires when a task is updated
    task.completedThis fires when a task completes its execution successfully
    task.failedThis fires when a task has failed
    playback.accessControlA 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
    RESPONSE
    []
    Retrieve a webhook
    Parameters
    No parameters available.
    get/webhook/{id}
    RESPONSE
    []
    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
    No parameters available.
    put/webhook/{id}
    RESPONSE
    []
    Delete a webhook
    Parameters
    No parameters available.
    delete/webhook/{id}
    RESPONSE
    []
    Retrieve assets
    Parameters
    No parameters available.
    get/asset
    RESPONSE
    []
    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
    No parameters available.
    post/asset/request-upload
    RESPONSE
    []
    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
    No parameters available.
    post/asset/upload/url
    RESPONSE
    []
    Retrieves an asset
    Parameters
    No parameters available.
    get/asset/{assetId}
    RESPONSE
    []
    Delete an asset
    Parameters
    No parameters available.
    delete/asset/{assetId}
    RESPONSE
    []
    Create a room
    Create a multiparticipant livestreaming room.
    Parameters
    No parameters available.
    post/room
    RESPONSE
    []
    Retrieve a room
    Parameters
    No parameters available.
    get/room/{id}
    RESPONSE
    []
    Delete a room
    Parameters
    No parameters available.
    delete/room/{id}
    RESPONSE
    []
    Start room RTMP egress
    Create a livestream for your room.
This allows you to leverage livestreaming features like recording and HLS output.
    Parameters
    No parameters available.
    post/room/{id}/egress
    RESPONSE
    []
    Stop room RTMP egress
    Parameters
    No parameters available.
    delete/room/{id}/egress
    RESPONSE
    []
    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
    No parameters available.
    post/room/{id}/user
    RESPONSE
    []
    Get user details
    Parameters
    No parameters available.
    get/room/{id}/user/{userId}
    RESPONSE
    []
    Update a room user
    Update properties for a user.
    Parameters
    No parameters available.
    put/room/{id}/user/{userId}
    RESPONSE
    []
    Remove a user from the room
    Parameters
    No parameters available.
    delete/room/{id}/user/{userId}
    RESPONSE
    []
    Query viewership metrics
    Allows querying any metric in its raw form. Requires a private
(non-CORS) API key to be used.
    Parameters
    No parameters available.
    get/data/views/query
    RESPONSE
    []
    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
    No parameters available.
    get/data/views/query/creator
    RESPONSE
    []
    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
    No parameters available.
    get/data/views/query/total/{playbackid}
    RESPONSE
    []
    Query usage metrics
    Allows querying any metric in its raw form.
This can be called from the frontend with a CORS key.
    Parameters
    No parameters available.
    get/data/usage/query
    RESPONSE
    []
    Retrieve sessions
    Parameters
    No parameters available.
    get/session
    RESPONSE
    []
    Retrieve a session
    Parameters
    No parameters available.
    get/session/{id}
    RESPONSE
    []
    Retrieve Recorded Sessions
    Parameters
    No parameters available.
    get/stream/{parentId}/sessions
    RESPONSE
    []
    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
    RESPONSE
    []
    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
    RESPONSE
    []
    Delete Signing Key
    Parameters
    No parameters available.
    delete/access-control/signing-key/{keyId}
    RESPONSE
    []
    Retrieves a signing key
    Parameters
    No parameters available.
    get/access-control/signing-key/{keyId}
    RESPONSE
    []
    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
    No parameters available.
    patch/access-control/signing-key/{keyId}
    RESPONSE
    []
    Retrieve Tasks
    Parameters
    No parameters available.
    get/task
    RESPONSE
    []
    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
    No parameters available.
    get/task/{taskId}
    RESPONSE
    []
    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"
}

    

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

    

    NameTypeDescription
    typestringThe type of storage service. Supported: "s3".
    endpointstringThe S3 endpoint.
    credentials.accessKeyIdstringThe S3 access key ID.
    credentials.secretAccessKeystringThe S3 access key secret.
    bucketstringThe name of the S3 bucket.
    pathstringThe 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"
}

    

    NameTypeDescription
    typestringThe type of storage service.
    endpointstringThe S3 endpoint.
    credentials.accessKeyIdstringThe S3 access key ID.
    credentials.secretAccessKeystringThe S3 access key secret.
    bucketstringThe path within the S3 bucket of the video file.
    

    Web3 Storage
    

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

    

    NameTypeDescription
    typestringThe type of storage service.
    credentials.proofstringBase64-encoded UCAN delegation proof.
    

    Outputs
    


    
This endpoint currently supports the following output types:
    

    

  • HLS
    • 

  • MP4
    • 

    

    HLS
    

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

    

    NameTypeDescription
    pathstringThe path of the directory that HLS playlists and mpegts segments will be stored in.
    

    MP4
    

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

    

    NameTypeDescription
    pathstringThe path of the directory that MP4 output videos will be stored in.
    Parameters
    No parameters available.
    post/transcode
    RESPONSE
    []
    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
    No parameters available.
    get/playback/{id}
    RESPONSE
    []
    Contract AddressesCreate a stream