Storage API · Dashboard
Video & media jobs
Upload a source, request HLS encoding, inspect jobs, issue playback URLs, and manage renditions.
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.
How to use these endpoints
- Create a media upload session and PUT the source to the returned URL.
- Start encoding with a supported maximum height, or encode a previously registered asset.
- Read media job state until renditions are ready; encoding is asynchronous.
- Issue a short-lived playback URL for a viewer. Re-encode or remove a rendition when needed.
Queue HLS encoding
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/storage/media/encode" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"bucket":"project-assets","sourceKey":"video/demo.mp4","maxHeight":720}'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 |
|---|---|---|
| DELETE | /api/v1/projects/:projectId/storage/assets/delete-rendition | Delete a video rendition |
| POST | /api/v1/projects/:projectId/storage/assets/encode | Encode a managed asset |
| POST | /api/v1/projects/:projectId/storage/media/encode | Start a video encoding job |
| GET | /api/v1/projects/:projectId/storage/media | List media jobs and assets |
| POST | /api/v1/projects/:projectId/storage/media/playback | Create a temporary playback URL |
| POST | /api/v1/projects/:projectId/storage/media/upload-session | Create a media upload session |
| POST | /api/v1/projects/:projectId/storage/renditions/reencode | Re-encode a video rendition |
DELETEDelete a video renditionDetails +/api/v1/projects/:projectId/storage/assets/delete-rendition
Deletes one encoded rendition using its renditionId query parameter.
- The selected rendition is no longer available to playback until the source is encoded again.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
renditionId | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "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": { "ok": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTEncode a managed assetDetails +/api/v1/projects/:projectId/storage/assets/encode
Starts video encoding for a registered asset and returns a job identifier and status.
- Encoding requires a supported source video and available worker capacity. Poll the asset or media endpoints for rendition readiness.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
assetId | string | Yes |
renditions | number[] | Yes |
Complete request schema
{
"type": "object",
"properties": {
"assetId": {
"type": "string"
},
"renditions": {
"type": "array",
"items": {
"type": "number"
}
}
},
"required": [
"assetId",
"renditions"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "asset_id": { "type": "string" } }, "required": [ "id", "state", "asset_id" ], "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", "state": "string", "asset_id": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTStart a video encoding jobDetails +/api/v1/projects/:projectId/storage/media/encode
Queues an HLS encoding job for a bucket object and selected maximum output height.
- Supported output heights are 360, 480, 720 and 1080. The source must already exist in the selected bucket.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
bucket | string | Yes |
sourceKey | string | Yes |
maxHeight | number | number | number | number | Yes |
Complete request schema
{
"type": "object",
"properties": {
"bucket": {
"type": "string"
},
"sourceKey": {
"type": "string"
},
"maxHeight": {
"oneOf": [
{
"const": 360,
"type": "number"
},
{
"const": 720,
"type": "number"
},
{
"const": 480,
"type": "number"
},
{
"const": 1080,
"type": "number"
}
]
}
},
"required": [
"bucket",
"sourceKey",
"maxHeight"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "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", "state": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList media jobs and assetsDetails +/api/v1/projects/:projectId/storage/media
Returns the project’s registered media and encoding job state for dashboard monitoring.
- Encoding is asynchronous. A queued or processing job does not yet have a playable HLS manifest.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | 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" }, "bucket": { "type": "string" }, "source_key": { "type": "string" }, "max_height": { "type": "number" }, "state": { "type": "string" }, "progress": { "type": "number" }, "duration_seconds": { "type": "number", "nullable": true }, "error": { "type": "string", "nullable": true }, "output_prefix": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "bucket", "source_key", "max_height", "state", "progress", "duration_seconds", "error", "output_prefix", "created_at", "updated_at" ], "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", "bucket": "string", "source_key": "string", "max_height": 0, "state": "string", "progress": 0, "duration_seconds": 0, "error": "string", "output_prefix": "string", "created_at": "string", "updated_at": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a temporary playback URLDetails +/api/v1/projects/:projectId/storage/media/playback
Creates a signed playback token for a managed video asset or media job.
- Playback URLs are temporary and should be generated when needed instead of stored as permanent links.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
jobId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"jobId": {
"type": "string"
}
},
"required": [
"jobId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "manifest_url": { "type": "string" }, "player_url": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "manifest_url", "player_url", "expires_at" ], "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": { "manifest_url": "string", "player_url": "string", "expires_at": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a media upload sessionDetails +/api/v1/projects/:projectId/storage/media/upload-session
Returns a temporary upload session for a video source object, with media-specific upload handling.
- Finish the upload before requesting encoding. The session is temporary; create a new one if it expires.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
bucket | string | Yes |
objectKey | string | Yes |
contentType | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"bucket": {
"type": "string"
},
"objectKey": {
"type": "string"
},
"contentType": {
"type": "string"
}
},
"required": [
"bucket",
"objectKey",
"contentType"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "upload_url": { "type": "string" }, "object_key": { "type": "string" }, "expires_at": { "type": "string" }, "content_type": { "type": "string" } }, "required": [ "upload_url", "object_key", "expires_at", "content_type" ], "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": { "upload_url": "string", "object_key": "string", "expires_at": "string", "content_type": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRe-encode a video renditionDetails +/api/v1/projects/:projectId/storage/renditions/reencode
Queues a new encode for an existing rendition/source configuration.
- Encoding is asynchronous; inspect job state before relying on the rendition in playback.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
renditionId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"renditionId": {
"type": "string"
}
},
"required": [
"renditionId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "state" ], "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", "state": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }