Managed Streams API · Dashboard
Live control & usage
Go live, switch scenes, start destinations and recordings, read live health, events, viewer stats and usage.
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
- Send control ops in order with an
id(8–64 characters); repeating the sameidwithin 10 minutes returns the first result instead of acting twice. - Read live status for inputs (bitrate, fps, keyframes, B-frames), channels, mixers, destinations and the next schedule fires.
- Page through events with
after, and read per-minute viewer stats and the month's usage and cost. - Studio tokens open the studio socket for meters and previews; they last at most two minutes.
Go live and start restreaming
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/stream/control" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"golive-2026-11-02","ops":[{"op":"channel.start","channel":"'"$CHANNEL_ID"'"},{"op":"destination.start","destination":"'"$DESTINATION_ID"'"}]}'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 (6)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/control | Run live control ops |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/events | List server events |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/live | Read live status |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/stats | Read viewer statistics |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/studio-token/create | Create a studio token |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/usage | Read monthly usage |
POSTRun live control opsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/control
Send control ops to the running server: switch mixer scenes and adjust layers, audio and text, set graphic variables, start or stop channels and switch their source or slate, start or stop destinations and recordings, cut clips, play or skip playlist items and disconnect a publisher. Ops run in order with one result each; a failing op does not undo earlier ones.
- Requires
stream:operate. id(8–64 letters, digits,_or-) makes the request idempotent for 10 minutes: a retry with the sameidreturns the first response instead of running the ops again.- Ops are checked against the server's configuration first; unknown references or invalid fields return
422 STREAM_INVALIDwithdetailsbefore anything runs. - Fields are camelCase (
gainDb,durationMs).clip.createtakesfromandtoas RFC 3339 times or negative offsets such as-90sand returns the newclipid in its result. - Live control state (active scene, current source, slate, started destinations) survives node restarts but is not saved in the server's configuration.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
id | string | Yes |
ops | object | object | object | object | object | object | object | object | object | object | object | object | object | object[] | Yes |
Complete request schema
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"ops": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"op": {
"const": "mixer.scene",
"type": "string"
},
"mixer": {
"type": "string"
},
"scene": {
"type": "string"
},
"transition": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"cut",
"fade"
]
},
"durationMs": {
"type": "number"
}
},
"required": [
"type",
"durationMs"
],
"additionalProperties": false
}
},
"required": [
"op",
"mixer",
"scene"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "mixer.layer",
"type": "string"
},
"mixer": {
"type": "string"
},
"source": {
"type": "string"
},
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"w": {
"type": "number"
},
"h": {
"type": "number"
},
"crop": {
"type": "object",
"properties": {
"l": {
"type": "number"
},
"t": {
"type": "number"
},
"r": {
"type": "number"
},
"b": {
"type": "number"
}
},
"required": [
"l",
"t",
"r",
"b"
],
"additionalProperties": false
},
"z": {
"type": "number"
},
"opacity": {
"type": "number"
},
"visible": {
"type": "boolean"
}
},
"required": [
"op",
"mixer",
"source"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "mixer.audio",
"type": "string"
},
"mixer": {
"type": "string"
},
"source": {
"type": "string"
},
"gainDb": {
"type": "number"
},
"muted": {
"type": "boolean"
}
},
"required": [
"op",
"mixer",
"source"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "mixer.text",
"type": "string"
},
"mixer": {
"type": "string"
},
"source": {
"type": "string"
},
"text": {
"type": "string"
}
},
"required": [
"op",
"mixer",
"source",
"text"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "graphics.set",
"type": "string"
},
"graphic": {
"type": "string"
},
"variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"op",
"graphic",
"variables"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"channel.start",
"channel.stop"
]
},
"channel": {
"type": "string"
}
},
"required": [
"op",
"channel"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "channel.source",
"type": "string"
},
"channel": {
"type": "string"
},
"source": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"input",
"mixer",
"playlist"
]
},
"ref": {
"type": "string"
}
},
"required": [
"type",
"ref"
],
"additionalProperties": false
}
},
"required": [
"op",
"channel",
"source"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "channel.slate",
"type": "string"
},
"channel": {
"type": "string"
},
"on": {
"type": "boolean"
},
"slate": {
"type": "string"
}
},
"required": [
"op",
"channel",
"on"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"destination.start",
"destination.stop"
]
},
"destination": {
"type": "string"
}
},
"required": [
"op",
"destination"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"recording.start",
"recording.stop"
]
},
"channel": {
"type": "string"
}
},
"required": [
"op",
"channel"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "clip.create",
"type": "string"
},
"channel": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"name": {
"type": "string"
},
"storageLink": {
"type": "string"
},
"prefix": {
"type": "string"
}
},
"required": [
"op",
"channel",
"from",
"to",
"name"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "playlist.play",
"type": "string"
},
"channel": {
"type": "string"
},
"playlist": {
"type": "string"
},
"item": {
"type": "number"
}
},
"required": [
"op",
"channel",
"playlist"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "playlist.next",
"type": "string"
},
"channel": {
"type": "string"
}
},
"required": [
"op",
"channel"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"op": {
"const": "input.disconnect",
"type": "string"
},
"input": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"primary",
"backup"
]
}
},
"required": [
"op",
"input"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"id",
"ops"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "clip": { "type": "string" } }, "required": [ "ok" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "const": false, "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "ok", "error" ], "additionalProperties": false } ] } } }, "required": [ "id", "results" ], "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", "results": [ null ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList server eventsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/events
Page through the node's event log for this server: inputs connecting, disconnecting and failing over, channels going live or offline, destination, recording, clip and schedule results, processing.rejected, speed.throttled, billing blocks and playlist items. Pass nextCursor back as after to read the next page.
- Requires
stream:read. limitis 1–500 (default 100) andaftermust be anextCursor; other values return422 STREAM_INVALID.- The node keeps events for 7 days.
503 STREAM_NODE_UNAVAILABLEwhen the stream node does not answer.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
after | query | No | string | — |
limit | query | No | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "input.connected", "type": "string" }, "data": { "type": "object", "properties": { "input": { "type": "string" }, "role": { "type": "string", "enum": [ "primary", "backup" ] }, "protocol": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "input", "role", "protocol" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "input.disconnected", "type": "string" }, "data": { "type": "object", "properties": { "input": { "type": "string" }, "role": { "type": "string", "enum": [ "primary", "backup" ] }, "protocol": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "input", "role", "protocol" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "input.failover", "type": "string" }, "data": { "type": "object", "properties": { "input": { "type": "string" }, "channel": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "channel.live", "type": "string" }, "data": { "type": "object", "properties": { "channel": { "type": "string" } }, "required": [ "channel" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "channel.offline", "type": "string" }, "data": { "type": "object", "properties": { "channel": { "type": "string" } }, "required": [ "channel" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "destination.connected", "type": "string" }, "data": { "type": "object", "properties": { "destination": { "type": "string" }, "error": { "type": "string" }, "retryInMs": { "type": "number" } }, "required": [ "destination" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "destination.failed", "type": "string" }, "data": { "type": "object", "properties": { "destination": { "type": "string" }, "error": { "type": "string" }, "retryInMs": { "type": "number" } }, "required": [ "destination" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "destination.stopped", "type": "string" }, "data": { "type": "object", "properties": { "destination": { "type": "string" }, "error": { "type": "string" }, "retryInMs": { "type": "number" } }, "required": [ "destination" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "recording.started", "type": "string" }, "data": { "type": "object", "properties": { "recording": { "type": "string" }, "channel": { "type": "string" } }, "required": [ "recording", "channel" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "recording.completed", "type": "string" }, "data": { "type": "object", "properties": { "recording": { "type": "string" }, "channel": { "type": "string" }, "storageLink": { "type": "string" }, "objectKey": { "type": "string" }, "part": { "type": "number" }, "bytes": { "type": "number" }, "durationMs": { "type": "number" }, "startedAt": { "type": "string" }, "endedAt": { "type": "string" }, "registerAsset": { "type": "boolean" } }, "required": [ "recording", "channel", "storageLink", "objectKey", "part", "bytes", "durationMs", "startedAt", "endedAt", "registerAsset" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "recording.failed", "type": "string" }, "data": { "type": "object", "properties": { "recording": { "type": "string" }, "channel": { "type": "string" }, "error": { "type": "string" } }, "required": [ "recording", "channel", "error" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "clip.completed", "type": "string" }, "data": { "type": "object", "properties": { "clip": { "type": "string" }, "channel": { "type": "string" }, "storageLink": { "type": "string" }, "objectKey": { "type": "string" }, "bytes": { "type": "number" }, "durationMs": { "type": "number" }, "name": { "type": "string" } }, "required": [ "clip", "channel", "storageLink", "objectKey", "bytes", "durationMs", "name" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "clip.failed", "type": "string" }, "data": { "type": "object", "properties": { "clip": { "type": "string" }, "channel": { "type": "string" }, "storageLink": { "type": "string" }, "objectKey": { "type": "string" }, "bytes": { "type": "number" }, "durationMs": { "type": "number" }, "name": { "type": "string" }, "error": { "type": "string" } }, "required": [ "clip", "channel", "name" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "schedule.fired", "type": "string" }, "data": { "type": "object", "properties": { "schedule": { "type": "string" }, "fireId": { "type": "string" }, "phase": { "type": "string", "enum": [ "start", "end" ] }, "at": { "type": "string" }, "error": { "type": "string" } }, "required": [ "schedule", "fireId", "phase", "at" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "schedule.missed", "type": "string" }, "data": { "type": "object", "properties": { "schedule": { "type": "string" }, "fireId": { "type": "string" }, "phase": { "type": "string", "enum": [ "start", "end" ] }, "at": { "type": "string" }, "error": { "type": "string" } }, "required": [ "schedule", "fireId", "phase", "at" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "schedule.failed", "type": "string" }, "data": { "type": "object", "properties": { "schedule": { "type": "string" }, "fireId": { "type": "string" }, "phase": { "type": "string", "enum": [ "start", "end" ] }, "at": { "type": "string" }, "error": { "type": "string" } }, "required": [ "schedule", "fireId", "phase", "at" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "processing.rejected", "type": "string" }, "data": { "type": "object", "properties": { "channel": { "type": "string" }, "mixer": { "type": "string" }, "neededMbps": { "type": "number" }, "availableMbps": { "type": "number" } }, "required": [ "neededMbps", "availableMbps" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "speed.throttled", "type": "string" }, "data": { "type": "object", "properties": { "egressMbps": { "type": "number" }, "speedMbps": { "type": "number" } }, "required": [ "egressMbps", "speedMbps" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "billing.blocked", "type": "string" }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "suspended", "balance", "spend_cap" ], "nullable": true } }, "required": [ "reason" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "billing.unblocked", "type": "string" }, "data": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "suspended", "balance", "spend_cap" ], "nullable": true } }, "required": [ "reason" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "seq": { "type": "string" }, "id": { "type": "string" }, "at": { "type": "string" }, "type": { "const": "playlist.item", "type": "string" }, "data": { "type": "object", "properties": { "channel": { "type": "string" }, "playlist": { "type": "string" }, "item": { "type": "number" }, "title": { "type": "string" } }, "required": [ "channel", "playlist", "item", "title" ], "additionalProperties": false } }, "required": [ "seq", "id", "at", "type", "data" ], "additionalProperties": false } ] } }, "nextCursor": { "type": "string" } }, "required": [ "events", "nextCursor" ], "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": { "events": [ null ], "nextCursor": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead live statusDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/live
Return the node's live view of the server: run state, billing, egress against the speed cap (throttled), processing used and viewers; each input's state and publishers (codecs, resolution, bitrate, SRT statistics); mixers and their active scene; channels with on-air and slate state, viewers per protocol, renditions, recording and playlist; destinations; and each schedule's next and last fire.
- Requires
stream:read. - Cached for at most 2 seconds per server: many tabs polling cause one node request per window.
- States: input
live,offline,disabled; channellive,starting,offline,disabled; rendition and mixerrunning,waiting,error,rejected(no processing capacity); destinationconnected,connecting,retrying,stopped,error,disabled. - Publisher
remoteaddresses are masked to the first two IPv4 octets. 503 STREAM_NODE_UNAVAILABLEwhen the stream node does not answer.
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": { "server": { "type": "object", "properties": { "runState": { "type": "string", "enum": [ "stopped", "running" ] }, "billing": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "suspended", "balance", "spend_cap" ], "nullable": true } }, "required": [ "allowed", "reason" ], "additionalProperties": false }, "egressMbps": { "type": "number" }, "speedMbps": { "type": "number" }, "throttled": { "type": "boolean" }, "processingMbpsUsed": { "type": "number" }, "processingMbps": { "type": "number" }, "viewers": { "type": "number" }, "webrtcSessions": { "type": "number" } }, "required": [ "runState", "billing", "egressMbps", "speedMbps", "throttled", "processingMbpsUsed", "processingMbps", "viewers", "webrtcSessions" ], "additionalProperties": false }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "live", "disabled", "offline" ] }, "activeRole": { "type": "string", "enum": [ "primary", "backup" ], "nullable": true }, "publishers": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "primary", "backup" ] }, "protocol": { "type": "string" }, "remote": { "type": "string" }, "since": { "type": "string" }, "video": { "type": "object", "properties": { "codec": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "fps": { "type": "number" }, "bitrateKbps": { "type": "number" }, "keyframeIntervalMs": { "type": "number" }, "bframes": { "type": "boolean" } }, "required": [ "codec", "width", "height", "fps", "bitrateKbps", "keyframeIntervalMs", "bframes" ], "additionalProperties": false, "nullable": true }, "audio": { "type": "object", "properties": { "codec": { "type": "string" }, "sampleRate": { "type": "number" }, "channels": { "type": "number" }, "bitrateKbps": { "type": "number" } }, "required": [ "codec", "sampleRate", "channels", "bitrateKbps" ], "additionalProperties": false, "nullable": true }, "srt": { "type": "object", "properties": { "rttMs": { "type": "number" }, "lossPct": { "type": "number" }, "retransmits": { "type": "number" }, "latencyMs": { "type": "number" } }, "required": [ "rttMs", "lossPct", "retransmits", "latencyMs" ], "additionalProperties": false, "nullable": true } }, "required": [ "role", "protocol", "remote", "since", "video", "audio", "srt" ], "additionalProperties": false } } }, "required": [ "id", "state", "activeRole", "publishers" ], "additionalProperties": false } }, "mixers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "rejected", "stopped", "running", "waiting", "error" ] }, "activeScene": { "type": "string" }, "processingMbps": { "type": "number" }, "error": { "type": "string", "nullable": true } }, "required": [ "id", "state", "activeScene", "processingMbps" ], "additionalProperties": false } }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "live", "disabled", "starting", "offline" ] }, "onAir": { "type": "boolean" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input", "mixer", "playlist" ] }, "ref": { "type": "string" } }, "required": [ "type", "ref" ], "additionalProperties": false, "nullable": true }, "onSlate": { "type": "boolean" }, "viewers": { "type": "object", "properties": { "hls": { "type": "number" }, "webrtc": { "type": "number" }, "icecast": { "type": "number" }, "pull": { "type": "number" } }, "required": [ "hls", "webrtc", "icecast", "pull" ], "additionalProperties": false }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "rejected", "stopped", "running", "waiting", "error" ] }, "processingMbps": { "type": "number" }, "error": { "type": "string", "nullable": true } }, "required": [ "name", "state", "processingMbps" ], "additionalProperties": false } }, "recording": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "error", "recording", "uploading", "idle" ] }, "id": { "type": "string" }, "since": { "type": "string", "nullable": true } }, "required": [ "state", "id", "since" ], "additionalProperties": false, "nullable": true }, "playlist": { "type": "object", "properties": { "id": { "type": "string" }, "item": { "type": "number" }, "title": { "type": "string" } }, "required": [ "id", "item", "title" ], "additionalProperties": false, "nullable": true } }, "required": [ "id", "state", "onAir", "source", "onSlate", "viewers", "renditions", "recording", "playlist" ], "additionalProperties": false } }, "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "disabled", "stopped", "error", "connected", "connecting", "retrying" ] }, "since": { "type": "string", "nullable": true }, "bitrateKbps": { "type": "number" }, "retries": { "type": "number" }, "lastError": { "type": "string", "nullable": true } }, "required": [ "id", "state", "since", "bitrateKbps", "retries", "lastError" ], "additionalProperties": false } }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nextFire": { "type": "string", "nullable": true }, "lastFire": { "type": "object", "properties": { "at": { "type": "string" }, "status": { "type": "string", "enum": [ "error", "ok", "missed" ] } }, "required": [ "at", "status" ], "additionalProperties": false, "nullable": true } }, "required": [ "id", "nextFire", "lastFire" ], "additionalProperties": false } } }, "required": [ "server", "inputs", "mixers", "channels", "destinations", "schedules" ], "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": { "server": { "runState": "stopped", "billing": { "allowed": true, "reason": "suspended" }, "egressMbps": 0, "speedMbps": 0, "throttled": true, "processingMbpsUsed": 0, "processingMbps": 0, "viewers": 0, "webrtcSessions": 0 }, "inputs": [ { "id": "string", "state": "live", "activeRole": "primary", "publishers": [ { "role": "primary", "protocol": "string", "remote": "string", "since": "string", "video": { "codec": "string", "width": 0, "height": 0, "fps": 0, "bitrateKbps": 0, "keyframeIntervalMs": 0, "bframes": true }, "audio": { "codec": "string", "sampleRate": 0, "channels": 0, "bitrateKbps": 0 }, "srt": { "rttMs": 0, "lossPct": 0, "retransmits": 0, "latencyMs": 0 } } ] } ], "mixers": [ { "id": "string", "state": "rejected", "activeScene": "string", "processingMbps": 0, "error": "string" } ], "channels": [ { "id": "string", "state": "live", "onAir": true, "source": { "type": "input", "ref": "string" }, "onSlate": true, "viewers": { "hls": 0, "webrtc": 0, "icecast": 0, "pull": 0 }, "renditions": [ { "name": "string", "state": "rejected", "processingMbps": 0, "error": "string" } ], "recording": { "state": "error", "id": "string", "since": "string" }, "playlist": { "id": "string", "item": 0, "title": "string" } } ], "destinations": [ { "id": "string", "state": "disabled", "since": "string", "bitrateKbps": 0, "retries": 0, "lastError": "string" } ], "schedules": [ { "id": "string", "nextFire": "string", "lastFire": { "at": "string", "status": "error" } } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead viewer statisticsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/stats
Return per-minute viewer statistics from the node for charts: per channel and minute, viewers, viewer-seconds, egress bytes and viewers by country.
- Requires
stream:read. fromandtoare RFC 3339 times or dates (default: the node's last hour);channelIdnarrows to one channel. A malformed time returns422 STREAM_INVALID.- The node keeps statistics for 35 days. Countries come from IP geolocation; viewer IP addresses are never stored.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
from | query | No | string | — |
to | query | No | string | — |
channelId | query | No | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "points": { "type": "array", "items": { "type": "object", "properties": { "minute": { "type": "string" }, "channel": { "type": "string" }, "viewers": { "type": "number" }, "viewerSeconds": { "type": "number" }, "egressBytes": { "type": "number" }, "countries": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "minute", "channel", "viewers", "viewerSeconds", "egressBytes", "countries" ], "additionalProperties": false } } }, "required": [ "points" ], "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": { "points": [ { "minute": "string", "channel": "string", "viewers": 0, "viewerSeconds": 0, "egressBytes": 0, "countries": null } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a studio tokenDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/studio-token/create
Mint a short-lived, single-use token for the studio WebSocket at url (wss://<host>/v1/studio), which streams live status, events, audio meters and previews. Send it as the first frame, {"type":"auth","token":…}. Every caller gets the read and preview scopes; callers with stream:operate also get operate.
- Requires
stream:read;stream:operateadds theoperatescope. - The token lives at most 60 seconds and is bound to
origin(default: the request'sOrigin), which must be one of the server'sstudioOriginsorhubfly-cli; otherwise403 STREAM_STUDIO_ORIGIN. - Sent with
cache-control: no-store. Tokens are never logged; the audit log records the token id and scopes.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
origin | string | No |
Complete request schema
{
"type": "object",
"properties": {
"origin": {
"type": "string"
}
},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "url": { "type": "string" }, "expiresAt": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "preview", "operate" ] } } }, "required": [ "token", "url", "expiresAt", "scopes" ], "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", "url": "string", "expiresAt": "string", "scopes": [ "read" ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead monthly usageDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/usage
Return one month of this server's usage: totals of speed and processing Mbps-hours, bandwidth GB and cost; the owner's free pools used (shared by all of the owner's stream servers); hourly rows with egress per class (hls, webrtc, icecast, push, pull), viewer hours and peak viewers; and estimatedMonthUsd.
- Requires
stream:read. monthisYYYY-MM(UTC), default the current month; another format returns400 STREAM_INVALID_MONTH.modeis the stream billing mode (write,shadoworoff);chargedis false when the costs shown are estimates that are not billed.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
month | query | No | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "month": { "type": "string" }, "free": { "type": "object", "properties": { "bandwidthGbUsed": { "type": "number" }, "bandwidthGbTotal": { "type": "number" }, "processingMbpsHoursUsed": { "type": "number" }, "processingMbpsHoursTotal": { "type": "number" }, "freeSpeedMbps": { "type": "number" } }, "required": [ "bandwidthGbUsed", "bandwidthGbTotal", "processingMbpsHoursUsed", "processingMbpsHoursTotal", "freeSpeedMbps" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "speedMbpsHours": { "type": "number" }, "processingMbpsHours": { "type": "number" }, "bandwidthGb": { "type": "number" }, "costUsd": { "type": "number" } }, "required": [ "speedMbpsHours", "processingMbpsHours", "bandwidthGb", "costUsd" ], "additionalProperties": false }, "estimatedMonthUsd": { "type": "number" }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "peakViewers": { "type": "number" }, "hour": { "type": "string" }, "speedMbpsHours": { "type": "number" }, "processingMbpsHours": { "type": "number" }, "viewerHours": { "type": "number" }, "costUsd": { "type": "number" }, "egressGb": { "type": "object", "properties": { "hls": { "type": "number" }, "webrtc": { "type": "number" }, "icecast": { "type": "number" }, "push": { "type": "number" }, "pull": { "type": "number" } }, "required": [ "hls", "webrtc", "icecast", "push", "pull" ], "additionalProperties": false } }, "required": [ "peakViewers", "hour", "speedMbpsHours", "processingMbpsHours", "viewerHours", "costUsd", "egressGb" ], "additionalProperties": false } }, "mode": { "type": "string", "enum": [ "off", "write", "shadow" ] }, "charged": { "type": "boolean" } }, "required": [ "month", "free", "totals", "estimatedMonthUsd", "hourly", "mode", "charged" ], "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": { "month": "string", "free": { "bandwidthGbUsed": 0, "bandwidthGbTotal": 0, "processingMbpsHoursUsed": 0, "processingMbpsHoursTotal": 0, "freeSpeedMbps": 0 }, "totals": { "speedMbpsHours": 0, "processingMbpsHours": 0, "bandwidthGb": 0, "costUsd": 0 }, "estimatedMonthUsd": 0, "hourly": [ { "peakViewers": 0, "hour": "string", "speedMbpsHours": 0, "processingMbpsHours": 0, "viewerHours": 0, "costUsd": 0, "egressGb": { "hls": 0, "webrtc": 0, "icecast": 0, "push": 0, "pull": 0 } } ], "mode": "off", "charged": true }, "meta": { "requestId": "string", "timestamp": "string" } }