Lightstream SourceService API

openapi: 3.2.0
info:
  title: Event AuthenticationService Source Service API
  version: '2.0'
  description: The Authentication Service provides token services for clients
servers:
- url: https://live.api.stream/event/v2
tags:
- name: SourceService
  description: The Source Service operates on Collection Live Sources and Project Sources.
paths:
  /collection/{collectionId}/project/{projectId}/source/{sourceId}:
    delete:
      summary: Delete Source From Project
      description: Removes a source from a project.
      operationId: SourceService_RemoveSourceFromProject
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21RemoveSourceFromProjectResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: the id of the parent Collection
        in: path
        required: true
        schema:
          type: string
      - name: projectId
        description: the id of the Project
        in: path
        required: true
        schema:
          type: string
      - name: sourceId
        description: the id of the Source
        in: path
        required: true
        schema:
          type: string
      - name: force
        description: delete a live source even if it is in use in a broadcast.
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
      tags:
      - SourceService
    put:
      summary: Add Source to Project
      description: Add a source to a project
      operationId: SourceService_AddSourceToProject
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21AddSourceToProjectResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: collection which owns the project
        in: path
        required: true
        schema:
          type: string
      - name: projectId
        description: project which will own the source
        in: path
        required: true
        schema:
          type: string
      - name: sourceId
        description: live source id
        in: path
        required: true
        schema:
          type: string
      tags:
      - SourceService
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trigger:
                  $ref: '#/components/schemas/v21SourceTrigger'
                  title: allow this source to trigger a project broadcast
        required: true
    patch:
      summary: Update Source
      description: Update attributes of the Source.
      operationId: SourceService_UpdateSourceInProject
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21UpdateSourceInProjectResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: collection which owns the project
        in: path
        required: true
        schema:
          type: string
      - name: projectId
        description: project which will own the source
        in: path
        required: true
        schema:
          type: string
      - name: sourceId
        description: live source id
        in: path
        required: true
        schema:
          type: string
      tags:
      - SourceService
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                updateMask:
                  type: string
                  example: metadata
                  title: fields to update (default updates any non-null field)
                  required:
                  - update_mask
                trigger:
                  $ref: '#/components/schemas/v21SourceTrigger'
                  title: allow this source to trigger a project broadcast
              required:
              - updateMask
        required: true
  /collection/{collectionId}/source:
    get:
      summary: Get Source
      description: Get existing sources in a collection
      operationId: SourceService_GetSources
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21GetSourcesResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: collection which owns the project which owns the source
        in: path
        required: true
        schema:
          type: string
      tags:
      - SourceService
    post:
      summary: Create Collection Live Source
      description: 'Create a new live source in a collection

        ### Permissions

        * scope: `SCOPE_VAPI_CREATE`'
      operationId: SourceService_CreateSource
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21CreateSourceResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: collection which will own this collection live source
        in: path
        required: true
        schema:
          type: string
      tags:
      - SourceService
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  example:
                    createdBy: Eddie Current
                  title: arbitrary metadata to associate with this collection live source
                address:
                  $ref: '#/components/schemas/v21SourceAddress'
                  title: type of collection live source
                preview:
                  $ref: '#/components/schemas/v21PreviewAddress'
                  title: enable real-time previews
        required: true
  /collection/{collectionId}/source/{sourceId}:
    get:
      summary: Get Source
      description: Get an existing source in a project
      operationId: SourceService_GetSource
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21GetSourceResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: collection which owns the project which owns the source
        in: path
        required: true
        schema:
          type: string
      - name: sourceId
        description: source id
        in: path
        required: true
        schema:
          type: string
      tags:
      - SourceService
    delete:
      summary: Delete Live Source
      description: Deletes a live source from a collection
      operationId: SourceService_DeleteSource
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21DeleteSourceResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: collection which owns the live source
        in: path
        required: true
        schema:
          type: string
      - name: sourceId
        description: live source id
        in: path
        required: true
        schema:
          type: string
      - name: force
        description: delete a live source even if it is in use in a broadcast.
        in: query
        required: false
        schema:
          type: boolean
          default: 'false'
      tags:
      - SourceService
    patch:
      summary: Update Source
      description: Update attributes of the Source.
      operationId: SourceService_UpdateSource
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v21UpdateSourceResponse'
        '401':
          description: The access token provided is not valid
          content:
            application/json:
              schema: {}
        '403':
          description: The access token provided does not have access to specified resource
          content:
            application/json:
              schema: {}
        '404':
          description: The specified resource was not found
          content:
            application/json:
              schema: {}
        '429':
          description: The specified service is busy; please use an exponential backoff on subsequent requests.
          content:
            application/json:
              schema: {}
        '500':
          description: The specified service is unavailable; please try again later
          content:
            application/json:
              schema: {}
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: collectionId
        description: collection which owns the project which owns the source
        in: path
        required: true
        schema:
          type: string
      - name: sourceId
        description: source id
        in: path
        required: true
        schema:
          type: string
      tags:
      - SourceService
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                updateMask:
                  type: string
                  example: metadata
                  title: fields to update (default updates any non-null field)
                  required:
                  - update_mask
                metadata:
                  type: object
                  example:
                    createdBy: Eddie Current
                  title: arbitrary metadata to associate with this source
                address:
                  $ref: '#/components/schemas/v21SourceAddress'
                  title: type of collection live source
                preview:
                  $ref: '#/components/schemas/v21PreviewAddress'
                  title: enable real-time previews
              required:
              - updateMask
        required: true
components:
  schemas:
    v21VideoCodecRateControlMode:
      type: string
      enum:
      - VIDEO_CODEC_RATE_CONTROL_MODE_CBR
      description: '- VIDEO_CODEC_RATE_CONTROL_MODE_CBR: constant bit rate encoding'
      title: video encoding rate control mode
    v21HlsLifecycleLive:
      type: object
      properties:
        playlistCount:
          type: integer
          format: int32
          example: 5
          default: '5'
          title: number of entries to advertise in playlist file
          minimum: 2
        fileCount:
          type: integer
          format: int32
          example: 10
          default: '10'
          title: number of files to keep on disk
          minimum: 4
      title: live hls lifecycle management
    v21AudioCodec:
      type: string
      enum:
      - AUDIO_CODEC_AAC
      title: audio encoding codec
    v21Project:
      type: object
      properties:
        collectionId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: collection which owns the project
        projectId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: project id
        metadata:
          type: object
          example:
            createdBy: Eddie Current
          title: arbitrary metadata associated with this project
        rendering:
          $ref: '#/components/schemas/v21Rendering'
          default: '{}'
          title: composition parameters
        encoding:
          $ref: '#/components/schemas/v21Encoding'
          default: '{}'
          title: encoding parameters
        sources:
          type: array
          items:
            $ref: '#/components/schemas/v21Source'
          title: collection live sources added to this project
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/v21Destination'
          title: destinations associated with this project
        composition:
          $ref: '#/components/schemas/v21Composition'
          default: '{}'
          title: composition/layout source of the broadcast
        maxDuration:
          type: integer
          format: int64
          example: 172800000
          default: '172800000'
          title: maximum duration (ms) of project broadcasts
          maximum: 604800000
        webrtc:
          $ref: '#/components/schemas/v21WebRtc'
          title: configuration for webrtc services (if requested)
        triggers:
          type: array
          items:
            $ref: '#/components/schemas/v21ProjectTrigger'
          title: external triggers to start and stop this broadcast
        location:
          $ref: '#/components/schemas/v21LatLong'
          title: optional optimal location to start broadcast
        guestCodes:
          type: array
          items:
            $ref: '#/components/schemas/v21GuestCode'
          title: guest codes associated with this project
          readOnly: true
      title: project which owns a broadcast, sources, and destinations
    v21GuestCode:
      type: object
      properties:
        collectionId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: collection which owns the project
        projectId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: project id
        code:
          type: string
          title: the short url code
        url:
          type: string
          title: the short url
        autoDelete:
          type: string
          format: date-time
          title: auto-delete after time
    v21UpdateSourceInProjectResponse:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/v21Project'
          title: updated project
    v21SourceTrigger:
      type: object
      properties:
        sourceId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: the id of the source
          required:
          - source_id
        start:
          $ref: '#/components/schemas/v21SourceTriggerAction'
          example: SOURCE_TRIGGER_ACTION_OR
          default: SOURCE_TRIGGER_ACTION_IGNORE
          title: source should trigger project(s) to start
        stop:
          $ref: '#/components/schemas/v21SourceTriggerAction'
          example: SOURCE_TRIGGER_ACTION_OR
          default: SOURCE_TRIGGER_ACTION_IGNORE
          title: source should trigger project(s) to stop
      title: triggers to indicate what actions to take on the project for a given Source
      required:
      - sourceId
    v21VideoCodec:
      type: string
      enum:
      - VIDEO_CODEC_H264
      title: video encoding codec
    v21SrtPushAddress:
      type: object
      properties:
        enabled:
          type: boolean
          example: true
          default: 'true'
          title: enable source srt push address
        streamId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: assigned srt streamid
          readOnly: true
        url:
          type: string
          example: srt://ingest.api.stream?streamid=7132b004-61e8-49c1-8dc8-4bb3269ce6f/7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: assigned srt destination url
          readOnly: true
        baseUrl:
          type: string
          example: srt://ingest.api.stream
          title: base_url without streamid
          readOnly: true
      title: srt push addressing
    v21AudioEncoding:
      type: object
      properties:
        codec:
          $ref: '#/components/schemas/v21AudioCodec'
          example: AUDIO_CODEC_AAC
          default: AUDIO_CODEC_AAC
          title: audio encoding codec
      title: encoding audio parameters
    v21VideoEncoding:
      type: object
      properties:
        codec:
          $ref: '#/components/schemas/v21VideoCodec'
          example: VIDEO_CODEC_H264
          default: VIDEO_CODEC_H264
          title: video encoding codec
        rateControl:
          $ref: '#/components/schemas/v21VideoCodecRateControl'
          default: '{}'
          title: video encoding rate control
        profile:
          $ref: '#/components/schemas/v21VideoCodecProfile'
          example: VIDEO_CODEC_PROFILE_HIGH
          default: VIDEO_CODEC_PROFILE_HIGH
          title: video encoding codec profile
      title: encoding video parameters
    v21AudioChannelLayout:
      type: string
      enum:
      - AUDIO_CHANNEL_LAYOUT_STEREO
      title: audio channel layout
    v21LatLong:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
      title: optimal location of broadcast (to optimize routing and delay)
    v21SceneComposition:
      type: object
      properties:
        rendererUrl:
          type: string
          example: https://rainmaker.gg/overlay/e67cfd6ad57560962fddcf63611d2834/1
          title: the url to pass to the studiosdk
        selectedLayoutId:
          type: string
          example: e67cfd6ad57560962fddcf63611d2835
          title: the active "scene" to render
        debug:
          type: boolean
          example: false
          default: 'false'
      title: compose scenes using the browser-based compositor
    v21S3StorageAddress:
      type: object
      properties:
        region:
          type: string
          example: us-west-1
          title: cloud region
          required:
          - region
        bucket:
          type: string
          example: company
          title: cloud bucket
          required:
          - bucket
        prefix:
          type: string
          example: app
          title: cloud bucket prefix
        accessKey:
          type: string
          title: cloud access key
          required:
          - access_key
        secretKey:
          type: string
          title: cloud secret key
          required:
          - secret_key
        token:
          type: string
          title: token based auth
        tokenDuration:
          type: integer
          format: int32
          title: token duration in ms
        acl:
          $ref: '#/components/schemas/v21S3ACL'
          example: S3ACL_PUBLIC_READ
          title: access control list
        endpoint:
          type: string
          example: fra1.digitaloceanspaces.com
          title: endpoint for non aws s3 destinations
        packaging:
          $ref: '#/components/schemas/v21ObjectStoragePackaging'
          default: '{}'
          title: the format of the files to be written
      required:
      - region
      - bucket
      - accessKey
      - secretKey
    v21ExternalComposition:
      type: object
      properties:
        url:
          type: string
          example: https://rainmaker.gg/overlay/e67cfd6ad57560962fddcf63611d2834/1
          required:
          - url
      title: compose using an external renderer
      required:
      - url
    v21Source:
      type: object
      properties:
        collectionId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: collection which owns the source
        sourceId:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: collection source id
        metadata:
          type: object
          example:
            createdBy: Eddie Current
          title: arbitrary metadata associated with this collection source
        preview:
          $ref: '#/components/schemas/v21PreviewAddress'
          title: preview addresses
        address:
          $ref: '#/components/schemas/v21SourceAddress'
          title: source address
      title: collection live source
    v21ObjectStoragePackaging:
      type: object
      properties:
        hls:
          $ref: '#/components/schemas/v21HlsPackaging'
          default: '{}'
          title: hls format
      title: packaging options for object storage
    v21Composition:
      type: object
      properties:
        external:
          $ref: '#/components/schemas/v21ExternalComposition'
          title: compose using an external renderer
        studioSdk:
          $ref: '#/components/schemas/v21StudioSdkComposition'
          title: compose using the studiosdk renderer
        scene:
          $ref: '#/components/schemas/v21SceneComposition'
          default: '{}'
          title: compose scenes using the browser-based compositor
      title: composition source for project (select one)
    v21WebRtc:
      type: object
      properties:
        hosted:
          $ref: '#/components/schemas/v21HostedWebRtc'
          title: hosted webrtc configuration
      title: webrtc service (select one)
    v21HlsLifecycle:
      type: object
      properties:
        vod:
          $ref: '#/components/schemas/v21HlsLifecycleVod'
          default: '{}'
          title: lifecycle of vod
        live:
          $ref: '#/components/schemas/v21HlsLifecycleLive'
          title: lifecycle of live
      title: hls lifecycle management
    v21SourceAddress:
      type: object
      properties:
        rtmpPush:
          $ref: '#/components/schemas/v21SourceRtmpPushAddress'
          title: rtmp push addressing
        srtPush:
          $ref: '#/components/schemas/v21SrtPushAddress'
          title: the srt address to publish to
        rtmpPull:
          $ref: '#/components/schemas/v21RtmpPullAddress'
          title: the rtmp address to pull from
      title: live source address (select one)
    v21Encoding:
      type: object
      properties:
        video:
          $ref: '#/components/schemas/v21VideoEncoding'
          default: '{}'
          title: the video parameters of the encoding
        audio:
          $ref: '#/components/schemas/v21AudioEncoding'
          default: '{}'
          title: the audio parameters of the encoding
      title: the parameters of the encoding
    v21PreviewAddress:
      type: object
      properties:
        webrtc:
          $ref: '#/components/schemas/v21PreviewWebRtcAddress'
          title: 'hls preview address

            optional PreviewHlsPullAddress hls = 1;

            webrtc preview address'
      title: addresses of source previews
    v21AudioRendering:
      type: object
      properties:
        channelLayout:
          $ref: '#/components/schemas/v21AudioChannelLayout'
          example: AUDIO_CHANNEL_LAYOUT_STEREO
          default: AUDIO_CHANNEL_LAYOUT_STEREO
          title: audio channel layout
      title: composition audio parameters
    v21HostedWebRtc:
      type: object
      properties:
        enabled:
          type: boolean
          example: true
          default: 'true'
          title: enable webrtc services
      title: hosted webrtc configuration
    v21HlsPackaging:
      type: object
      properties:
        lifecycle:
          $ref: '#/components/schemas/v21HlsLifecycle'
          default: '{}'
          title: lifecycle of hls segments
        segmentDuration:
          type: integer
          format: int32
          example: 2000
          default: '2000'
          title: duration of segments in ms
          maximum: 18000
          minimum: 2000
      title: hls packaging options
    v21DestinationRtmpPushAddress:
      type: object
      properties:
        key:
          type: string
          example: 7132b004-61e8-49c1-8dc8-4bb3269ce6f
          title: rtmp stream key
        url:
          type: string
          example: rtmp://ingest.fakecompany.com
          title: rtmp destination url
          required:
          - url
      title: rtmp push destination address
      required:
      - url
    v21GetSourceResponse:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/v21Source'
    v21AddSourceToProjectResponse:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/v21Project'
          title: updated project
        broadcastUpdated:
          type: boolean
          example: true
          title: indicates whether the broadcast was updated as a function of this request
    v21HlsLifecycleVod:
      type: object
      properties:
        maxDuration:
          type: integer
          format: int32
          example: 0
          default: '0'
          title: max duration of the recording in ms (0 is indefinite)
      title: vod hls lifecycle management
    v21Rendering:
      type: object
      properties:
        video:
          $ref: '#/components/schemas/v21VideoRendering'
          default: '{}'
          title: composition video parameters
        audio:
          $ref: '#/components/schemas/v21AudioRendering'
          default: '{}'
          title: composition audio parameters
        quality:
          $ref: '#/components

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