Livestreams

Manage live video streams on Unleash Live. The endpoints below let you start and stop streams, list what is currently broadcasting, mint short-lived viewer tokens, and group devices into shareable channels.

Base URL

https://api.unleashlive.com

Authentication

All endpoints require a Bearer token in the Authorization header. We recommend using a Personal Access Token (PAT). See the Authentication section for how to create one.

Authorization: Bearer <YOUR_PAT>

Channels

Channels group one or more devices so they can be watched together, optionally on a public watch page.

Create Channel

POST /v1/channels

Create a new channel scoped to the caller’s team. Channel names must be unique within the team and cannot exceed 100 characters.

Request Body

Field	Type	Description
`name`	String`!`	Channel name. Max 100 characters.

Example Request

{
  "name": "Site Alpha"
}

Example Response

{
  "id": "channelId1",
  "name": "Site Alpha",
  "teamId": "teamId1",
  "companyId": "companyId1",
  "deviceIds": ["deviceId1", "deviceId2"],
  "isPublic": false,
  "publicUrl": null,
  "createdAt": 1747526400000,
  "updatedAt": 1747526400000
}

List Channels

GET /v1/channels

Lists all channels for the caller’s team.

Example Response

[
  {
    "id": "channelId1",
    "name": "Site Alpha",
    "teamId": "teamId1",
    "companyId": "companyId1",
    "deviceIds": ["deviceId1"],
    "isPublic": true,
    "publicUrl": "8f5a2c1d-...",
    "createdAt": 1747526400000,
    "updatedAt": 1747612800000
  },
  {
    "id": "channelId2",
    "name": "Substation North",
    "teamId": "teamId1",
    "companyId": "companyId1",
    "deviceIds": [],
    "isPublic": false,
    "createdAt": 1747526400000,
    "updatedAt": 1747526400000
  }
]

Update Channel

PATCH /v1/channels/{id}

Update one or more mutable fields on a channel. Send only the fields you want to change.

Path Parameters

Parameter	Type	Description
`id`	String	Channel ID.

Request Body

Field	Type	Description
`name`	String	New channel name. Must be unique within the team.
`isPublic`	Boolean	Toggle public sharing. `true` generates a new `publicUrl`; `false` clears it.
`deviceIds`	String[]	Replaces the channel’s device list. Every device must belong to the caller’s team.

Example Request

{
  "isPublic": true,
  "deviceIds": ["deviceId1", "deviceId2"]
}

Add Device to Channel

POST /v1/channels/{id}/devices/{deviceId}

Add a device to a channel. The device must belong to the caller’s team.

Path Parameters

Parameter	Type	Description
`id`	String	Channel ID.
`deviceId`	String	Device ID.

Remove Device from Channel

DELETE /v1/channels/{id}/devices/{deviceId}

Remove a device from a channel. No-op if the device is not in the channel.

Path Parameters

Parameter	Type	Description
`id`	String	Channel ID.
`deviceId`	String	Device ID.

Delete Channel

DELETE /v1/channels/{id}

Delete a channel.

Path Parameters

Parameter	Type	Description
`id`	String	Channel ID.

Streams

These endpoints manage the lifecycle of a live stream: start, stop, and check status.

There are two parallel APIs:

Restream API (/v1/streams/from/*, /v1/streams/to/*): the caller supplies the sourceUrl (or destUrl) along with the device and stream key. Best for one-off flows or testing.
Device-scoped API (/v1/streams/api/*): sourceUrl and streamKey are looked up from the device record, so the request payload only carries IDs. Recommended for production integrations.

Stream States

Value	Description
`STARTING`	Start request accepted; provisioning is underway.
`STREAMING`	Stream is live and status is being logged.
`STOPPING`	Stop request accepted; the stream is winding down.
`STOPPED`	Stopped by a user request.
`FINISHED`	Stream ended on its own (source disconnected, etc.).
`ERROR`	An unrecoverable error was reported.

Start Restream from Source

POST /v1/streams/from/start

Pull a remote RTMP or RTSP feed and ingest it as a stream on Unleash Live.

Request Body

Field	Type	Description
`deviceId`	String`!`	Device to associate the stream with.
`streamKey`	String`!`	Stream key for the team.
`sourceUrl`	String`!`	RTMP or RTSP URL to pull from.

Example Request

{
  "deviceId": "deviceId1",
  "streamKey": "teamId1",
  "sourceUrl": "rtsp://camera.example.com/live"
}

Example Response

"STARTING"

Stop Restream from Source

POST /v1/streams/from/stop

Stop a stream that was started with Start Restream from Source.

Request Body

Field	Type	Description
`deviceId`	String`!`	Device ID.
`streamKey`	String`!`	Stream key.

Start Restream to Destination

POST /v1/streams/to/start

Relay an existing Unleash Live RTMP stream to an external RTMP destination (for example, a YouTube Live or social media ingest).

Request Body

Field	Type	Description
`deviceId`	String`!`	Device whose stream to relay.
`streamKey`	String`!`	Stream key.
`destUrl`	String`!`	RTMP URL to push to.

Stop Restream to Destination

POST /v1/streams/to/stop

Stop an outbound restream started with Start Restream to Destination.

Request Body

Field	Type	Description
`deviceId`	String`!`	Device ID.
`streamKey`	String`!`	Stream key.

Start Stream (device-scoped)

POST /v1/streams/api/{deviceId}/start

Start ingesting the source URL pre-configured on the given device. No request body is needed; the source URL and stream key are resolved from the device record.

Path Parameters

Parameter	Type	Description
`deviceId`	String	Device ID.

Example Response

{
  "streamId": "deviceId1-FROM"
}

Error Responses

Status	Meaning
`400`	Stream is already running for this device.
`403`	Device does not belong to the caller’s team.
`412`	Device has no `sourceUrl` configured.

Stop Stream by ID

POST /v1/streams/api/stop

Stop a running stream by its streamId.

Request Body

Field	Type	Description
`streamId`	String`!`	Stream identifier returned when starting it.

Example Request

{
  "streamId": "deviceId1-FROM"
}

Get Stream State

POST /v1/streams/api/status

Check the current state of a stream. Useful for confirming that a stop request has completed.

Request Body

Field	Type	Description
`streamId`	String`!`	Stream identifier.

Example Response

{
  "state": "STREAMING"
}

Get Active Stream ID for Device

GET /v1/streams/api/{deviceId}/streamid

Return the streamId of the currently active stream for a device.

Path Parameters

Parameter	Type	Description
`deviceId`	String	Device ID.

Example Response

{
  "streamId": "deviceId1-FROM"
}

If the device is not currently streaming the endpoint returns HTTP 400.

List Running Streams

GET /v1/streams/{streamKey}

List streams currently in the STREAMING state for the caller’s team. The active team is resolved from the auth token; {streamKey} is a legacy path segment kept for routing, so pass any non-empty string.

Example Response

[
  {
    "deviceId": "deviceId1",
    "player": "default",
    "modelId": null,
    "type": "RAW",
    "state": "STREAMING",
    "total_size": 14582344,
    "bitrate": 2400,
    "fps": 30
  }
]

External Stream Token

Mint a JWT that grants temporary access to a device’s HLS or DASH stream through the external streaming CDN. Use this when you need to share a live feed with a third-party viewer (an embed, a TV monitor, an integration) without exposing platform credentials.

Provide either deviceId (single-device token) or teamId (team-wide token).

Generate External Stream Token

POST /v1/streams/external/token

Request Body

Field	Type	Description
`deviceId`	String	Required if `teamId` is not provided.
`teamId`	String	Required if `deviceId` is not provided.
`aiAppIds`	String[]	Optional. AI add-on IDs to also include annotated stream URLs for.
`duration`	Integer	Token lifetime in seconds. Minimum `60`, maximum `43200` (12 hours). Defaults to `3600` (1 hour).

Example Request

{
  "deviceId": "device-abc123",
  "duration": 3600
}

Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "scope": "device",
  "deviceId": "device-abc123",
  "teamId": "teamId1",
  "expiresIn": 3600,
  "expiresAt": 1747612800,
  "streamUrls": {
    "hls": "https://stream-ext.unleashlive.com/.../index.m3u8?token=...",
    "dash": "https://stream-ext.unleashlive.com/.../index.mpd?token=..."
  }
}

Response Fields

Field	Type	Description
`token`	String	Signed JWT to include in requests to the external streaming CDN.
`scope`	String	`device` or `team`. Matches what was requested.
`deviceId`	String	Echoed when `scope` is `device`.
`teamId`	String	Team the token is bound to.
`expiresIn`	Integer	Token lifetime in seconds.
`expiresAt`	Integer	Unix timestamp (seconds) at which the token expires.
`streamUrls.hls` / `dash`	String	Signed playback URLs. Present when `scope` is `device`.
`streamUrlPattern`	Object	Templated URL pattern with a `note` field. Present when `scope` is `team`.
`annotatedStreamUrls`	Array	Per-`aiAppId` signed HLS URLs. Present when `aiAppIds` were supplied.
`annotatedStreamUrlPatterns`	Array	Per-`aiAppId` URL patterns. Present when `scope` is `team` and `aiAppIds` were supplied.