Hubfly spaceDocs
Console

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

  1. Create a storage link to a bucket of one of your Storage projects: write for recordings and clips, read for playlists, or read_write for both. You need storage:admin on that project.
  2. 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.
  3. Cut a clip from a channel's DVR window with RFC 3339 times. A channel without DVR returns STREAM_NOT_LIVE.
  4. Deleting a recording removes the record; pass deleteObject to delete the file in Storage too.

Cut a clip from the DVR

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

Open interactive API explorer
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 (dvrMinutes above 0), otherwise 409 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 with write or read_write access) or, by default, the channel's recording link; with neither, 422 STREAM_INVALID (code recording_link).
  • name is 1–200 characters.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
channelIdstringYes
fromstringYes
tostringYes
namestringYes
storageLinkIdstringNo
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 response
    Response 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.
  • limit is 1–200 (default 50); a kind other than recording or clip returns 400 BAD_REQUEST.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
kindqueryNostring—
channelIdqueryNostring—
cursorqueryNostring—
limitqueryNonumber—
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"
                  },
                  "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; deleteObject also needs storage:write on the Storage project that holds the file.
  • Unknown recording: 404 STREAM_RESOURCE_NOT_FOUND.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
recordingIdpathYesstring—
deleteObjectqueryNoboolean—
Responses
  • 200 — Successful response
    Response 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"
      }
    }
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:read here and media:read on the link's Storage project.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
linkIdpathYesstring—
searchqueryNostring—
hlsReadyqueryNoboolean—
Responses
  • 200 — Successful response
    Response 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"
      }
    }

Related guides

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