Managed Streams API · Dashboard
Recordings & clips
Link Hubfly space Storage buckets, list recordings, cut clips from the DVR window and browse playable assets.
Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.
Stream servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the stream server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the stream permissions must hold that exact permission.
How to use these endpoints
- Create a storage link to a bucket of one of your Storage projects:
writefor recordings and clips,readfor playlists, orread_writefor both. You needstorage:adminon that project. - Turn on recording on a channel, or start and stop it with live control. Recordings are split into parts and can be registered as video-on-demand assets.
- Cut a clip from a channel's DVR window with RFC 3339 times. A channel without DVR returns
STREAM_NOT_LIVE. - Deleting a recording removes the record; pass
deleteObjectto delete the file in Storage too.
Cut a clip from the DVR
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/stream/clips/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"channelId":"'"$CHANNEL_ID"'","from":"2026-11-02T18:42:00Z","to":"2026-11-02T18:44:30Z","name":"Opening keynote"}'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 (7)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/clips/create | Cut a clip |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/recordings | List recordings and clips |
| DELETE | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/recordings/:recordingId/delete | Delete a recording |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links/create | Link a Storage bucket |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links | List Storage links |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links/:linkId/assets | List Storage assets of a link |
| DELETE | /api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links/:linkId/delete | Unlink a Storage bucket |
POSTCut a clipDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/clips/create
Cut a clip from a channel's DVR window into Storage and return its clipId; the file appears in the recordings list when the node reports clip.completed. from and to are RFC 3339 times or negative offsets such as -90s.
- Requires
stream:operate. - The channel needs DVR (
dvrMinutesabove 0), otherwise409 STREAM_NOT_LIVE; the same error is returned when the DVR holds no video for that range. - The clip is written through
storageLinkId(a link withwriteorread_writeaccess) or, by default, the channel's recording link; with neither,422 STREAM_INVALID(coderecording_link). nameis 1–200 characters.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
channelId | string | Yes |
from | string | Yes |
to | string | Yes |
name | string | Yes |
storageLinkId | string | No |
Complete request schema
{
"type": "object",
"properties": {
"channelId": {
"type": "string"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"name": {
"type": "string"
},
"storageLinkId": {
"type": "string"
}
},
"required": [
"channelId",
"from",
"to",
"name"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "clipId": { "type": "string" } }, "required": [ "clipId" ], "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": { "clipId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList recordings and clipsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/recordings
List this server's recordings (one row per part) and clips, newest first, with their status (recording, uploading, completed, registered or failed), Storage project, bucket, object key and asset, size and duration. Filter with kind and channelId, and pass nextCursor back as cursor for the next page.
- Requires
stream:read. limitis 1–200 (default 50); akindother thanrecordingorclipreturns400 BAD_REQUEST.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
kind | query | No | string | — |
channelId | query | No | string | — |
cursor | query | No | string | — |
limit | query | No | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channelId": { "type": "string" }, "kind": { "type": "string", "enum": [ "recording", "clip" ] }, "name": { "type": "string", "nullable": true }, "part": { "type": "number" }, "status": { "type": "string", "enum": [ "failed", "completed", "recording", "uploading", "registered" ] }, "storageLinkId": { "type": "string", "nullable": true }, "storageProjectId": { "type": "string", "nullable": true }, "bucket": { "type": "string", "nullable": true }, "objectKey": { "type": "string", "nullable": true }, "storageAssetId": { "type": "string", "nullable": true }, "bytes": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "startedAt": { "type": "string", "description": "Date string", "nullable": true }, "endedAt": { "type": "string", "description": "Date string", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "storageLink": { "type": "object", "properties": { "id": { "type": "string" }, "storageProjectId": { "type": "string" }, "bucket": { "type": "string" }, "mode": { "type": "string" } }, "required": [ "id", "storageProjectId", "bucket", "mode" ], "additionalProperties": false, "nullable": true } }, "required": [ "id", "channelId", "kind", "name", "part", "status", "storageLinkId", "storageProjectId", "bucket", "objectKey", "storageAssetId", "bytes", "durationMs", "startedAt", "endedAt", "error", "createdAt", "updatedAt", "storageLink" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "channelId": "string", "kind": "recording", "name": "string", "part": 0, "status": "failed", "storageLinkId": "string", "storageProjectId": "string", "bucket": "string", "objectKey": "string", "storageAssetId": "string", "bytes": 0, "durationMs": 0, "startedAt": "string", "endedAt": "string", "error": "string", "createdAt": "string", "updatedAt": "string", "storageLink": { "id": "string", "storageProjectId": "string", "bucket": "string", "mode": "string" } } ], "nextCursor": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a recordingDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/recordings/:recordingId/delete
Delete a recording or clip record. With deleteObject=true its Storage object and asset are deleted too, and objectDeleted reports whether that happened; otherwise the file stays in Storage.
- Requires
stream:admin;deleteObjectalso needsstorage:writeon the Storage project that holds the file. - Unknown recording:
404 STREAM_RESOURCE_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
recordingId | path | Yes | string | — |
deleteObject | query | No | boolean | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "const": true, "type": "boolean" }, "objectDeleted": { "type": "boolean" } }, "required": [ "deleted", "objectDeleted" ], "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, "objectDeleted": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTLink a Storage bucketDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links/create
Link a Hubfly space Storage bucket so the server can read playlist media (read), write recordings and clips (write), or both (read_write). The Dashboard creates a Storage key scoped to that bucket and sends it to the node; its secret is never returned.
- Requires
stream:adminhere andstorage:adminon the Storage project. - A bucket can be linked once per server (
409 STREAM_STORAGE_LINK_EXISTS); a server holds up to 10 links. - An invalid bucket name returns
422 STREAM_INVALID; a Storage region without an S3 endpoint returns409 STREAM_STORAGE_UNAVAILABLE.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
storageProjectId | string | Yes |
bucket | string | Yes |
mode | read | write | read_write | Yes |
Complete request schema
{
"type": "object",
"properties": {
"storageProjectId": {
"type": "string"
},
"bucket": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"read",
"write",
"read_write"
]
}
},
"required": [
"storageProjectId",
"bucket",
"mode"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "storageLink": { "type": "object", "properties": { "id": { "type": "string" }, "storageProjectId": { "type": "string" }, "bucket": { "type": "string" }, "mode": { "type": "string", "enum": [ "read", "write", "read_write" ] }, "endpoint": { "type": "string" }, "region": { "type": "string" }, "accessKeyId": { "type": "string" }, "storageKeyId": { "type": "string", "nullable": true }, "revision": { "type": "number" }, "createdByUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "storageProjectId", "bucket", "mode", "endpoint", "region", "accessKeyId", "storageKeyId", "revision", "createdByUserId", "createdAt", "updatedAt" ], "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": [ "storageLink", "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": { "storageLink": { "id": "string", "storageProjectId": "string", "bucket": "string", "mode": "read", "endpoint": "string", "region": "string", "accessKeyId": "string", "storageKeyId": "string", "revision": 0, "createdByUserId": "string", "createdAt": "string", "updatedAt": "string" }, "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] } }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList Storage linksDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links
List the Hubfly space Storage buckets linked to this server with their Storage project, bucket, mode, S3 endpoint, region and access key id. The secret key is never returned.
- Requires
stream:read.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "storageProjectId": { "type": "string" }, "bucket": { "type": "string" }, "mode": { "type": "string", "enum": [ "read", "write", "read_write" ] }, "endpoint": { "type": "string" }, "region": { "type": "string" }, "accessKeyId": { "type": "string" }, "storageKeyId": { "type": "string", "nullable": true }, "revision": { "type": "number" }, "createdByUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "storageProjectId", "bucket", "mode", "endpoint", "region", "accessKeyId", "storageKeyId", "revision", "createdByUserId", "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", "storageProjectId": "string", "bucket": "string", "mode": "read", "endpoint": "string", "region": "string", "accessKeyId": "string", "storageKeyId": "string", "revision": 0, "createdByUserId": "string", "createdAt": "string", "updatedAt": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
GETList Storage assets of a linkDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links/:linkId/assets
List the Storage video assets in the link's bucket, newest first (at most 500), for picking playlist items: title, object key, size, duration, rendition states and hlsObjectKey, the object an assetId playlist item plays. search matches the title or object key; hlsReady=true keeps only assets with a ready HLS rendition.
- Requires
stream:readhere andmedia:readon the link's Storage project.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
linkId | path | Yes | string | — |
search | query | No | string | — |
hlsReady | query | No | boolean | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "link": { "type": "object", "properties": { "id": { "type": "string" }, "storageProjectId": { "type": "string" }, "bucket": { "type": "string" }, "mode": { "type": "string" } }, "required": [ "id", "storageProjectId", "bucket", "mode" ], "additionalProperties": false }, "assets": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string" }, "title": { "type": "string" }, "objectKey": { "type": "string" }, "contentType": { "type": "string", "nullable": true }, "sizeBytes": { "type": "number" }, "durationSeconds": { "type": "number", "nullable": true }, "hlsReady": { "type": "boolean" }, "hlsObjectKey": { "type": "string", "nullable": true }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "height": { "type": "number" }, "state": { "type": "string" } }, "required": [ "height", "state" ], "additionalProperties": false } }, "createdAt": { "type": "string" } }, "required": [ "assetId", "title", "objectKey", "contentType", "sizeBytes", "durationSeconds", "hlsReady", "hlsObjectKey", "renditions", "createdAt" ], "additionalProperties": false } } }, "required": [ "link", "assets" ], "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": { "link": { "id": "string", "storageProjectId": "string", "bucket": "string", "mode": "string" }, "assets": [ { "assetId": "string", "title": "string", "objectKey": "string", "contentType": "string", "sizeBytes": 0, "durationSeconds": 0, "hlsReady": true, "hlsObjectKey": "string", "renditions": [ { "height": 0, "state": "string" } ], "createdAt": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEUnlink a Storage bucketDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/stream/storage-links/:linkId/delete
Remove the link and revoke its Storage key; files already in the bucket stay. keyRevoked reports whether the key was revoked.
- Requires
stream:admin. - Refused with
409 STREAM_IN_USEwhile a channel records to the link or a playlist reads from it; the error lists thereferrers.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
linkId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "const": true, "type": "boolean" }, "keyRevoked": { "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", "keyRevoked", "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, "keyRevoked": true, "sync": { "status": "pending", "generation": 0, "error": "string", "warnings": [ { "path": "string", "code": "string", "message": "string" } ] } }, "meta": { "requestId": "string", "timestamp": "string" } }