OpenAPI Specification
openapi: 3.1.0
info:
title: Livepeer API Reference accessControl session API
description: 'Welcome to the Livepeer API reference docs. Here you will find all the
endpoints exposed on the standard Livepeer API, learn how to use them and
what they return.
'
version: 1.0.0
servers:
- url: https://livepeer.studio/api
security:
- apiKey: []
tags:
- name: session
description: Operations related to session api
paths:
/session/{id}/clips:
get:
operationId: getSessionClips
x-speakeasy-name-override: getClips
summary: Retrieve clips of a session
tags:
- session
parameters:
- in: path
name: id
schema:
type: string
description: ID of the parent session
required: true
responses:
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/asset'
x-speakeasy-name-override: data
x-codeSamples:
- lang: typescript
label: getSessionClips
source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n const result = await livepeer.session.getClips(\"<id>\");\n\n // Handle the result\n console.log(result);\n}\n\nrun();"
- lang: go
label: getSessionClips
source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n s := livepeergo.New(\n livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n )\n\n ctx := context.Background()\n res, err := s.Session.GetClips(ctx, \"<id>\")\n if err != nil {\n log.Fatal(err)\n }\n if res.Data != nil {\n // handle response\n }\n}"
- lang: python
label: getSessionClips
source: "from livepeer import Livepeer\n\ns = Livepeer(\n api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.session.get_clips(id=\"<id>\")\n\nif res.data is not None:\n # handle response\n pass"
/session:
get:
operationId: getSessions
x-speakeasy-name-override: getAll
summary: Retrieve sessions
tags:
- session
responses:
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/session'
x-speakeasy-name-override: data
x-codeSamples:
- lang: typescript
label: getSessions
source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n const result = await livepeer.session.getAll();\n\n // Handle the result\n console.log(result);\n}\n\nrun();"
- lang: go
label: getSessions
source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n s := livepeergo.New(\n livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n )\n\n ctx := context.Background()\n res, err := s.Session.GetAll(ctx)\n if err != nil {\n log.Fatal(err)\n }\n if res.Data != nil {\n // handle response\n }\n}"
- lang: python
label: getSessions
source: "from livepeer import Livepeer\n\ns = Livepeer(\n api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.session.get_all()\n\nif res.data is not None:\n # handle response\n pass"
/session/{id}:
get:
operationId: getSession
x-speakeasy-name-override: get
summary: Retrieve a session
tags:
- session
parameters:
- in: path
name: id
schema:
type: string
description: ID of the session
required: true
responses:
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/session'
x-speakeasy-name-override: data
x-codeSamples:
- lang: typescript
label: getSession
source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n const result = await livepeer.session.get(\"<id>\");\n\n // Handle the result\n console.log(result);\n}\n\nrun();"
- lang: go
label: getSession
source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n s := livepeergo.New(\n livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n )\n\n ctx := context.Background()\n res, err := s.Session.Get(ctx, \"<id>\")\n if err != nil {\n log.Fatal(err)\n }\n if res.Session != nil {\n // handle response\n }\n}"
- lang: python
label: getSession
source: "from livepeer import Livepeer\n\ns = Livepeer(\n api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.session.get(id=\"<id>\")\n\nif res.session is not None:\n # handle response\n pass"
/stream/{parentId}/sessions:
get:
operationId: getRecordedSessions
x-speakeasy-name-override: getRecorded
summary: Retrieve Recorded Sessions
tags:
- session
parameters:
- in: path
name: parentId
schema:
type: string
description: ID of the parent stream
required: true
- in: query
name: record
schema:
oneOf:
- type: boolean
- type: integer
example: true
description: 'Flag indicating if the response should only include recorded
sessions
'
responses:
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/session'
x-speakeasy-name-override: data
x-codeSamples:
- lang: typescript
label: getRecordedSessions
source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n const result = await livepeer.session.getRecorded(\"<id>\", true);\n\n // Handle the result\n console.log(result);\n}\n\nrun();"
- lang: go
label: getRecordedSessions
source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n s := livepeergo.New(\n livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n )\n\n ctx := context.Background()\n res, err := s.Session.GetRecorded(ctx, \"<value>\", livepeergo.Pointer(operations.CreateRecordBoolean(\n true,\n )))\n if err != nil {\n log.Fatal(err)\n }\n if res.Data != nil {\n // handle response\n }\n}"
- lang: python
label: getRecordedSessions
source: "from livepeer import Livepeer\n\ns = Livepeer(\n api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.session.get_recorded(parent_id=\"<value>\", record=True)\n\nif res.data is not None:\n # handle response\n pass"
components:
schemas:
storage-status:
readOnly: true
additionalProperties: false
required:
- phase
- tasks
properties:
phase:
type: string
description: Phase of the asset storage
enum:
- waiting
- processing
- ready
- failed
- reverted
example: ready
progress:
type: number
description: Current progress of the task updating the storage.
example: 0.5
errorMessage:
type: string
description: Error message if the last storage changed failed.
example: Failed to update storage
tasks:
type: object
additionalProperties: false
properties:
pending:
type: string
description: 'ID of any currently running task that is exporting this
asset to IPFS.
'
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
last:
type: string
description: 'ID of the last task to run successfully, that created
the currently saved data.
'
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
failed:
type: string
description: ID of the last task to fail execution.
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
creator-id:
oneOf:
- type: object
additionalProperties: false
required:
- type
- value
properties:
type:
type: string
enum:
- unverified
example: unverified
value:
type: string
description: Developer-managed ID of the user who created the resource.
example: user123
new-asset-payload:
properties:
encryption:
type: object
additionalProperties: false
required:
- encryptedKey
properties:
encryptedKey:
type: string
writeOnly: true
description: Encryption key used to encrypt the asset. Only writable in the upload asset endpoints and cannot be retrieved back.
ipfs-file-info:
type: object
required:
- cid
additionalProperties: false
properties:
cid:
type: string
description: CID of the file on IPFS
url:
readOnly: true
type: string
description: URL with IPFS scheme for the file
gatewayUrl:
readOnly: true
type: string
description: URL to access file via HTTP through an IPFS gateway
stream-health-payload:
properties:
is_healthy:
oneOf:
- type: 'null'
- type: boolean
description: Indicates whether the stream is healthy or not.
human_issues:
oneOf:
- type: 'null'
- type: array
items:
type: string
description: A string array of human-readable errors describing issues affecting the stream, if any.
stream:
properties:
profiles:
type: array
description: 'Profiles to transcode the stream into. If not specified, a default
set of profiles will be used with 240p, 360p, 480p and 720p
resolutions. Keep in mind that the source rendition is always kept.
'
default:
- name: 240p0
fps: 0
bitrate: 250000
width: 426
height: 240
- name: 360p0
fps: 0
bitrate: 800000
width: 640
height: 360
- name: 480p0
fps: 0
bitrate: 1600000
width: 854
height: 480
- name: 720p0
fps: 0
bitrate: 3000000
width: 1280
height: 720
items:
$ref: '#/components/schemas/ffmpeg-profile'
recordingSpec:
type: object
description: 'Configuration for recording the stream. This can only be set if
`record` is true.
'
additionalProperties: false
properties:
profiles:
type: array
items:
$ref: '#/components/schemas/transcode-profile'
description: 'Profiles to process the recording of this stream into. If not
specified, default profiles will be derived based on the stream
input. Keep in mind that the source rendition is always kept.
'
error:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: string
example:
- id not provided
- Account not found
playback-policy:
type:
- object
- 'null'
description: Whether the playback policy for an asset or stream is public or signed
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- public
- jwt
- webhook
example: webhook
webhookId:
type: string
description: ID of the webhook to use for playback policy
example: 1bde4o2i6xycudoy
webhookContext:
type: object
description: User-defined webhook context
additionalProperties: true
example:
streamerId: my-custom-id
refreshInterval:
type: number
description: 'Interval (in seconds) at which the playback policy should be
refreshed (default 600 seconds)
'
example: 600
allowedOrigins:
type: array
description: List of allowed origins for CORS playback (<scheme>://<hostname>:<port>, <scheme>://<hostname>)
items:
type: string
ffmpeg-profile:
type: object
description: Transcode profile
additionalProperties: false
required:
- width
- name
- height
- bitrate
- fps
properties:
width:
type: integer
minimum: 128
example: 1280
name:
type: string
minLength: 1
maxLength: 500
example: 720p
height:
type: integer
minimum: 128
example: 720
bitrate:
type: integer
minimum: 400
example: 3000000
fps:
type: integer
minimum: 0
example: 30
fpsDen:
type: integer
minimum: 1
example: 1
quality:
type: integer
description: 'Restricts the size of the output video using the constant quality feature. Increasing this value will result in a lower quality video. Note that this parameter might not work if the transcoder lacks support for it.
'
minimum: 0
maximum: 44
example: 23
gop:
type: string
example: 2
profile:
type: string
enum:
- H264Baseline
- H264Main
- H264High
- H264ConstrainedHigh
example: H264Baseline
encoder:
type: string
enum:
- H.264
asset:
type: object
additionalProperties: false
required:
- id
- name
- source
properties:
id:
type: string
readOnly: true
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
type:
type: string
enum:
- video
- audio
description: Type of the asset.
example: video
playbackId:
type: string
example: eaw4nk06ts2d0mzb
description: The playback ID to use with the Playback Info endpoint to retrieve playback URLs.
userId:
type: string
readOnly: true
example: 66E2161C-7670-4D05-B71D-DA2D6979556F
deprecated: true
staticMp4:
type: boolean
writeOnly: true
description: Whether to generate MP4s for the asset.
playbackUrl:
readOnly: true
type: string
example: https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8
description: URL for HLS playback. **It is recommended to not use this URL**, and instead use playback IDs with the Playback Info endpoint to retrieve the playback URLs - this URL format is subject to change (e.g. https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8).
downloadUrl:
readOnly: true
type: string
example: https://livepeercdn.com/asset/eaw4nk06ts2d0mzb/video/download.mp4
description: The URL to directly download the asset, e.g. `https://livepeercdn.com/asset/eawrrk06ts2d0mzb/video`. It is not recommended to use this for playback.
playbackPolicy:
$ref: '#/components/schemas/playback-policy'
source:
oneOf:
- additionalProperties: false
required:
- type
- url
properties:
type:
type: string
enum:
- url
url:
type: string
description: URL from which the asset was uploaded.
gatewayUrl:
type: string
description: Gateway URL from asset if parsed from provided URL on upload.
encryption:
$ref: '#/components/schemas/new-asset-payload/properties/encryption'
- additionalProperties: false
required:
- type
- sessionId
properties:
type:
type: string
enum:
- recording
sessionId:
type: string
description: ID of the session from which this asset was created
- additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- directUpload
- clip
encryption:
$ref: '#/components/schemas/new-asset-payload/properties/encryption'
sourceId:
type: string
description: ID of the asset or stream from which this asset was created.
sessionId:
type: string
description: ID of the session from which this asset was created.
playbackId:
type: string
description: Playback ID of the asset or stream from which this asset was created.
requesterId:
type: string
description: ID of the requester from which this asset was created.
assetId:
type: string
description: ID of the asset from which this asset was created.
creatorId:
$ref: '#/components/schemas/creator-id'
profiles:
type: array
description: 'Requested profiles for the asset to be transcoded into. Configured
on the upload APIs payload or through the `stream.recordingSpec`
field for recordings. If not specified, default profiles are derived
based on the source input. If this is a recording, the source will
not be present in this list but will be available for playback.
'
items:
$ref: '#/components/schemas/transcode-profile'
storage:
type: object
additionalProperties: false
properties:
ipfs:
type: object
additionalProperties: false
properties:
spec:
type: object
additionalProperties: false
default: {}
properties:
nftMetadataTemplate:
type: string
enum:
- file
- player
default: file
description: 'Name of the NFT metadata template to export. ''player''
will embed the Livepeer Player on the NFT while ''file''
will reference only the immutable MP4 files.
'
nftMetadata:
type: object
description: 'Additional data to add to the NFT metadata exported to
IPFS. Will be deep merged with the default metadata
exported.
'
$ref: {}
nftMetadata:
$ref: '#/components/schemas/ipfs-file-info'
updatedAt:
readOnly: true
type: number
description: 'Timestamp (in milliseconds) at which IPFS export task was
updated
'
example: 1587667174725
status:
$ref: '#/components/schemas/storage-status'
status:
readOnly: true
type: object
additionalProperties: false
required:
- phase
- updatedAt
description: Status of the asset
properties:
phase:
type: string
description: Phase of the asset
enum:
- uploading
- waiting
- processing
- ready
- failed
- deleting
- deleted
updatedAt:
type: number
description: Timestamp (in milliseconds) at which the asset was last updated
example: 1587667174725
progress:
type: number
description: Current progress of the task creating this asset.
errorMessage:
type: string
description: Error message if the asset creation failed.
name:
type: string
description: 'The name of the asset. This is not necessarily the filename - it can be a custom name or title.
'
example: filename.mp4
projectId:
type: string
description: The ID of the project
example: aac12556-4d65-4d34-9fb6-d1f0985eb0a9
createdAt:
readOnly: true
type: number
description: Timestamp (in milliseconds) at which asset was created
example: 1587667174725
createdByTokenName:
type: string
readOnly: true
description: Name of the token used to create this object
size:
readOnly: true
type: number
description: Size of the asset in bytes
example: 84934509
hash:
type:
- array
- 'null'
description: Hash of the asset
items:
type: object
additionalProperties: false
properties:
hash:
type: string
description: Hash of the asset
example: 9b560b28b85378a5004117539196ab24e21bbd75b0e9eb1a8bc7c5fd80dc5b57
algorithm:
type: string
description: Hash algorithm used to compute the hash
example: sha256
videoSpec:
readOnly: true
type: object
additionalProperties: false
description: Video metadata
properties:
format:
type: string
description: Format of the asset
example: mp4
duration:
type: number
description: Duration of the asset in seconds (float)
example: 23.8328
bitrate:
type: number
description: Bitrate of the video in bits per second
example: 1000000
tracks:
type: array
description: 'List of tracks associated with the asset when the format
contemplates them (e.g. mp4)
'
items:
type: object
additionalProperties: false
required:
- type
- codec
properties:
type:
type: string
description: type of track
enum:
- video
- audio
example: video
codec:
type: string
description: Codec of the track
example: aac
startTime:
type: number
description: Start time of the track in seconds
example: 23.8238
duration:
type: number
description: Duration of the track in seconds
example: 23.8238
bitrate:
type: number
description: Bitrate of the track in bits per second
example: 1000000
width:
type: number
description: Width of the track - only for video tracks
example: 1920
height:
type: number
description: Height of the track - only for video tracks
example: 1080
pixelFormat:
type: string
description: Pixel format of the track - only for video tracks
example: yuv420p
fps:
type: number
description: Frame rate of the track - only for video tracks
example: 30
channels:
type: number
description: Amount of audio channels in the track
example: 2
sampleRate:
type: number
description: 'Sample rate of the track in samples per second - only for
audio tracks
'
example: 44100
bitDepth:
type: number
description: Bit depth of the track - only for audio tracks
example: 16
session:
type: object
required:
- name
- streamId
additionalProperties: false
properties:
id:
type: string
readOnly: true
example: de7818e7-610a-4057-8f6f-b785dc1e6f88
kind:
type: string
example: stream
deprecated: true
userId:
type: string
readOnly: true
example: 66E2161C-7670-4D05-B71D-DA2D6979556F
deprecated: true
name:
type: string
example: test_session
lastSeen:
type: number
example: 1587667174725
sourceSegments:
type: number
example: 1
transcodedSegments:
type: number
example: 2
sourceSegmentsDuration:
type: number
example: 1
description: Duration of all the source segments, sec
transcodedSegmentsDuration:
type: number
example: 2
description: Duration of all the transcoded segments, sec
sourceBytes:
type: number
example: 1
transcodedBytes:
type: number
example: 2
ingestRate:
type: number
example: 1
description: Rate at which sourceBytes increases (bytes/second)
outgoingRate:
type: number
example: 2
description: Rate at which transcodedBytes increases (bytes/second)
isHealthy:
$ref: '#/components/schemas/stream-health-payload/properties/is_healthy'
issues:
$ref: '#/components/schemas/stream-health-payload/properties/human_issues'
createdAt:
readOnly: true
type: number
description: Timestamp (in milliseconds) at which stream object was created
example: 1587667174725
parentId:
type: string
example: de7818e7-610a-4057-8f6f-b785dc1e6f88
description: Points to parent stream object
projectId:
type: string
description: The ID of the project
example: aac12556-4d65-4d34-9fb6-d1f0985eb0a9
record:
description: 'Whether the stream should be recorded. Uses default settings. For more customization, create and configure an object store.
'
type: boolean
example: false
recordingStatus:
readOnly: true
type: string
description: The status of the recording process of this stream session.
enum:
- waiting
- ready
- failed
- deleted
- none
recordingUrl:
type: string
readOnly: true
description: URL for accessing the recording of this stream session.
mp4Url:
type: string
readOnly: true
description: The URL for the stream session recording packaged in an MP4.
playbackId:
type: string
example: eaw4nk06ts2d0mzb
description: The playback ID to use with the Playback Info endpoint to retrieve playback URLs.
profiles:
$ref: '#/components/schemas/stream/properties/profiles'
recordingSpec:
$ref: '#/components/schemas/stream/properties/recordingSpec'
transcode-profile:
type: object
description: Transcode API profile
additionalProperties: false
required:
- bitrate
properties:
width:
type: integer
minimum: 128
example: 1280
name:
type: string
minLength: 1
maxLength: 500
example: 720p
height:
type: integer
minimum: 128
example: 720
bitrate:
type: integer
minimum: 400
example: 3000000
quality:
type: integer
description: 'Restricts the size of the output video using the constant quality feature. Increasing this value will result in a lower quality video. Note that this parameter might not work if the transcoder lacks support for it.
'
minimum: 0
maximum: 44
example: 23
fps:
type: integer
minimum: 0
example: 30
fpsDen:
type: integer
minimum: 1
example: 1
gop:
type: string
example: 2
profile:
type: string
enum:
- H264Baseline
- H264Main
- H264High
- H264ConstrainedHigh
example: H264Baseline
encoder:
type: string
enum:
- H.264
- HEVC
- VP8
- VP9
example: H.264
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: JWT
HTTPBearer:
type: http
scheme: bearer