Hubfly spaceDocs
Console

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

  1. Create a channel with a source (an input, a mixer or a playlist), its encoding (passthrough or a ladder), playback outputs, latency, DVR and access.
  2. Read the channel's playback route for HLS, WHEP, embed, thumbnail, status and audio URLs and ready-made embed HTML.
  3. For token access, create a playback key. Its secret is returned once: keep it on your server and sign viewer tokens with @hubfly/streams/server or the Go streams package.
  4. A binding writes HUBFLY_STREAM_URL and, with a playback key, HUBFLY_STREAM_PLAYBACK_KEY_ID and HUBFLY_STREAM_PLAYBACK_KEY_SECRET into a Cell project.

Create a low-latency channel from an input

curl
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.

Open interactive API explorer
MethodPathPurpose
POST/api/v1/projects/:projectId/managed/instances/:instanceId/stream/bindings/createConnect a stream server to an app
GET/api/v1/projects/:projectId/managed/instances/:instanceId/stream/bindingsList app bindings
DELETE/api/v1/projects/:projectId/managed/instances/:instanceId/stream/bindings/:bindingId/deleteDisconnect an app
POST/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/createCreate a channel
GET/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channelsList channels
DELETE/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/deleteDelete a channel
GET/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelIdRead a channel
GET/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/playbackGet playback URLs
POST/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/token/createCreate a test playback token
PUT/api/v1/projects/:projectId/managed/instances/:instanceId/stream/channels/:channelId/updateUpdate a channel
POST/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keys/createCreate a playback key
GET/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keysList playback keys
DELETE/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keys/:keyId/deleteDelete a playback key
POST/api/v1/projects/:projectId/managed/instances/:instanceId/stream/playback-keys/:keyId/rotateRotate a playback key
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:admin here and project:edit on the target project.
  • clientPrefix (NEXT_PUBLIC_, VITE_ or PUBLIC_) prefixes the channel and HLS variables for browser code; the key secret never gets a prefix. Any other prefix returns 400 STREAM_INVALID_CLIENT_PREFIX.
  • Only Cell projects can be bound (409 MANAGED_BINDING_TARGET_UNSUPPORTED); a playback key that is not active returns 409 STREAM_PLAYBACK_KEY_NOT_ACTIVE.
  • Rotating or deleting the bound playback key rewrites these variables automatically.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
targetProjectIdstringYes
playbackKeyIdstringNo
channelIdstringNo
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 response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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, and project:edit on the target project when variables are removed.
  • Returns variablesRemoved, the number of variables deleted. Unknown binding: 404 MANAGED_BINDING_NOT_FOUND.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
bindingIdpathYesstring—
removeVariablesqueryNoboolean—
Responses
  • 200 — Successful response
    Response 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.
  • source is required: without it the request returns 422 STREAM_INVALID (code unknown_ref).
  • latency is standard (HLS, 15–25 s behind live), low (LL-HLS, 3–5 s) or ultra (the embed player prefers WebRTC, under 1 s). dvrMinutes is 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 with write or read_write access.
  • A server holds up to 20 channels. Invalid configuration returns 422 STREAM_INVALID with details; a duplicate name returns 409 STREAM_NAME_TAKEN.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
sourceobjectNo
accessobjectNo
backupobjectNo
recordingobjectNo
playbackobjectNo
failoverobjectNo
encodingobjectNo
latencylow | standard | ultraNo
dvrMinutesnumberNo
maxViewersnumberNo
namestringYes
enabledbooleanNo
positionnumberNo
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 response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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_USE while a destination or schedule still uses the channel; the error lists the referrers.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
channelIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
channelIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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 tokenRequired is true, add a playback token as ?token= (or Authorization: Bearer on WHEP); the HLS playlist carries it on to every child URL.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
channelIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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.
  • ttlSeconds is 1–86,400; sub (at most 128 characters) is a viewer id for statistics; ip limits the token to an IPv4 address or CIDR. Invalid values return 422 STREAM_INVALID.
  • Without an active playback key: 409 STREAM_PLAYBACK_KEY_MISSING.
  • Sent with cache-control: no-store.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
channelIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
ttlSecondsnumberYes
substringNo
ipstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "ttlSeconds": {
      "type": "number"
    },
    "sub": {
      "type": "string"
    },
    "ip": {
      "type": "string"
    }
  },
  "required": [
    "ttlSeconds"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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 revision equal to the channel's current revision; if it changed meanwhile you get 409 STREAM_REVISION_CONFLICT.
  • Invalid configuration returns 422 STREAM_INVALID with details; warnings such as processing_over_cap or bframes_need_transcode come back in sync.warnings.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
channelIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
sourceobjectNo
accessobjectNo
backupobjectNo
recordingobjectNo
playbackobjectNo
failoverobjectNo
encodingobjectNo
latencylow | standard | ultraNo
dvrMinutesnumberNo
maxViewersnumberNo
namestringNo
enabledbooleanNo
positionnumberNo
revisionnumberYes
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 response
    Response 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 secret is returned once, with cache-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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
namestringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
keyIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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 secret is returned once, with cache-control: no-store; retired describes the old key.
  • Only active keys rotate: 409 STREAM_PLAYBACK_KEY_NOT_ACTIVE.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
keyIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
Complete request schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top