Skip to main content
Documentation Powered by Redocly

API.stream Live API (2.1)

The Live API enables developers to build video-enabled applications.

Authentication

AccessToken

Assert your access token into a HTTP Header named 'Authorization: Bearer'

curl -H 'Authorization: Bearer bar' https://live.api.stream/live/v2/collection/foo

Security Scheme Type API Key
Header parameter name: Authorization: Bearer

ApiKey

Assert your api key into a HTTP Header named 'X-API-Key'

curl -H 'X-API-Key:bar' https://live.api.stream/live/v2/collection/foo

Security Scheme Type API Key
Header parameter name: X-API-Key

CollectionService

The Collection Service operates on collections, which contain projects and collection live sources used in projects.

Get Collections

Get all collections owned by the user

Authorizations:
AccessToken

    Responses

    Response samples

    Content type
    application/json
    {
    • "collections": [
      ]
    }

    Create Collection

    Create a new collection of related projects and collection live sources

    Authorizations:
    AccessToken
      Request Body schema: application/json
      metadata
      object (arbitrary metadata to associate with this collection)

      Responses

      Request samples

      Content type
      application/json
      {
      • "metadata": {
        }
      }

      Response samples

      Content type
      application/json
      {
      • "collection": {
        }
      }

      Get Collection

      Get an existing collection of related projects and collection live sources

      Authorizations:
      AccessToken
        path Parameters
        collectionId
        required
        string

        collection id

        query Parameters
        populateProjects
        boolean
        Default: "true"

        optionally populate projects.

        populateSources
        boolean
        Default: "true"

        optionally populate sources.

        Responses

        Response samples

        Content type
        application/json
        {
        • "collection": {
          }
        }

        Delete Collection

        Delete a collection of related projects and collection live sources

        Authorizations:
        AccessToken
          path Parameters
          collectionId
          required
          string

          collection id

          query Parameters
          force
          boolean
          Default: "false"

          forcibly end all child project broadcasts in progress.

          Responses

          Response samples

          Content type
          application/json
          {
          • "sourcesDeleted": 1,
          • "projectsDeleted": 1,
          • "projectIdsStopped": [
            ]
          }

          Update Collection

          Update select collection document data

          Authorizations:
          AccessToken
            path Parameters
            collectionId
            required
            string

            collection id

            Request Body schema: application/json
            updateMask
            required
            string (fields to update)
            metadata
            object (arbitrary metadata to associate with this collection)

            Responses

            Request samples

            Content type
            application/json
            {
            • "updateMask": "metadata",
            • "metadata": {
              }
            }

            Response samples

            Content type
            application/json
            {
            • "collection": {
              }
            }

            ProjectService

            The Project Service operates on a Project.

            Create Project

            Create a new project

            Authorizations:
            AccessToken
              path Parameters
              collectionId
              required
              string

              collection which will own this project

              Request Body schema: application/json
              metadata
              object (arbitrary metadata to associate with this project)
              object (composition parameters)
              object (the parameters of the encoding)
              object (composition source for project (select one))
              maxDuration
              integer <int64> (maximum duration of project broadcasts (ms)) <= 604800000
              Default: "172800000"
              object (webrtc service (select one))
              object (optimal location of broadcast (to optimize routing and delay))

              Responses

              Request samples

              Content type
              application/json
              {
              • "metadata": {
                },
              • "rendering": {
                },
              • "encoding": {
                },
              • "composition": {},
              • "maxDuration": 172800000,
              • "webrtc": {
                },
              • "location": {
                }
              }

              Response samples

              Content type
              application/json
              {
              • "project": {
                }
              }

              Get Project

              Get an existing project

              Authorizations:
              AccessToken
                path Parameters
                collectionId
                required
                string

                collection which owns the project

                projectId
                required
                string

                project id

                query Parameters
                status
                boolean
                Default: "false"

                also query project broadcast status.

                Responses

                Response samples

                Content type
                application/json
                {
                • "project": {
                  },
                • "status": {
                  }
                }

                Delete Project

                Delete a project

                Authorizations:
                AccessToken
                  path Parameters
                  collectionId
                  required
                  string

                  collection which owns the project

                  projectId
                  required
                  string

                  project id

                  query Parameters
                  force
                  boolean
                  Default: "false"

                  forcibly end broadcast in progress.

                  Responses

                  Response samples

                  Content type
                  application/json
                  {
                  • "broadcastStopped": true,
                  • "layoutsDeleted": 0
                  }

                  Update Project

                  Updates a project

                  Authorizations:
                  AccessToken
                    path Parameters
                    collectionId
                    required
                    string

                    collection which owns the project

                    projectId
                    required
                    string

                    project id

                    Request Body schema: application/json
                    updateMask
                    required
                    string (fields to update)
                    metadata
                    object (arbitrary metadata to associate with this project)
                    object (composition parameters)
                    object (the parameters of the encoding)
                    object (composition source for project (select one))
                    maxDuration
                    integer <int64> (maximum duration of project broadcasts (ms)) <= 604800000
                    object (webrtc service (select one))
                    object (optimal location of broadcast (to optimize routing and delay))

                    Responses

                    Request samples

                    Content type
                    application/json
                    {
                    • "updateMask": "metadata, maxDuration, rendering.video.frameRate",
                    • "metadata": {
                      },
                    • "rendering": {
                      },
                    • "encoding": {
                      },
                    • "composition": {},
                    • "maxDuration": 172800000,
                    • "webrtc": {
                      },
                    • "location": {
                      }
                    }

                    Response samples

                    Content type
                    application/json
                    {
                    • "project": {
                      },
                    • "broadcastUpdated": true
                    }

                    Get Snapshot

                    Get a snapshot of the current output frame of the broadcast

                    Authorizations:
                    AccessToken
                      path Parameters
                      collectionId
                      required
                      string

                      collection which owns the project

                      projectId
                      required
                      string

                      project id

                      query Parameters
                      format
                      string
                      Value: "IMAGE_FORMAT_JPEG"

                      snapshot binary format.

                      Responses

                      Start Broadcast

                      Start broadcasting a project

                      Authorizations:
                      AccessToken
                        path Parameters
                        collectionId
                        required
                        string

                        collection which owns the project

                        projectId
                        required
                        string

                        project id

                        query Parameters
                        webrtcStart
                        boolean
                        Default: "false"

                        also start webrtc room.

                        Responses

                        Response samples

                        Content type
                        application/json
                        {
                        • "broadcastId": "7132b004-61e8-49c1-8dc8-4bb3269ce6f"
                        }

                        Get Broadcast Status

                        Get the broadcast status of the project

                        Authorizations:
                        AccessToken
                          path Parameters
                          collectionId
                          required
                          string

                          collection which owns the project

                          projectId
                          required
                          string

                          project id

                          Responses

                          Response samples

                          Content type
                          application/json
                          {
                          • "status": {
                            }
                          }

                          Stop Broadcast

                          Stop broadcasting a project

                          Authorizations:
                          AccessToken
                            path Parameters
                            collectionId
                            required
                            string

                            collection which owns the project

                            projectId
                            required
                            string

                            project id

                            query Parameters
                            webrtcStop
                            boolean
                            Default: "false"

                            stop the associated webrtc room,.

                            Responses

                            Response samples

                            Content type
                            application/json
                            { }

                            Start WebRTC

                            Start WebRTC services

                            Authorizations:
                            AccessToken
                              path Parameters
                              collectionId
                              required
                              string

                              collection which owns the project

                              projectId
                              required
                              string

                              project id

                              Responses

                              Response samples

                              Content type
                              application/json
                              { }

                              Stop WebRTC

                              Stop WebRTC services

                              Authorizations:
                              AccessToken
                                path Parameters
                                collectionId
                                required
                                string

                                collection which owns the project

                                projectId
                                required
                                string

                                project id

                                Responses

                                Response samples

                                Content type
                                application/json
                                { }

                                SourceService

                                The Source Service operates on Collection Live Sources and Project Sources.

                                Delete Source From Project

                                Removes a source from a project.

                                Authorizations:
                                AccessToken
                                  path Parameters
                                  collectionId
                                  required
                                  string

                                  the id of the parent Collection

                                  projectId
                                  required
                                  string

                                  the id of the Project

                                  sourceId
                                  required
                                  string

                                  the id of the Source

                                  query Parameters
                                  force
                                  boolean
                                  Default: "false"

                                  delete a live source even if it is in use in a broadcast.

                                  Responses

                                  Response samples

                                  Content type
                                  application/json
                                  {
                                  • "project": {
                                    },
                                  • "broadcastUpdated": true
                                  }

                                  Add Source to Project

                                  Add a source to a project

                                  Authorizations:
                                  AccessToken
                                    path Parameters
                                    collectionId
                                    required
                                    string

                                    collection which owns the project

                                    projectId
                                    required
                                    string

                                    project which will own the source

                                    sourceId
                                    required
                                    string

                                    live source id

                                    Request Body schema: application/json
                                    object (triggers to indicate what actions to take on the project for a given Source)
                                    sourceId
                                    required
                                    string (the id of the source)
                                    start
                                    string (boolean logic for trigger)
                                    Enum: "SOURCE_TRIGGER_ACTION_IGNORE" "SOURCE_TRIGGER_ACTION_OR"
                                    • SOURCE_TRIGGER_ACTION_OR: SOURCE_TRIGGER_ACTION_AND = 2;
                                    stop
                                    string (boolean logic for trigger)
                                    Enum: "SOURCE_TRIGGER_ACTION_IGNORE" "SOURCE_TRIGGER_ACTION_OR"
                                    • SOURCE_TRIGGER_ACTION_OR: SOURCE_TRIGGER_ACTION_AND = 2;

                                    Responses

                                    Request samples

                                    Content type
                                    application/json
                                    {
                                    • "trigger": {
                                      }
                                    }

                                    Response samples

                                    Content type
                                    application/json
                                    {
                                    • "project": {
                                      },
                                    • "broadcastUpdated": true
                                    }

                                    Update Source

                                    Update attributes of the Source.

                                    Authorizations:
                                    AccessToken
                                      path Parameters
                                      collectionId
                                      required
                                      string

                                      collection which owns the project

                                      projectId
                                      required
                                      string

                                      project which will own the source

                                      sourceId
                                      required
                                      string

                                      live source id

                                      Request Body schema: application/json
                                      updateMask
                                      required
                                      string (fields to update (default updates any non-null field))
                                      object (triggers to indicate what actions to take on the project for a given Source)

                                      Responses

                                      Request samples

                                      Content type
                                      application/json
                                      {
                                      • "updateMask": "metadata",
                                      • "trigger": {
                                        }
                                      }

                                      Response samples

                                      Content type
                                      application/json
                                      {
                                      • "project": {
                                        }
                                      }

                                      Get Source

                                      Get existing sources in a collection

                                      Authorizations:
                                      AccessToken
                                        path Parameters
                                        collectionId
                                        required
                                        string

                                        collection which owns the project which owns the source

                                        Responses

                                        Response samples

                                        Content type
                                        application/json
                                        {
                                        • "sources": [
                                          ]
                                        }

                                        Create Collection Live Source

                                        Create a new live source in a collection

                                        Permissions

                                        • scope: SCOPE_VAPI_CREATE
                                        Authorizations:
                                        AccessToken
                                          path Parameters
                                          collectionId
                                          required
                                          string

                                          collection which will own this collection live source

                                          Request Body schema: application/json
                                          metadata
                                          object (arbitrary metadata to associate with this collection live source)
                                          object (live source address (select one))
                                          object (addresses of source previews)

                                          Responses

                                          Request samples

                                          Content type
                                          application/json
                                          {
                                          • "metadata": {
                                            },
                                          • "address": {
                                            },
                                          • "preview": {
                                            }
                                          }

                                          Response samples

                                          Content type
                                          application/json
                                          {
                                          • "source": {
                                            }
                                          }

                                          Get Source

                                          Get an existing source in a project

                                          Authorizations:
                                          AccessToken
                                            path Parameters
                                            collectionId
                                            required
                                            string

                                            collection which owns the project which owns the source

                                            sourceId
                                            required
                                            string

                                            source id

                                            Responses

                                            Response samples

                                            Content type
                                            application/json
                                            {
                                            • "source": {
                                              }
                                            }

                                            Delete Live Source

                                            Deletes a live source from a collection

                                            Authorizations:
                                            AccessToken
                                              path Parameters
                                              collectionId
                                              required
                                              string

                                              collection which owns the live source

                                              sourceId
                                              required
                                              string

                                              live source id

                                              query Parameters
                                              force
                                              boolean
                                              Default: "false"

                                              delete a live source even if it is in use in a broadcast.

                                              Responses

                                              Response samples

                                              Content type
                                              application/json
                                              {
                                              • "projectIdsUpdated": [
                                                ]
                                              }

                                              Update Source

                                              Update attributes of the Source.

                                              Authorizations:
                                              AccessToken
                                                path Parameters
                                                collectionId
                                                required
                                                string

                                                collection which owns the project which owns the source

                                                sourceId
                                                required
                                                string

                                                source id

                                                Request Body schema: application/json
                                                updateMask
                                                required
                                                string (fields to update (default updates any non-null field))
                                                metadata
                                                object (arbitrary metadata to associate with this source)
                                                object (live source address (select one))
                                                object (addresses of source previews)

                                                Responses

                                                Request samples

                                                Content type
                                                application/json
                                                {
                                                • "updateMask": "metadata",
                                                • "metadata": {
                                                  },
                                                • "address": {
                                                  },
                                                • "preview": {
                                                  }
                                                }

                                                Response samples

                                                Content type
                                                application/json
                                                {
                                                • "source": {
                                                  },
                                                • "broadcastUpdated": true
                                                }

                                                DestinationService

                                                The Destination Service operates on Project Destinations. Destinations designate where a Broadcast associated with a Project is distributed downstream.

                                                Create Destination

                                                Create a new Destination

                                                Authorizations:
                                                AccessToken
                                                  path Parameters
                                                  collectionId
                                                  required
                                                  string

                                                  collection which owns the project which owns the destination

                                                  projectId
                                                  required
                                                  string

                                                  project which will own this destination

                                                  Request Body schema: application/json
                                                  metadata
                                                  object (arbitrary metadata associated with this destination)
                                                  object (destination address (select one))
                                                  enabled
                                                  boolean (enable or disable this destination)
                                                  Default: "true"
                                                  timeout
                                                  integer <int64> (timeout (in milliseconds) to wait before resetting a connection) [ 100 .. 30000 ]
                                                  Default: "5000"

                                                  Responses

                                                  Request samples

                                                  Content type
                                                  application/json
                                                  {
                                                  • "metadata": {
                                                    },
                                                  • "address": {
                                                    },
                                                  • "enabled": true,
                                                  • "timeout": 5000
                                                  }

                                                  Response samples

                                                  Content type
                                                  application/json
                                                  {
                                                  • "destination": {
                                                    }
                                                  }

                                                  Get Destination

                                                  Get an existing Destination.

                                                  Authorizations:
                                                  AccessToken
                                                    path Parameters
                                                    collectionId
                                                    required
                                                    string

                                                    collection which owns the project which owns the destination

                                                    projectId
                                                    required
                                                    string

                                                    project which owns the destination

                                                    destinationId
                                                    required
                                                    string

                                                    destination id

                                                    Responses

                                                    Response samples

                                                    Content type
                                                    application/json
                                                    {
                                                    • "destination": {
                                                      }
                                                    }

                                                    Delete Destination

                                                    Delete a destination

                                                    Authorizations:
                                                    AccessToken
                                                      path Parameters
                                                      collectionId
                                                      required
                                                      string

                                                      collection which owns the project which owns the destination

                                                      projectId
                                                      required
                                                      string

                                                      project which owns the destination

                                                      destinationId
                                                      required
                                                      string

                                                      destination id

                                                      query Parameters
                                                      force
                                                      boolean
                                                      Default: "false"

                                                      forcibly remove destination if enabled.

                                                      Responses

                                                      Response samples

                                                      Content type
                                                      application/json
                                                      {
                                                      • "broadcastUpdated": true
                                                      }

                                                      Update Destination

                                                      Update a destination

                                                      Authorizations:
                                                      AccessToken
                                                        path Parameters
                                                        collectionId
                                                        required
                                                        string

                                                        collection which owns the project which owns the destination

                                                        projectId
                                                        required
                                                        string

                                                        project which owns the destination

                                                        destinationId
                                                        required
                                                        string

                                                        destination id

                                                        Request Body schema: application/json
                                                        updateMask
                                                        required
                                                        string (fields to update (default updates any non-null field))
                                                        metadata
                                                        object (arbitrary metadata associated with this destination)
                                                        object (destination address (select one))
                                                        enabled
                                                        boolean (enable or disable this destination)
                                                        Default: "true"
                                                        timeout
                                                        integer <int64> (timeout (in milliseconds) to wait before resetting a connection) [ 100 .. 30000 ]

                                                        Responses

                                                        Request samples

                                                        Content type
                                                        application/json
                                                        {
                                                        • "updateMask": "metadata, address.rtmpPush.url",
                                                        • "metadata": {
                                                          },
                                                        • "address": {
                                                          },
                                                        • "enabled": true,
                                                        • "timeout": 5000
                                                        }

                                                        Response samples

                                                        Content type
                                                        application/json
                                                        {
                                                        • "destination": {
                                                          },
                                                        • "broadcastUpdated": true
                                                        }

                                                        AuthenticationService

                                                        The Authentication Service provides token services for clients

                                                        Refresh Access Token

                                                        Forcibly refresh an access token prior to expiration

                                                        Authorizations:
                                                        AccessToken
                                                          Request Body schema: application/json
                                                          object (v21RefreshAccessTokenRequest)

                                                          Responses

                                                          Request samples

                                                          Content type
                                                          application/json
                                                          { }

                                                          Response samples

                                                          Content type
                                                          application/json
                                                          { }

                                                          Create Guest Access Token

                                                          Create an access token for a guest

                                                          Authorizations:
                                                          AccessToken
                                                            Request Body schema: application/json
                                                            collectionId
                                                            required
                                                            string (id of the collection this token is allowed to access)
                                                            projectId
                                                            required
                                                            string (id of the project this token is allowed to access)
                                                            maxDuration
                                                            integer <int64> (requested duration (ms) of token before it expires)
                                                            Default: "172800000"
                                                            role
                                                            string (defined roles)
                                                            Enum: "ROLE_HOST" "ROLE_COHOST" "ROLE_CONTRIBUTOR" "ROLE_GUEST" "ROLE_VIEWER" "ROLE_RENDERER" "ROLE_PLATFORM" "ROLE_IMPERSONATE"
                                                            object (the type of access token (selec one))
                                                            url
                                                            string (request a shortened url)

                                                            Responses

                                                            Request samples

                                                            Content type
                                                            application/json
                                                            {
                                                            • "collectionId": "7132b004-61e8-49c1-8dc8-4bb3269ce6f",
                                                            • "projectId": "7132b004-61e8-49c1-8dc8-4bb3269ce6f",
                                                            • "maxDuration": 172800000,
                                                            • "role": "ROLE_HOST",
                                                            • "token": {
                                                              },
                                                            • "url": "https://rainmaker.gg/overlay/e67cfd6ad57560962fddcf63611d2834/1"
                                                            }

                                                            Response samples

                                                            Content type
                                                            application/json
                                                            {
                                                            • "accessToken": "7132b004-61e8-49c1-8dc8-4bb3269ce6f",
                                                            • "url": "string"
                                                            }

                                                            BackendAuthenticationService

                                                            The Backend Authentication Service provides token services for partner backend systems

                                                            Create Access Token

                                                            Create an access token for a session host

                                                            Authorizations:
                                                            ApiKey
                                                              Request Body schema: application/json
                                                              serviceUserId
                                                              required
                                                              string (service-specific user id ### Usage * this should be an opaque GUID with no spaces)
                                                              displayName
                                                              string
                                                              role
                                                              string (defined roles)
                                                              Enum: "ROLE_HOST" "ROLE_COHOST" "ROLE_CONTRIBUTOR" "ROLE_GUEST" "ROLE_VIEWER" "ROLE_RENDERER" "ROLE_PLATFORM" "ROLE_IMPERSONATE"
                                                              maxDuration
                                                              integer <int64> (requested duration of token before it expires (ms))
                                                              Default: "172800000"

                                                              Responses

                                                              Request samples

                                                              Content type
                                                              application/json
                                                              {
                                                              • "serviceUserId": "7132b004-61e8-49c1-8dc8-4bb3269ce6f",
                                                              • "displayName": "string",
                                                              • "role": "ROLE_HOST",
                                                              • "maxDuration": 172800000
                                                              }

                                                              Response samples

                                                              Content type
                                                              application/json
                                                              {
                                                              • "accessToken": "7132b004-61e8-49c1-8dc8-4bb3269ce6f"
                                                              }

                                                              PublicAuthenticationService

                                                              The Public Authentication Service provides token verification services

                                                              Get Public Keys

                                                              Get public keys used to sign access tokens

                                                              Authorizations:
                                                              AccessToken

                                                                Responses

                                                                Response samples

                                                                Content type
                                                                application/json
                                                                {
                                                                • "keys": [
                                                                  ]
                                                                }

                                                                Exchange Guest Access Token

                                                                Exchange a guest access token with updated user identifiers

                                                                Authorizations:
                                                                AccessToken
                                                                  path Parameters
                                                                  serviceId
                                                                  required
                                                                  string

                                                                  the id of the service

                                                                  code
                                                                  required
                                                                  string

                                                                  the short url code

                                                                  Responses

                                                                  Response samples

                                                                  Content type
                                                                  application/json
                                                                  { }