Hubfly spaceDocs
Console

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

  1. Create a media upload session and PUT the source to the returned URL.
  2. Start encoding with a supported maximum height, or encode a previously registered asset.
  3. Read media job state until renditions are ready; encoding is asynchronous.
  4. Issue a short-lived playback URL for a viewer. Re-encode or remove a rendition when needed.

Queue HLS encoding

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

Open interactive API explorer
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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
renditionIdqueryYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
assetIdstringYes
renditionsnumber[]Yes
Complete request schema
{
  "type": "object",
  "properties": {
    "assetId": {
      "type": "string"
    },
    "renditions": {
      "type": "array",
      "items": {
        "type": "number"
      }
    }
  },
  "required": [
    "assetId",
    "renditions"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
bucketstringYes
sourceKeystringYes
maxHeightnumber | number | number | numberYes
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 response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

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

JSON request body

FieldType / allowed valuesRequired
bucketstringYes
objectKeystringYes
contentTypestringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "bucket": {
      "type": "string"
    },
    "objectKey": {
      "type": "string"
    },
    "contentType": {
      "type": "string"
    }
  },
  "required": [
    "bucket",
    "objectKey",
    "contentType"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

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

Related guides

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