Streamrun REST API

The Streamrun REST API lets you control your configurations and server instances via HTTP requests. You can query configurations, launch instances, and more. The API is currently in early beta, and we welcome all feedback at team@streamrun.com.

All REST API resources use the following base URL:

https://streamrun.com

All requests are served over HTTPS; unencrypted HTTP is not supported.

Authentication

The Streamrun API uses Bearer Authentication. You can create account-specific API keys on the API Keys page.

Authorization: Bearer <API_KEY>

For example, following command fetches a list of configurations using cURL:

curl -H "Authorization: Bearer <API_KEY>" https://streamrun.com/api/v1/configurations

Resources

Configurations

Create configurations using the Streamrun Editor, or copy a ready-made template or another user's public configuration to your account using web browser.

Please note that editing configurations or using the Streamrun editor is not recommended while using the API. The order in which changes are applied is not synchronous.

List configurations

GET /api/v1/configurations

Fetch single configuration

GET /api/v1/configurations/{configurationId}

Run configuration

POST /api/v1/configurations/{configurationId}/instances

The request may include an optional payload to override configuration settings or to start multiple instances. If there is no payload, one instance with default settings is launched. When launching multiple instances, numberOfInstances must match the length of the instanceSettings array. Each instance should have its own name and element-specific setting overrides, like output destinations and HTML overlay URL.

{
    "numberOfInstances": 1,
    "instanceSettings": [
        {
            "name": "Instance name to help indetify it",
            "overrides": {
                "htmloverlay-1": {"url": "https://streamrun.com"},
                "outputstream-1": {"destinations": ["destination-id"]}
            }
        }
    ]
}

Response includes a Location header pointing to the created instance request. Use that URL to monitor when the instance is started up and running.

Location: /api/v1/instance-requests/{requestId}

List instances

GET /api/v1/configurations/{configurationId}/instances

Set all output destinations live or offline for instances running this configuration

PUT /api/v1/configurations/{configurationId}/instances

Payload must include information weather outputs should be set live or offline.

{
    "outputs": "LIVE" | "OFFLINE
}

Stop all instances running, or queued to start, with provided configuration id.

DELETE /api/v1/configurations/{configurationId}/instances

Instance requests

When you start instances with the POST /api/v1/configurations/{configurationId}/instances API call, an intance request is created. Requests are first in the QUEUED state and they are switches to RUNNING once a server has been allocated.

List instance requests by request ID

GET /api/v1/instance-requests/{requestId}

Instances

Instances, i.e. servers where configurations run. Each instance can be in one of three states:

• QUEUED: Request to start the conf is made and it's waiting for an available server
• RUNNING: Configuration is running in production mode. You can go live with output destinations
• PREVIEW: Configuration is open in Streamrun editor

List instances

GET /api/v1/instances

Stop all instance

DELETE /api/v1/instances

Fetch single instance

GET /api/v1/instances/{instanceId}

Stop specific instance

DELETE /api/v1/instances/{instanceId}

Restart specific instance

POST /api/v1/instances/{instanceId}/restart

Get instance's setting overrides

GET /api/v1/instances/{instanceId}/overrides

Change instance's setting overrides

PATCH /api/v1/instances/{instanceId}/overrides

The payload includes element-specific setting overrides. For example, HTML overlay's URL.

{
    "htmloverlay-1": {"url": "https://streamrun.com", "visible": true},
    "switch-1": {"activeInput": 2}
}

Response contains updated overrides.

List all outputs for a running instance. Returns output stream elements with their current state.

GET /instances/{id}/outputs

Response 200:

{
  "outputs": [
    {
      "id": "outputstream-1",
      "type": "outputstream",
      "health": "OK",
      "state": {
        "destinations": [
          { "id": "dest-1", "status": "LIVE" }
        ]
      }
    }
  ]
}

Update the state of ALL outputs for an instance. Sets all output destinations to LIVE or OFFLINE.

PATCH /instances/{id}/outputs

Request Body:

{
  "desiredState": "LIVE" | "OFFLINE"
}

Update the state of a SPECIFIC output element. Sets all destinations for the specified output to LIVE or OFFLINE.

PATCH /instances/{id}/outputs/{outputId}

Request Body:

{
  "desiredState": "LIVE" | "OFFLINE"
}

Update the state of a SPECIFIC destination within a specific output element. Sets the individual destination to LIVE or OFFLINE.

PATCH /instances/{id}/outputs/{outputId}/destinations/{destinationId}

Request Body:

{
  "desiredState": "LIVE" | "OFFLINE"
}

Destinations

Destinations are platforms you stream to, such as Twitch, YouTube, or custom RTMP servers. Use destination IDs as an override setting when launching new instances to define the streaming destination at launch time.

List destinations

GET /api/v1/destinations