Livepeer Studio API

openapi: 3.1.0
info:
  title: Livepeer API Reference
  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: stream
    description: Operations related to livestream api
  - name: asset
    description: Operations related to asset/vod api
  - name: webhook
    description: Operations related to webhook api
  - name: multistream
    description: Operations related to multistream api
  - name: session
    description: Operations related to session api
  - name: room
    description: Operations related to rooms api
  - name: transcode
    description: Operations related to transcode api
  - name: metrics
    description: Operations related to metrics api
  - name: playback
    description: Operations related to playback api
  - name: accessControl
    description: Operations related to access control/signing keys api
  - name: task
    description: Operations related to tasks api
  - name: generate
    description: Operations related to AI generate api
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
    HTTPBearer:
      type: http
      scheme: bearer
  schemas:
    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
    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
    webhook:
      type: object
      required:
        - name
        - url
      additionalProperties: false
      properties:
        id:
          type: string
          readOnly: true
          example: de7818e7-610a-4057-8f6f-b785dc1e6f88
        name:
          type: string
          example: test_webhook
        kind:
          type: string
          example: webhook
          readOnly: true
          deprecated: true
        userId:
          type: string
          readOnly: true
          deprecated: true
        projectId:
          type: string
          description: The ID of the project
          example: aac12556-4d65-4d34-9fb6-d1f0985eb0a9
        createdAt:
          type: number
          readOnly: true
          description:
            Timestamp (in milliseconds) at which stream object was created
          example: 1587667174725
        events:
          type: array
          items:
            type: string
            enum:
              - stream.started
              - stream.detection
              - stream.idle
              - recording.ready
              - recording.started
              - recording.waiting
              - multistream.connected
              - multistream.error
              - multistream.disconnected
              - playback.user.new
              - playback.accessControl
              - asset.created
              - asset.updated
              - asset.failed
              - asset.ready
              - asset.deleted
              - task.spawned
              - task.updated
              - task.completed
              - task.failed
          example:
            - stream.started
            - stream.idle
        url:
          type: string
          format: uri
          pattern: "^http(s)?://"
          example: "https://my-service.com/webhook"
        sharedSecret:
          type: string
          writeOnly: true
          description: shared secret used to sign the webhook payload
          example: my-secret
        streamId:
          type: string
          description: streamId of the stream on which the webhook is applied
          example: de7818e7-610a-4057-8f6f-b785dc1e6f88
        status:
          type: object
          readOnly: true
          description: status of webhook
          properties:
            lastFailure:
              type: object
              readOnly: true
              description: failure timestamp and error message with status code
              properties:
                timestamp:
                  type: number
                  readOnly: true
                  example: 1587667174725
                  description:
                    Timestamp (in milliseconds) at which the webhook last failed
                error:
                  readOnly: true
                  type: string
                  description: Webhook failure error message
                  example: Error message
                response:
                  readOnly: true
                  type: string
                  description: Webhook failure response
                  example: Response body
                statusCode:
                  readOnly: true
                  type: number
                  description: Webhook failure status code
                  example: 500
            lastTriggeredAt:
              type: number
              description: |
                Timestamp (in milliseconds) at which the webhook last was
                triggered
              example: 1587667174725
    webhook-log:
      type: object
      required:
        - id
        - webhookId
      additionalProperties: false
      properties:
        id:
          type: string
          readOnly: true
          example: de7818e7-610a-4057-8f6f-b785dc1e6f88
        webhookId:
          readOnly: true
          type: string
          description: ID of the webhook this request was made for
          example: de7818e7-610a-4057-8f6f-b785dc1e6f88
        event:
          readOnly: true
          type: string
          description: The event type that triggered the webhook request
          example: stream.started
        createdAt:
          readOnly: true
          type: number
          description: |
            Timestamp (in milliseconds) at which webhook request object was
            created
          example: 1587667174725
        duration:
          type: number
          description: The time taken (in seconds) to make the webhook request
          example: 0.5
        success:
          type: boolean
          description: Whether the webhook request was successful
          example: true
        request:
          type: object
          properties:
            url:
              type: string
              description: URL used for the request
              example: "https://my-service.com/webhook"
            method:
              type: string
              description: HTTP request method
              example: POST
            headers:
              type: object
              description: HTTP request headers
              additionalProperties:
                type: string
              example:
                User-Agent: livepeer.studio
            body:
              type: string
              description: request body
              example: '{"event": "stream.started"}'
        response:
          type: object
          additionalProperties: false
          properties:
            body:
              type: string
              description: response body
            status:
              type: number
              description: HTTP status code
            statusText:
              type: string
              description: response status text
    clip-payload:
      type: object
      additionalProperties: false
      required:
        - playbackId
        - startTime
      properties:
        playbackId:
          type: string
          description: >-
            The playback ID of the stream or stream recording to clip. Asset
            playback IDs are not supported yet.
          example: eaw4nk06ts2d0mzb
        startTime:
          type: number
          description: >-
            The start timestamp of the clip in Unix milliseconds. _See the
            ClipTrigger in the UI Kit for an example of how this is calculated
            (for HLS, it uses `Program Date-Time` tags, and for WebRTC, it uses
            the latency from server to client at stream startup)._
          example: 1587667174725
        endTime:
          type: number
          description: >-
            The end timestamp of the clip in Unix milliseconds. _See the
            ClipTrigger in the UI Kit for an example of how this is calculated
            (for HLS, it uses `Program Date-Time` tags, and for WebRTC, it uses
            the latency from server to client at stream startup)._
          example: 1587667174725
        name:
          type: string
          description: The optional friendly name of the clip to create.
          example: My Clip
        sessionId:
          type: string
          description: >-
            The optional session ID of the stream to clip. This can be used to
            clip _recordings_ - if it is not specified, it will clip the ongoing
            livestream.
          example: de7818e7-610a-4057-8f6f-b785dc1e6f88
    target:
      type: object
      required:
        - profile
      additionalProperties: false
      properties:
        profile:
          type: string
          description: |
            Name of transcoding profile that should be sent. Use
            "source" for pushing source stream data
          minLength: 1
          maxLength: 500
          example: 720p0
        videoOnly:
          type: boolean
          description: |
            If true, the stream audio will be muted and only silent
            video will be pushed to the target.
          default: false
          example: false
        id:
          type: string
          description: ID of multistream target object where to push this stream
          example: PUSH123
        spec:
          type: object
          writeOnly: true
          description: |
            Inline multistream target object. Will automatically
            create the target resource to be used by the created
            stream.
          required:
            - url
          additionalProperties: false
          properties:
            name:
              type: string
              example: My target
            url:
              $ref: "#/components/schemas/multistream-target/properties/url"
    project:
      type: object
      required:
        - name
      additionalProperties: false
      properties:
        id:
          type: string
          readOnly: true
          example: de7818e7-610a-4057-8f6f-b785dc1e6f88
        name:
          type: string
          example: test_project
        createdAt:
          type: number
          readOnly: true
          description:
            Timestamp (in milliseconds) at which stream object was created
          example: 1587667174725
    stream:
      type: object
      required:
        - name
      additionalProperties: false
      properties:
        id:
          type: string
          readOnly: true
          example: de7818e7-610a-4057-8f6f-b785dc1e6f88
        name:
          type: string
          example: test_stream
        kind:
          type: string
          example: stream
          deprecated: true
        creatorId:
          $ref: "#/components/schemas/creator-id"
        userTags:
          type: object
          description: User input tags associated with the stream
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: array
                items:
                  oneOf:
                    - type: string
                    - type: number
        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)
        isActive:
          type: boolean
          description: If currently active
          example: true
        isHealthy:
          $ref: "#/components/schemas/stream-health-payload/properties/is_healthy"
        issues:
          $ref: "#/components/schemas/stream-health-payload/properties/human_issues"
        createdByTokenName:
          type: string
          readOnly: true
          description: Name of the token used to create this object
          example: abc-123-xyz-456
        createdAt:
          type: number
          readOnly: true
          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
        streamKey:
          type: string
          example: hgebdhhigq
          description: Used to form RTMP ingest URL
        pull:
          type: object
          description: |-
            Configuration for a stream that should be actively pulled from an
            external source, rather than pushed to Livepeer. If specified, the
            stream will not have a streamKey.
          additionalProperties: false
          required:
            - source
          properties:
            source:
              type: string
              description: |-
                URL from which to pull from.
              example: https://myservice.com/live/stream.flv
            headers:
              type: object
              description: |-
                Headers to be sent with the request to the pull source.
              additionalProperties:
                type: string
              example:
                Authorization: "Bearer 123"
            isMobile:
              oneOf:
                - type: integer
                  enum:
                    - 0
                    - 1
                    - 2
                  description: |-
                    0: not mobile, 1: mobile screen share, 2: mobile camera.
                - type: boolean
                  description: |-
                    If true, the stream will be pulled from a mobile source.
              description: |-
                Indicates whether the stream will be pulled from a mobile source.
              default: 0
            location:
              type: object
              description: |-
                Approximate location of the pull source. The location is used to
                determine the closest Livepeer region to pull the stream from.
              additionalProperties: false
              required:
                - lat
                - lon
              properties:
                lat:
                  type: number
                  description: |-
                    Latitude of the pull source in degrees. North is positive,
                    south is negative.
                  example: 39.739
                lon:
                  type: number
                  description: |-
                    Longitude of the pull source in degrees. East is positive,
                    west is negative.
                  example: -104.988
        playbackId:
          type: string
          example: eaw4nk06ts2d0mzb
          description:
            The playback ID to use with the Playback Info endpoint to retrieve
            playback URLs.
        playbackPolicy:
          $ref: "#/components/schemas/playback-policy"
        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"
        projectId:
          type: string
          description: The ID of the project
          example: aac12556-4d65-4d34-9fb6-d1f0985eb0a9
        record:
          description: |
            Should this stream be recorded? Uses default settings. For more
            customization, create and configure an object store.
          type: boolean
          example: false
        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.
        multistream:
          type: object
          additionalProperties: false
          properties:
            targets:
              type: array
              example:
                - id: PUSH123
                  profile: 720p
              description: |
                References to targets where this stream will be simultaneously
                streamed to
              items:
                $ref: "#/components/schemas/target"
        suspended:
          type: boolean
          description: If currently suspended
        lastTerminatedAt:
          type:
            - number
            - "null"
          example: 1713281212993
          description:
            Timestamp (in milliseconds) when the stream was last terminated
        userId:
          type: string
          readOnly: true
          example: "we7818e7-610a-4057-8f6f-b785dc1e6f88"
          deprecated: true
        renditions:
          type: object
    new-stream-payload:
      type: object
      required:
        - name
      additionalProperties: false
      properties:
        name:
          $ref: "#/components/schemas/stream/properties/name"
        pull:
          $ref: "#/components/schemas/stream/properties/pull"
        creatorId:
          $ref: "#/components/schemas/input-creator-id"
        playbackPolicy:
          $ref: "#/components/schemas/playback-policy"
        profiles:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/ffmpeg-profile"
          default:
            $ref: "#/components/schemas/stream/properties/profiles/default"
        record:
          $ref: "#/components/schemas/stream/properties/record"
        recordingSpec:
          type: object
          additionalProperties: false
          properties:
            profiles:
              type:
                - array
                - "null"
              items:
                $ref: "#/components/schemas/transcode-profile"
        multistream:
          $ref: "#/components/schemas/stream/properties/multistream"
        userTags:
          $ref: "#/components/schemas/stream/properties/userTags"
    asset-patch-payload:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: "#/components/schemas/asset/properties/name"
        creatorId:
          $ref: "#/components/schemas/input-creator-id"
        playbackPolicy:
          $ref: "#/components/schemas/playback-policy"
        storage:
          $ref: "#/components/schemas/new-asset-payload/properties/storage"
    stream-patch-payload:
      type: object
      additionalProperties: false
      properties:
        creatorId:
          $ref: "#/components/schemas/input-creator-id"
        record:
          $ref: "#/components/schemas/stream/properties/record"
        suspended:
          $ref: "#/components/schemas/stream/properties/suspended"
        multistream:
          $ref: "#/components/schemas/stream/properties/multistream"
        playbackPolicy:
          $ref: "#/components/schemas/playback-policy"
        profiles:
          $ref: "#/components/schemas/new-stream-payload/properties/profiles"
        recordingSpec:
          $ref: "#/components/schemas/new-stream-payload/properties/recordingSpec"
        userTags:
          $ref: "#/components/schemas/stream/properties/userTags"
        name:
          $ref: "#/components/schemas/stream/properties/name"
    target-add-payload:
      type: object
      additionalProperties: false
      $ref: "#/components/schemas/target"
    stream-health-payload:
      type: object
      description: |
        Payload received from Catalyst about the health of livestreams currently
        or recently active on Mist.
      required:
        - stream_name
        - is_active
        - is_healthy
      properties:
        stream_name:
          type: string
          description: |
            The name of the stream within Catalyst/Mist, normally comprised of
            the base stream name with the playback ID after the + sign.
          example: videorec+eaw4nk06ts2d0mzb
        session_id:
          description: |
            The unique identifier for the specific session, created by Mist and
            used for creating the session object in the DB.
          type: string
        is_active:
          type: boolean
          description: Indicates whether the stream is currently live or not.
        is_healthy:
          oneOf:
            - type: "null"
            - type: "boolean"
          description: "Indicates whether the stream is healthy or not."
        issues:
          oneOf:
            - type: "null"
            - type: "string"
          description: |
            "Raw issues affecting the stream as described by Mist, if any. We don't expose those to the end-user, showing only human_issues instead."
        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."
        tracks:
          type: object
          description: |
            A map of track objects containing information about the stream's
            tracks. The keys are the unique track ID from Mist.
          additionalProperties:
            type: object
            properties:
              codec:
                type: string
                description: The codec being used for the track.
              kbits:
                type: number
                description: "The bitrate of the track, in kilobits per second."
              keys:
                type: object
                description:
                  An object containing additional track-specific metrics.
                additionalProperties:
                  type: number
              fpks:
                type: number
                description: |
                  The framerate of the track, in frames per thousand seconds
                  (kilo-second).
              height:
                type: number
                description: The height of the track's video resolution.
              width:
                type: number
                description: The width of the track's video resolution.
        extra:
          type: object
          description: |
            An object containing any additional fields sent by mist in the
            health (STREAM_BUFFER) payload.
          additionalProperties: true
    multistream-target-patch-payload:
      $ref: "#/components/schemas/multistream-target"
      required: []
    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"
    error:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: string
            example:
              - id not provided
              - Account not found
    multistream-target:
      type: object
      required:
        - url
      additionalProperties: false
      properties:
        id:
          type: string
          readOnly: true
          example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
        name:
          type: string
        userId:
          type: string
          readOnly: true
          example: 66E2161C-7670-4D05-B71D-DA2D6979556F
          deprecated: true
        url:
          type: string
          writeOnly: true
          description:
            Livepeer-compatible multistream target URL (RTMP(S) or SRT)
          example: "rtmps://live.my-service.tv/channel/secretKey"
          format: uri
          pattern: "^(srt|rtmps?)://"
        disabled:
          type: boolean
          description: |
            If true then this multistream target will not be used for pushing
            even if it is configured in a stream object.
        createdAt:
          type: number
          readOnly: true
          description: |
            Timestamp (in milliseconds) at which multistream target object was
            created
          example: 1587667174725
    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
     

# --- truncated at 32 KB (304 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/livepeer-com/refs/heads/main/openapi/livepeer-studio-openapi.yml