Managed Streams API · Dashboard
Channels & playback
Channels viewers watch, their playback URLs and embed code, playback keys, viewer tokens and app bindings.
Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.
Stream servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the stream server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the stream permissions must hold that exact permission.
How to use these endpoints
- Create a channel with a
source(an input, a mixer or a playlist), itsencoding(passthroughor aladder),playbackoutputs,latency, DVR and access. - Read the channel's playback route for HLS, WHEP, embed, thumbnail, status and audio URLs and ready-made embed HTML.
- For
tokenaccess, create a playback key. Its secret is returned once: keep it on your server and sign viewer tokens with@hubfly/streams/serveror the Gostreamspackage. - A binding writes
HUBFLY_STREAM_URLand, with a playback key,HUBFLY_STREAM_PLAYBACK_KEY_IDandHUBFLY_STREAM_PLAYBACK_KEY_SECRETinto a Cell project.
Create a low-latency channel from an input
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/stream/channels/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Main","source":{"type":"input","ref":"'"$INPUT_ID"'"},"latency":"low","dvrMinutes":60}'The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.
Endpoint reference
Dashboard endpoints (14)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
POSTConnect a stream server to an appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/bindings/create
Write the server's variables into a Cell project's environment: HUBFLY_STREAM_URL, then HUBFLY_STREAM_PLAYBACK_KEY_ID and HUBFLY_STREAM_PLAYBACK_KEY_SECRET for a playback key (default: the newest active key, if any), and with channelId also HUBFLY_STREAM_CHANNEL and HUBFLY_STREAM_HLS. There is one binding per server and project: connecting again replaces it and removes the variables it no longer writes.
- Requires
stream:adminhere andproject:editon the target project. clientPrefix(NEXT_PUBLIC_,VITE_orPUBLIC_) prefixes the channel and HLS variables for browser code; the key secret never gets a prefix. Any other prefix returns400 STREAM_INVALID_CLIENT_PREFIX.- Only Cell projects can be bound (
409 MANAGED_BINDING_TARGET_UNSUPPORTED); a playback key that is not active returns409 STREAM_PLAYBACK_KEY_NOT_ACTIVE. - Rotating or deleting the bound playback key rewrites these variables automatically.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
targetProjectId | string | Yes |
playbackKeyId | string | No |
channelId | string | No |
clientPrefix | | none | NEXT_PUBLIC_ | VITE_ | PUBLIC_ | No |
Complete request schema
{
"type": "object",
"properties": {
"targetProjectId": {
"type": "string"
},
"playbackKeyId": {
"type": "string"
},
"channelId": {
"type": "string"
},
"clientPrefix": {
"type": "string",
"enum": [
"",
"none",
"NEXT_PUBLIC_",
"VITE_",
"PUBLIC_"
]
}
},
"required": [
"targetProjectId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "instanceId": { "type": "string" }, "targetProjectId": { "type": "string" }, "targetProjectName": { "type": "string" }, "playbackKeyId": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "clientPrefix": { "type": "string", "enum": [ "none", "NEXT_PUBLIC_", "VITE_", "PUBLIC_" ] }, "envKeys": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "instanceId", "targetProjectId", "targetProjectName", "playbackKeyId", "channelId", "clientPrefix", "envKeys", "createdAt", "updatedAt" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "instanceId": "string", "targetProjectId": "string", "targetProjectName": "string", "playbackKeyId": "string", "channelId": "string", "clientPrefix": "none", "envKeys": [ "string" ], "createdAt": "string", "updatedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList app bindingsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/bindings
List the Cell projects this server is connected to, with the bound playback key and channel, the client prefix and the envKeys written into each project.
- Requires
stream:read.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "instanceId": { "type": "string" }, "targetProjectId": { "type": "string" }, "targetProjectName": { "type": "string" }, "playbackKeyId": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "clientPrefix": { "type": "string", "enum": [ "none", "NEXT_PUBLIC_", "VITE_", "PUBLIC_" ] }, "envKeys": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "instanceId", "targetProjectId", "targetProjectName", "playbackKeyId", "channelId", "clientPrefix", "envKeys", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "instanceId": "string", "targetProjectId": "string", "targetProjectName": "string", "playbackKeyId": "string", "channelId": "string", "clientPrefix": "none", "envKeys": [ "string" ], "createdAt": "string", "updatedAt": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDisconnect an appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/bindings/:bindingId/delete
Delete a binding. By default the variables it wrote are removed from the project too, where they still hold this server's values; pass removeVariables=false to keep them.
- Requires
stream:admin, andproject:editon the target project when variables are removed. - Returns
variablesRemoved, the number of variables deleted. Unknown binding:404 MANAGED_BINDING_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
bindingId | path | Yes | string | — |
removeVariables | query | No | boolean | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "const": true, "type": "boolean" }, "variablesRemoved": { "type": "number" } }, "required": [ "deleted", "variablesRemoved" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "deleted": true, "variablesRemoved": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a channelDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/create
Create a channel, what viewers watch: a source (an input, mixer or playlist), an optional backup with failover, encoding (passthrough or an ABR ladder of renditions and audio outputs), playback outputs, latency, dvrMinutes, access and recording. Defaults: passthrough, HLS with LL-HLS and WebRTC on, low latency, no DVR, public access and no recording.
- Requires
stream:admin. sourceis required: without it the request returns422 STREAM_INVALID(codeunknown_ref).latencyisstandard(HLS, 15–25 s behind live),low(LL-HLS, 3–5 s) orultra(the embed player prefers WebRTC, under 1 s).dvrMinutesis 0–360; clips need DVR.- With
access.mode: "token"every playback request needs a token signed with one of the server's playback keys. Recording needs a storage link withwriteorread_writeaccess. - A server holds up to 20 channels. Invalid configuration returns
422 STREAM_INVALIDwithdetails; a duplicate name returns409 STREAM_NAME_TAKEN.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
source | object | No |
access | object | No |
backup | object | No |
recording | object | No |
playback | object | No |
failover | object | No |
encoding | object | No |
latency | low | standard | ultra | No |
dvrMinutes | number | No |
maxViewers | number | No |
name | string | Yes |
enabled | boolean | No |
position | number | No |
Complete request schema
{
"type": "object",
"properties": {
"source": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"input",
"mixer",
"playlist"
]
},
"ref": {
"type": "string"
}
},
"required": [
"type",
"ref"
],
"additionalProperties": false
},
"access": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"token",
"public"
]
},
"allowedOrigins": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedCidrs": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"mode",
"allowedOrigins",
"allowedCidrs"
],
"additionalProperties": false
},
"backup": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"input",
"mixer",
"playlist"
]
},
"ref": {
"type": "string"
}
},
"required": [
"type",
"ref"
],
"additionalProperties": false,
"nullable": true
},
"recording": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"storageLink": {
"type": "string"
},
"prefix": {
"type": "string"
},
"splitMinutes": {
"type": "number"
},
"registerAsset": {
"type": "boolean"
}
},
"required": [
"enabled",
"storageLink",
"prefix",
"splitMinutes",
"registerAsset"
],
"additionalProperties": false
},
"playback": {
"type": "object",
"properties": {
"hls": {
"type": "boolean"
},
"llHls": {
"type": "boolean"
},
"webrtc": {
"type": "boolean"
},
"icecast": {
"type": "array",
"items": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"aac",
"mp3",
"opus"
]
},
"bitrateKbps": {
"type": "number"
}
},
"required": [
"format",
"bitrateKbps"
],
"additionalProperties": false
}
},
"rtmpPull": {
"type": "boolean"
},
"srtPull": {
"type": "boolean"
}
},
"required": [
"hls",
"llHls",
"webrtc",
"icecast",
"rtmpPull",
"srtPull"
],
"additionalProperties": false
},
"failover": {
"type": "object",
"properties": {
"afterMs": {
"type": "number"
},
"slate": {
"type": "string",
"nullable": true
},
"returnToPrimary": {
"type": "boolean"
}
},
"required": [
"afterMs",
"slate",
"returnToPrimary"
],
"additionalProperties": false
},
"encoding": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"passthrough",
"ladder"
]
},
"includeSource": {
"type": "boolean"
},
"renditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"codec": {
"const": "h264",
"type": "string"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"fps": {
"type": "number"
},
"videoBitrateKbps": {
"type": "number"
},
"audioBitrateKbps": {
"type": "number"
}
},
"required": [
"name",
"codec",
"width",
"height",
"fps",
"videoBitrateKbps",
"audioBitrateKbps"
],
"additionalProperties": false
}
},
"audioOutputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"codec": {
"type": "string",
"enum": [
"aac",
"mp3",
"opus"
]
},
"bitrateKbps": {
"type": "number"
}
},
"required": [
"name",
"codec",
"bitrateKbps"
],
"additionalProperties": false
}
}
},
"required": [
"mode",
"includeSource",
"renditions",
"audioOutputs"
],
"additionalProperties": false
},
"latency": {
"type": "string",
"enum": [
"low",
"standard",
"ultra"
]
},
"dvrMinutes": {
"type": "number"
},
"maxViewers": {
"type": "number"
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"position": {
"type": "number"
}
},
"required": [
"name"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false }, "access": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "token", "public" ] }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowedOrigins", "allowedCidrs" ], "additionalProperties": false }, "backup": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false, "nullable": true }, "recording": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "storageLink": { "type": "string" }, "prefix": { "type": "string" }, "splitMinutes": { "type": "number" }, "registerAsset": { "type": "boolean" } }, "required": [ "enabled", "storageLink", "prefix", "splitMinutes", "registerAsset" ], "additionalProperties": false }, "failover": { "type": "object", "properties": { "afterMs": { "type": "number" }, "slate": { "type": "string", "nullable": true }, "returnToPrimary": { "type": "boolean" } }, "required": [ "afterMs", "slate", "returnToPrimary" ], "additionalProperties": false }, "encoding": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "passthrough", "ladder" ] }, "includeSource": { "type": "boolean" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "const": "h264", "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "videoBitrateKbps": { "type": "number" }, "audioBitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "width", "height", "fps", "videoBitrateKbps", "audioBitrateKbps" ], "additionalProperties": false } }, "audioOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "bitrateKbps" ], "additionalProperties": false } } }, "required": [ "mode", "includeSource", "renditions", "audioOutputs" ], "additionalProperties": false }, "latency": { "type": "string", "enum": [ "low", "standard", "ultra" ] }, "dvrMinutes": { "type": "number" }, "maxViewers": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "revision": { "type": "number" }, "position": { "type": "number" }, "processingMbps": { "type": "number" }, "playback": { "type": "object", "properties": { "hls": { "type": "boolean" }, "llHls": { "type": "boolean" }, "webrtc": { "type": "boolean" }, "icecast": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "format", "bitrateKbps" ], "additionalProperties": false } }, "rtmpPull": { "type": "boolean" }, "srtPull": { "type": "boolean" }, "urls": { "type": "object", "properties": { "hls": { "type": "string" }, "whep": { "type": "string" }, "embed": { "type": "string" }, "thumb": { "type": "string" }, "status": { "type": "string" }, "audio": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "url": { "type": "string" } }, "required": [ "format", "url" ], "additionalProperties": false } }, "rtmpPull": { "type": "string" }, "srtPull": { "type": "string" } }, "required": [ "hls", "whep", "embed", "thumb", "status", "audio" ], "additionalProperties": false, "nullable": true } }, "required": [ "hls", "llHls", "webrtc", "icecast", "rtmpPull", "srtPull", "urls" ], "additionalProperties": false } }, "required": [ "id", "name", "enabled", "source", "access", "backup", "recording", "failover", "encoding", "latency", "dvrMinutes", "maxViewers", "createdAt", "updatedAt", "revision", "position", "processingMbps", "playback" ], "additionalProperties": false }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false } } }, "required": [ "status", "generation", "error", "warnings" ], "additionalProperties": false } }, "required": [ "channel", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "channel": { "id": "string", "name": "string", "enabled": true, "source": { "type": "input", "ref": "string" }, "access": { "mode": "token", "allowedOrigins": [ "string" ], "allowedCidrs": [ "string" ] }, "backup": { "type": "input", "ref": "string" }, "recording": { "enabled": true, "storageLink": "string", "prefix": "string", "splitMinutes": 0, "registerAsset": true }, "failover": { "afterMs": 0, "slate": "string", "returnToPrimary": true }, "encoding": { "mode": "passthrough", "includeSource": true, "renditions": [ { "name": "string", "codec": "string", "width": 0, "height": 0, "fps": 0, "videoBitrateKbps": 0, "audioBitrateKbps": 0 } ], "audioOutputs": [ { "name": "string", "codec": "aac", "bitrateKbps": 0 } ] }, "latency": "low", "dvrMinutes": 0, "maxViewers": 0, "createdAt": "string", "updatedAt": "string", "revision": 0, "position": 0, "processingMbps": 0, "playback": { "hls": true, "llHls": true, "webrtc": true, "icecast": [ { "format": "aac", "bitrateKbps": 0 } ], "rtmpPull": true, "srtPull": true, "urls": { "hls": "string", "whep": "string", "embed": "string", "thumb": "string", "status": "string", "audio": [ { "format": "aac", "url": "string" } ], "rtmpPull": "string", "srtPull": "string" } } }, "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList channelsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels
List the server's channels in position order, each with its source and backup, encoding, playback outputs and URLs, latency, DVR, access, recording settings and processingMbps, the processing its encoding needs.
- Requires
stream:read.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false }, "access": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "token", "public" ] }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowedOrigins", "allowedCidrs" ], "additionalProperties": false }, "backup": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false, "nullable": true }, "recording": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "storageLink": { "type": "string" }, "prefix": { "type": "string" }, "splitMinutes": { "type": "number" }, "registerAsset": { "type": "boolean" } }, "required": [ "enabled", "storageLink", "prefix", "splitMinutes", "registerAsset" ], "additionalProperties": false }, "failover": { "type": "object", "properties": { "afterMs": { "type": "number" }, "slate": { "type": "string", "nullable": true }, "returnToPrimary": { "type": "boolean" } }, "required": [ "afterMs", "slate", "returnToPrimary" ], "additionalProperties": false }, "encoding": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "passthrough", "ladder" ] }, "includeSource": { "type": "boolean" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "const": "h264", "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "videoBitrateKbps": { "type": "number" }, "audioBitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "width", "height", "fps", "videoBitrateKbps", "audioBitrateKbps" ], "additionalProperties": false } }, "audioOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "bitrateKbps" ], "additionalProperties": false } } }, "required": [ "mode", "includeSource", "renditions", "audioOutputs" ], "additionalProperties": false }, "latency": { "type": "string", "enum": [ "low", "standard", "ultra" ] }, "dvrMinutes": { "type": "number" }, "maxViewers": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "revision": { "type": "number" }, "position": { "type": "number" }, "processingMbps": { "type": "number" }, "playback": { "type": "object", "properties": { "hls": { "type": "boolean" }, "llHls": { "type": "boolean" }, "webrtc": { "type": "boolean" }, "icecast": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "format", "bitrateKbps" ], "additionalProperties": false } }, "rtmpPull": { "type": "boolean" }, "srtPull": { "type": "boolean" }, "urls": { "type": "object", "properties": { "hls": { "type": "string" }, "whep": { "type": "string" }, "embed": { "type": "string" }, "thumb": { "type": "string" }, "status": { "type": "string" }, "audio": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "url": { "type": "string" } }, "required": [ "format", "url" ], "additionalProperties": false } }, "rtmpPull": { "type": "string" }, "srtPull": { "type": "string" } }, "required": [ "hls", "whep", "embed", "thumb", "status", "audio" ], "additionalProperties": false, "nullable": true } }, "required": [ "hls", "llHls", "webrtc", "icecast", "rtmpPull", "srtPull", "urls" ], "additionalProperties": false } }, "required": [ "id", "name", "enabled", "source", "access", "backup", "recording", "failover", "encoding", "latency", "dvrMinutes", "maxViewers", "createdAt", "updatedAt", "revision", "position", "processingMbps", "playback" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": [ { "id": "string", "name": "string", "enabled": true, "source": { "type": "input", "ref": "string" }, "access": { "mode": "token", "allowedOrigins": [ "string" ], "allowedCidrs": [ "string" ] }, "backup": { "type": "input", "ref": "string" }, "recording": { "enabled": true, "storageLink": "string", "prefix": "string", "splitMinutes": 0, "registerAsset": true }, "failover": { "afterMs": 0, "slate": "string", "returnToPrimary": true }, "encoding": { "mode": "passthrough", "includeSource": true, "renditions": [ { "name": "string", "codec": "string", "width": 0, "height": 0, "fps": 0, "videoBitrateKbps": 0, "audioBitrateKbps": 0 } ], "audioOutputs": [ { "name": "string", "codec": "aac", "bitrateKbps": 0 } ] }, "latency": "low", "dvrMinutes": 0, "maxViewers": 0, "createdAt": "string", "updatedAt": "string", "revision": 0, "position": 0, "processingMbps": 0, "playback": { "hls": true, "llHls": true, "webrtc": true, "icecast": [ { "format": "aac", "bitrateKbps": 0 } ], "rtmpPull": true, "srtPull": true, "urls": { "hls": "string", "whep": "string", "embed": "string", "thumb": "string", "status": "string", "audio": [ { "format": "aac", "url": "string" } ], "rtmpPull": "string", "srtPull": "string" } } } ], "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a channelDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/delete
Delete a channel; its playback URLs stop serving once the node applies the change.
- Requires
stream:admin. - Refused with
409 STREAM_IN_USEwhile a destination or schedule still uses the channel; the error lists thereferrers.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
channelId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "const": true, "type": "boolean" }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false } } }, "required": [ "status", "generation", "error", "warnings" ], "additionalProperties": false } }, "required": [ "deleted", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "deleted": true, "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead a channelDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId
Return one channel with its full configuration, revision, processingMbps and playback.urls for its enabled outputs: HLS, WHEP, embed page, thumbnail, status, audio streams and RTMP or SRT pulls.
- Requires
stream:read.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
channelId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false }, "access": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "token", "public" ] }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowedOrigins", "allowedCidrs" ], "additionalProperties": false }, "backup": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false, "nullable": true }, "recording": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "storageLink": { "type": "string" }, "prefix": { "type": "string" }, "splitMinutes": { "type": "number" }, "registerAsset": { "type": "boolean" } }, "required": [ "enabled", "storageLink", "prefix", "splitMinutes", "registerAsset" ], "additionalProperties": false }, "failover": { "type": "object", "properties": { "afterMs": { "type": "number" }, "slate": { "type": "string", "nullable": true }, "returnToPrimary": { "type": "boolean" } }, "required": [ "afterMs", "slate", "returnToPrimary" ], "additionalProperties": false }, "encoding": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "passthrough", "ladder" ] }, "includeSource": { "type": "boolean" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "const": "h264", "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "videoBitrateKbps": { "type": "number" }, "audioBitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "width", "height", "fps", "videoBitrateKbps", "audioBitrateKbps" ], "additionalProperties": false } }, "audioOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "bitrateKbps" ], "additionalProperties": false } } }, "required": [ "mode", "includeSource", "renditions", "audioOutputs" ], "additionalProperties": false }, "latency": { "type": "string", "enum": [ "low", "standard", "ultra" ] }, "dvrMinutes": { "type": "number" }, "maxViewers": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "revision": { "type": "number" }, "position": { "type": "number" }, "processingMbps": { "type": "number" }, "playback": { "type": "object", "properties": { "hls": { "type": "boolean" }, "llHls": { "type": "boolean" }, "webrtc": { "type": "boolean" }, "icecast": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "format", "bitrateKbps" ], "additionalProperties": false } }, "rtmpPull": { "type": "boolean" }, "srtPull": { "type": "boolean" }, "urls": { "type": "object", "properties": { "hls": { "type": "string" }, "whep": { "type": "string" }, "embed": { "type": "string" }, "thumb": { "type": "string" }, "status": { "type": "string" }, "audio": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "url": { "type": "string" } }, "required": [ "format", "url" ], "additionalProperties": false } }, "rtmpPull": { "type": "string" }, "srtPull": { "type": "string" } }, "required": [ "hls", "whep", "embed", "thumb", "status", "audio" ], "additionalProperties": false, "nullable": true } }, "required": [ "hls", "llHls", "webrtc", "icecast", "rtmpPull", "srtPull", "urls" ], "additionalProperties": false } }, "required": [ "id", "name", "enabled", "source", "access", "backup", "recording", "failover", "encoding", "latency", "dvrMinutes", "maxViewers", "createdAt", "updatedAt", "revision", "position", "processingMbps", "playback" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "id": "string", "name": "string", "enabled": true, "source": { "type": "input", "ref": "string" }, "access": { "mode": "token", "allowedOrigins": [ "string" ], "allowedCidrs": [ "string" ] }, "backup": { "type": "input", "ref": "string" }, "recording": { "enabled": true, "storageLink": "string", "prefix": "string", "splitMinutes": 0, "registerAsset": true }, "failover": { "afterMs": 0, "slate": "string", "returnToPrimary": true }, "encoding": { "mode": "passthrough", "includeSource": true, "renditions": [ { "name": "string", "codec": "string", "width": 0, "height": 0, "fps": 0, "videoBitrateKbps": 0, "audioBitrateKbps": 0 } ], "audioOutputs": [ { "name": "string", "codec": "aac", "bitrateKbps": 0 } ] }, "latency": "low", "dvrMinutes": 0, "maxViewers": 0, "createdAt": "string", "updatedAt": "string", "revision": 0, "position": 0, "processingMbps": 0, "playback": { "hls": true, "llHls": true, "webrtc": true, "icecast": [ { "format": "aac", "bitrateKbps": 0 } ], "rtmpPull": true, "srtPull": true, "urls": { "hls": "string", "whep": "string", "embed": "string", "thumb": "string", "status": "string", "audio": [ { "format": "aac", "url": "string" } ], "rtmpPull": "string", "srtPull": "string" } } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETGet playback URLsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/playback
Return a channel's playback URLs for its enabled outputs, an embedHtml snippet for the embed player, and tokenRequired, true when the channel's access mode is token.
- Requires
stream:read. - When
tokenRequiredis true, add a playback token as?token=(orAuthorization: Beareron WHEP); the HLS playlist carries it on to every child URL.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
channelId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "urls": { "type": "object", "properties": { "hls": { "type": "string" }, "whep": { "type": "string" }, "embed": { "type": "string" }, "thumb": { "type": "string" }, "status": { "type": "string" }, "audio": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "url": { "type": "string" } }, "required": [ "format", "url" ], "additionalProperties": false } }, "rtmpPull": { "type": "string" }, "srtPull": { "type": "string" } }, "required": [ "hls", "whep", "embed", "thumb", "status", "audio" ], "additionalProperties": false }, "embedHtml": { "type": "string" }, "tokenRequired": { "type": "boolean" } }, "required": [ "urls", "embedHtml", "tokenRequired" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "urls": { "hls": "string", "whep": "string", "embed": "string", "thumb": "string", "status": "string", "audio": [ { "format": "aac", "url": "string" } ], "rtmpPull": "string", "srtPull": "string" }, "embedHtml": "string", "tokenRequired": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a test playback tokenDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/token/create
Sign a viewer token for this channel with the server's newest active playback key, to test token-protected playback. Apps should sign their own viewer tokens on their backend with a playback key.
- Requires
stream:operate. ttlSecondsis 1–86,400;sub(at most 128 characters) is a viewer id for statistics;iplimits the token to an IPv4 address or CIDR. Invalid values return422 STREAM_INVALID.- Without an active playback key:
409 STREAM_PLAYBACK_KEY_MISSING. - Sent with
cache-control: no-store.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
channelId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
ttlSeconds | number | Yes |
sub | string | No |
ip | string | No |
Complete request schema
{
"type": "object",
"properties": {
"ttlSeconds": {
"type": "number"
},
"sub": {
"type": "string"
},
"ip": {
"type": "string"
}
},
"required": [
"ttlSeconds"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "token", "expiresAt" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "token": "string", "expiresAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTUpdate a channelDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/update
Change any part of a channel. Omitted fields keep their value and objects merge one level deep, so {playback: {webrtc: false}} keeps the other playback outputs; arrays replace. To switch what a live channel plays without saving it, use channel.source in the control call.
- Requires
stream:admin. - Send
revisionequal to the channel's currentrevision; if it changed meanwhile you get409 STREAM_REVISION_CONFLICT. - Invalid configuration returns
422 STREAM_INVALIDwithdetails; warnings such asprocessing_over_caporbframes_need_transcodecome back insync.warnings.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
channelId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
source | object | No |
access | object | No |
backup | object | No |
recording | object | No |
playback | object | No |
failover | object | No |
encoding | object | No |
latency | low | standard | ultra | No |
dvrMinutes | number | No |
maxViewers | number | No |
name | string | No |
enabled | boolean | No |
position | number | No |
revision | number | Yes |
Complete request schema
{
"type": "object",
"properties": {
"source": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"input",
"mixer",
"playlist"
]
},
"ref": {
"type": "string"
}
},
"required": [
"type",
"ref"
],
"additionalProperties": false
},
"access": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"token",
"public"
]
},
"allowedOrigins": {
"type": "array",
"items": {
"type": "string"
}
},
"allowedCidrs": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"mode",
"allowedOrigins",
"allowedCidrs"
],
"additionalProperties": false
},
"backup": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"input",
"mixer",
"playlist"
]
},
"ref": {
"type": "string"
}
},
"required": [
"type",
"ref"
],
"additionalProperties": false,
"nullable": true
},
"recording": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"storageLink": {
"type": "string"
},
"prefix": {
"type": "string"
},
"splitMinutes": {
"type": "number"
},
"registerAsset": {
"type": "boolean"
}
},
"required": [
"enabled",
"storageLink",
"prefix",
"splitMinutes",
"registerAsset"
],
"additionalProperties": false
},
"playback": {
"type": "object",
"properties": {
"hls": {
"type": "boolean"
},
"llHls": {
"type": "boolean"
},
"webrtc": {
"type": "boolean"
},
"icecast": {
"type": "array",
"items": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"aac",
"mp3",
"opus"
]
},
"bitrateKbps": {
"type": "number"
}
},
"required": [
"format",
"bitrateKbps"
],
"additionalProperties": false
}
},
"rtmpPull": {
"type": "boolean"
},
"srtPull": {
"type": "boolean"
}
},
"required": [
"hls",
"llHls",
"webrtc",
"icecast",
"rtmpPull",
"srtPull"
],
"additionalProperties": false
},
"failover": {
"type": "object",
"properties": {
"afterMs": {
"type": "number"
},
"slate": {
"type": "string",
"nullable": true
},
"returnToPrimary": {
"type": "boolean"
}
},
"required": [
"afterMs",
"slate",
"returnToPrimary"
],
"additionalProperties": false
},
"encoding": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"passthrough",
"ladder"
]
},
"includeSource": {
"type": "boolean"
},
"renditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"codec": {
"const": "h264",
"type": "string"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"fps": {
"type": "number"
},
"videoBitrateKbps": {
"type": "number"
},
"audioBitrateKbps": {
"type": "number"
}
},
"required": [
"name",
"codec",
"width",
"height",
"fps",
"videoBitrateKbps",
"audioBitrateKbps"
],
"additionalProperties": false
}
},
"audioOutputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"codec": {
"type": "string",
"enum": [
"aac",
"mp3",
"opus"
]
},
"bitrateKbps": {
"type": "number"
}
},
"required": [
"name",
"codec",
"bitrateKbps"
],
"additionalProperties": false
}
}
},
"required": [
"mode",
"includeSource",
"renditions",
"audioOutputs"
],
"additionalProperties": false
},
"latency": {
"type": "string",
"enum": [
"low",
"standard",
"ultra"
]
},
"dvrMinutes": {
"type": "number"
},
"maxViewers": {
"type": "number"
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"position": {
"type": "number"
},
"revision": {
"type": "number"
}
},
"required": [
"revision"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "channel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false }, "access": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "token", "public" ] }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "allowedOrigins", "allowedCidrs" ], "additionalProperties": false }, "backup": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false, "nullable": true }, "recording": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "storageLink": { "type": "string" }, "prefix": { "type": "string" }, "splitMinutes": { "type": "number" }, "registerAsset": { "type": "boolean" } }, "required": [ "enabled", "storageLink", "prefix", "splitMinutes", "registerAsset" ], "additionalProperties": false }, "failover": { "type": "object", "properties": { "afterMs": { "type": "number" }, "slate": { "type": "string", "nullable": true }, "returnToPrimary": { "type": "boolean" } }, "required": [ "afterMs", "slate", "returnToPrimary" ], "additionalProperties": false }, "encoding": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "passthrough", "ladder" ] }, "includeSource": { "type": "boolean" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "const": "h264", "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "videoBitrateKbps": { "type": "number" }, "audioBitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "width", "height", "fps", "videoBitrateKbps", "audioBitrateKbps" ], "additionalProperties": false } }, "audioOutputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "codec": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "name", "codec", "bitrateKbps" ], "additionalProperties": false } } }, "required": [ "mode", "includeSource", "renditions", "audioOutputs" ], "additionalProperties": false }, "latency": { "type": "string", "enum": [ "low", "standard", "ultra" ] }, "dvrMinutes": { "type": "number" }, "maxViewers": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "revision": { "type": "number" }, "position": { "type": "number" }, "processingMbps": { "type": "number" }, "playback": { "type": "object", "properties": { "hls": { "type": "boolean" }, "llHls": { "type": "boolean" }, "webrtc": { "type": "boolean" }, "icecast": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "bitrateKbps": { "type": "number" } }, "required": [ "format", "bitrateKbps" ], "additionalProperties": false } }, "rtmpPull": { "type": "boolean" }, "srtPull": { "type": "boolean" }, "urls": { "type": "object", "properties": { "hls": { "type": "string" }, "whep": { "type": "string" }, "embed": { "type": "string" }, "thumb": { "type": "string" }, "status": { "type": "string" }, "audio": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "aac", "mp3", "opus" ] }, "url": { "type": "string" } }, "required": [ "format", "url" ], "additionalProperties": false } }, "rtmpPull": { "type": "string" }, "srtPull": { "type": "string" } }, "required": [ "hls", "whep", "embed", "thumb", "status", "audio" ], "additionalProperties": false, "nullable": true } }, "required": [ "hls", "llHls", "webrtc", "icecast", "rtmpPull", "srtPull", "urls" ], "additionalProperties": false } }, "required": [ "id", "name", "enabled", "source", "access", "backup", "recording", "failover", "encoding", "latency", "dvrMinutes", "maxViewers", "createdAt", "updatedAt", "revision", "position", "processingMbps", "playback" ], "additionalProperties": false }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false } } }, "required": [ "status", "generation", "error", "warnings" ], "additionalProperties": false } }, "required": [ "channel", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "channel": { "id": "string", "name": "string", "enabled": true, "source": { "type": "input", "ref": "string" }, "access": { "mode": "token", "allowedOrigins": [ "string" ], "allowedCidrs": [ "string" ] }, "backup": { "type": "input", "ref": "string" }, "recording": { "enabled": true, "storageLink": "string", "prefix": "string", "splitMinutes": 0, "registerAsset": true }, "failover": { "afterMs": 0, "slate": "string", "returnToPrimary": true }, "encoding": { "mode": "passthrough", "includeSource": true, "renditions": [ { "name": "string", "codec": "string", "width": 0, "height": 0, "fps": 0, "videoBitrateKbps": 0, "audioBitrateKbps": 0 } ], "audioOutputs": [ { "name": "string", "codec": "aac", "bitrateKbps": 0 } ] }, "latency": "low", "dvrMinutes": 0, "maxViewers": 0, "createdAt": "string", "updatedAt": "string", "revision": 0, "position": 0, "processingMbps": 0, "playback": { "hls": true, "llHls": true, "webrtc": true, "icecast": [ { "format": "aac", "bitrateKbps": 0 } ], "rtmpPull": true, "srtPull": true, "urls": { "hls": "string", "whep": "string", "embed": "string", "thumb": "string", "status": "string", "audio": [ { "format": "aac", "url": "string" } ], "rtmpPull": "string", "srtPull": "string" } } }, "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] } }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a playback keyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keys/create
Create an active key that signs viewer tokens (HS256, with the key id as kid) and return it with its secret, a 43-character base64url string. Sign tokens on your backend, for example with the SDK's signPlaybackToken.
- Requires
stream:admin. - The
secretis returned once, withcache-control: no-store; it cannot be read again. - A server holds up to 10 playback keys; a duplicate name returns
409 STREAM_NAME_TAKEN.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
name | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retiring" ] }, "fingerprint": { "type": "string" }, "retiringUntil": { "type": "string", "nullable": true }, "revision": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "fingerprint", "retiringUntil", "revision", "createdAt", "updatedAt" ], "additionalProperties": false }, "secret": { "type": "string" }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false } } }, "required": [ "status", "generation", "error", "warnings" ], "additionalProperties": false } }, "required": [ "key", "secret", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "key": { "id": "string", "name": "string", "status": "active", "fingerprint": "string", "retiringUntil": "string", "revision": 0, "createdAt": "string", "updatedAt": "string" }, "secret": "string", "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList playback keysDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keys
List the server's active and retiring playback keys with their fingerprint and, for retiring keys, retiringUntil. Secrets are never returned.
- Requires
stream:read.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retiring" ] }, "fingerprint": { "type": "string" }, "retiringUntil": { "type": "string", "nullable": true }, "revision": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "fingerprint", "retiringUntil", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": [ { "id": "string", "name": "string", "status": "active", "fingerprint": "string", "retiringUntil": "string", "revision": 0, "createdAt": "string", "updatedAt": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a playback keyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keys/:keyId/delete
Delete a playback key now: tokens signed with it stop working once the node applies the change. Apps bound to it are switched to the newest active key, or lose the key variables when none is left.
- Requires
stream:admin. - To replace a key without cutting off viewers, rotate it instead.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
keyId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "const": true, "type": "boolean" }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false } } }, "required": [ "status", "generation", "error", "warnings" ], "additionalProperties": false } }, "required": [ "deleted", "sync" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "deleted": true, "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] } }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRotate a playback keyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keys/:keyId/rotate
Create a replacement active key with the same name and mark the old one retiring: tokens it signed keep working for 24 hours (retiringUntil), then it is removed. Apps bound to the old key get the new key written into their variables.
- Requires
stream:admin. - The new
secretis returned once, withcache-control: no-store;retireddescribes the old key. - Only active keys rotate:
409 STREAM_PLAYBACK_KEY_NOT_ACTIVE.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
keyId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retiring" ] }, "fingerprint": { "type": "string" }, "retiringUntil": { "type": "string", "nullable": true }, "revision": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "fingerprint", "retiringUntil", "revision", "createdAt", "updatedAt" ], "additionalProperties": false }, "secret": { "type": "string" }, "sync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "applied" ] }, "generation": { "type": "number" }, "error": { "type": "string", "nullable": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ], "additionalProperties": false } } }, "required": [ "status", "generation", "error", "warnings" ], "additionalProperties": false }, "retired": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retiring" ] }, "fingerprint": { "type": "string" }, "retiringUntil": { "type": "string", "nullable": true }, "revision": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "status", "fingerprint", "retiringUntil", "revision", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "key", "secret", "sync", "retired" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "key": { "id": "string", "name": "string", "status": "active", "fingerprint": "string", "retiringUntil": "string", "revision": 0, "createdAt": "string", "updatedAt": "string" }, "secret": "string", "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] }, "retired": { "id": "string", "name": "string", "status": "active", "fingerprint": "string", "retiringUntil": "string", "revision": 0, "createdAt": "string", "updatedAt": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }