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.

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

Stop instances with this configuration running or queued

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:

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

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"}
}

Response contains updated overrides.

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