API documentation

The Streamrun REST API lets you control configurations and server instances via HTTP. Query configurations, launch instances, manage destinations, and control running streams programmatically. The API is currently in beta. Feedback is welcome at team@streamrun.com.

Authentication

All requests use the base URL https://streamrun.com and must be made over HTTPS. The API uses Bearer authentication. Create API keys on the API Keys page.

Authorization: Bearer <API_KEY>

Example: list configurations with cURL

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

Configurations

Build configurations in the Streamrun Editor or copy a template to your account. Avoid launching instances via the API while the configuration is open in the editor — concurrent changes may be applied out of order.

GET/api/v1/configurations

List all configurations.

GET/api/v1/configurations/{configurationId}

Fetch a single configuration.

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

List all instances running this configuration.

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

Launch one or more instances of a configuration. Without a payload, one instance with default settings is started. The response includes a Location header pointing to the instance request.

{
    "numberOfInstances": 1,
    "instanceSettings": [
        {
            "name": "Instance name",
            "overrides": {
                "htmloverlay-1": {"url": "https://example.com"},
                "inputstream-1": {"pullUrl": "rtmp://customserver"},
                "outputstream-1": {"destinations": ["destination-id"]}
            }
        }
    ]
}

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

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

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

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

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

Stop all running or queued instances for this configuration.

Instance requests

When you launch instances, an instance request is created. It starts in the QUEUED state and transitions to RUNNING once a server has been allocated.

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

Fetch an instance request by ID to check its status.

Instances

Each instance is a server running a configuration. Possible states:

QUEUED

Waiting for an available server.

RUNNING

Live in production mode. Outputs can go live.

PREVIEW

Configuration is open in the Streamrun editor.

GET/api/v1/instances

List all instances.

GET/api/v1/instances/{instanceId}

Fetch a single instance.

DELETE/api/v1/instances

Stop all instances.

DELETE/api/v1/instances/{instanceId}

Stop a specific instance.

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

Restart a specific instance.

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

Get the current setting overrides for an instance.

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

Update setting overrides for a running instance. Changes apply immediately.

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

Outputs

Manage the live state of output stream elements and their individual destinations.

GET/api/v1/instances/{id}/outputs

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

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

PATCH/api/v1/instances/{id}/outputs

Set all output destinations for an instance to LIVE or OFFLINE.

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

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

Set all destinations for a specific output element to LIVE or OFFLINE.

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

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

Set a single destination within a specific output element to LIVE or OFFLINE.

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

Instance actions

Trigger runtime behavior on a specific element inside a running instance. Actions are asynchronous and return 202 Accepted on success.

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

{
    "elementId": "string",
    "action": "string",
    "params": {}
}

HTML Overlay

RELOAD_OVERLAY

Reload the web page shown as the overlay.

{ "elementId": "htmloverlay-1", "action": "RELOAD_OVERLAY" }

Input Stream

START_PULL

Start RTMP/SRT pull.

STOP_PULL

Stop RTMP/SRT pull.

Video Player

PLAY

Start or resume playback. If stopped, starts from the beginning. If paused, resumes from current position.

PAUSE

Pause playback at the current position. Playback position is preserved.

STOP

Stop playback and reset position to the beginning.

RESTART

Set position to the beginning without changing playback state.

Destinations

Destinations are the platforms you stream to (Twitch, YouTube, custom RTMP, etc.). Use destination IDs as override settings when launching instances to control where each instance streams. Changes to destinations are saved but not applied to already-running instances.

GET/api/v1/destinations

List all destinations.

POST/api/v1/destinations

Add a new destination.

{
    "platform": "twitch",
    "name": "My Twitch channel",
    "streamKey": "live_..."
}

Field	Type	Required	Description
platform	string	Yes	Platform identifier, e.g. "twitch", "youtube", "kick"
name	string	Yes	Display name to identify the destination, e.g. channel name.
streamKey	string	Yes	Stream key used to authenticate the stream. Stored encrypted.

PUT/api/v1/destinations/{destinationId}

Update an existing destination.

Field	Type	Required	Description
platform	string	Yes	Platform identifier.
name	string	Yes	Display name.
streamKey	string	No	Updated stream key. Omit to keep the existing key.

DELETE/api/v1/destinations/{destinationId}

Delete a destination.

API documentation

Authentication

Configurations

Instance requests

Instances

Outputs

Instance actions

HTML Overlay

Input Stream

Video Player

Destinations

Related

API Keys

Output Destinations

Streamrun Editor

Streamrun Pro