Storage API · Dashboard
Assets, sharing & images
Register managed assets, set delivery permissions, create shares, and inspect or delete image variants.
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
- Upload an object into an existing bucket, then register it as a managed asset.
- Choose public or protected delivery and configure preview, stream, and download permissions.
- For protected assets, create a short-lived share token. Treat its URL as a secret.
- Inspect generated image variants and remove unneeded variants without deleting the source object.
Register an uploaded object
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/storage/assets/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"bucket":"project-assets","objectKey":"images/logo.png","title":"Logo"}'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 (9)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/projects/:projectId/storage/assets/create | Register a managed media asset |
| DELETE | /api/v1/projects/:projectId/storage/assets/delete | Delete a managed asset |
| GET | /api/v1/projects/:projectId/storage/assets | List managed assets |
| POST | /api/v1/projects/:projectId/storage/assets/regenerate-key | Regenerate a managed asset access key |
| POST | /api/v1/projects/:projectId/storage/assets/share-token | Create a signed asset share link |
| PUT | /api/v1/projects/:projectId/storage/assets/update | Update managed asset delivery settings |
| GET | /api/v1/projects/:projectId/storage/assets/:assetId/access-key | Reveal an asset access key |
| DELETE | /api/v1/projects/:projectId/storage/images/variants/delete | Delete a generated image variant |
| GET | /api/v1/projects/:projectId/storage/images/variants | List generated image variants |
POSTRegister a managed media assetDetails +/api/v1/projects/:projectId/storage/assets/create
Promotes an uploaded bucket object into a managed image or video asset and returns an asset ID and share URL.
- Upload the source object first. This call registers and configures delivery; it is not the raw object upload operation.
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 |
title | string | No |
Complete request schema
{
"type": "object",
"properties": {
"bucket": {
"type": "string"
},
"objectKey": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"bucket",
"objectKey"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string" }, "url_id": { "type": "string" }, "tenant_id": { "type": "string" }, "bucket_id": { "type": "string" }, "bucket": { "type": "string" }, "object_key": { "type": "string" }, "source_version_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number" }, "file_type": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" }, "access_mode": { "type": "string" }, "allow_stream": { "type": "boolean" }, "allow_download": { "type": "boolean" }, "allow_preview": { "type": "boolean" }, "image_retention_seconds": { "type": "number", "nullable": true }, "image_watermark_key": { "type": "string" }, "hls_ready": { "type": "boolean" }, "duration_seconds": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "asset_id": { "type": "string" }, "height": { "type": "number" }, "width": { "type": "number" }, "bandwidth": { "type": "number" }, "state": { "type": "string" }, "job_id": { "type": "string" }, "output_prefix": { "type": "string" }, "size_bytes": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "asset_id", "height", "width", "bandwidth", "state", "output_prefix", "size_bytes", "created_at", "updated_at" ], "additionalProperties": false } }, "asset_url": { "type": "string" }, "player_url": { "type": "string" } }, "required": [ "id", "url_id", "tenant_id", "bucket_id", "bucket", "object_key", "content_type", "size_bytes", "file_type", "title", "state", "access_mode", "allow_stream", "allow_download", "allow_preview", "hls_ready", "duration_seconds", "created_at", "updated_at", "renditions", "asset_url", "player_url" ], "additionalProperties": false }, "asset_url": { "type": "string" }, "player_url": { "type": "string" }, "access_key": { "type": "string" } }, "required": [ "asset", "asset_url", "player_url" ], "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": { "asset": { "id": "string", "url_id": "string", "tenant_id": "string", "bucket_id": "string", "bucket": "string", "object_key": "string", "source_version_id": "string", "content_type": "string", "size_bytes": 0, "file_type": "string", "title": "string", "state": "string", "access_mode": "string", "allow_stream": true, "allow_download": true, "allow_preview": true, "image_retention_seconds": 0, "image_watermark_key": "string", "hls_ready": true, "duration_seconds": 0, "created_at": "string", "updated_at": "string", "renditions": [ { "id": "string", "asset_id": "string", "height": 0, "width": 0, "bandwidth": 0, "state": "string", "job_id": "string", "output_prefix": "string", "size_bytes": 0, "created_at": "string", "updated_at": "string" } ], "asset_url": "string", "player_url": "string" }, "asset_url": "string", "player_url": "string", "access_key": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a managed assetDetails +/api/v1/projects/:projectId/storage/assets/delete
Removes the managed asset identified by assetId and its managed renditions and delivery metadata.
- Deleting an asset affects its managed viewer links; independently uploaded source objects are managed through the bucket object API.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
assetId | 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" } }
GETList managed assetsDetails +/api/v1/projects/:projectId/storage/assets
Lists the project’s managed media assets, including access mode, preview/stream/download permissions, source object and encoding state.
- This is distinct from listing raw objects inside a bucket.
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" }, "url_id": { "type": "string" }, "tenant_id": { "type": "string" }, "bucket_id": { "type": "string" }, "bucket": { "type": "string" }, "object_key": { "type": "string" }, "source_version_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number" }, "file_type": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" }, "access_mode": { "type": "string" }, "allow_stream": { "type": "boolean" }, "allow_download": { "type": "boolean" }, "allow_preview": { "type": "boolean" }, "image_retention_seconds": { "type": "number", "nullable": true }, "image_watermark_key": { "type": "string" }, "hls_ready": { "type": "boolean" }, "duration_seconds": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "asset_id": { "type": "string" }, "height": { "type": "number" }, "width": { "type": "number" }, "bandwidth": { "type": "number" }, "state": { "type": "string" }, "job_id": { "type": "string" }, "output_prefix": { "type": "string" }, "size_bytes": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "asset_id", "height", "width", "bandwidth", "state", "output_prefix", "size_bytes", "created_at", "updated_at" ], "additionalProperties": false } }, "asset_url": { "type": "string" }, "player_url": { "type": "string" }, "has_access_key": { "type": "boolean" } }, "required": [ "id", "url_id", "tenant_id", "bucket_id", "bucket", "object_key", "content_type", "size_bytes", "file_type", "title", "state", "access_mode", "allow_stream", "allow_download", "allow_preview", "hls_ready", "duration_seconds", "created_at", "updated_at", "renditions", "asset_url", "player_url", "has_access_key" ], "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", "url_id": "string", "tenant_id": "string", "bucket_id": "string", "bucket": "string", "object_key": "string", "source_version_id": "string", "content_type": "string", "size_bytes": 0, "file_type": "string", "title": "string", "state": "string", "access_mode": "string", "allow_stream": true, "allow_download": true, "allow_preview": true, "image_retention_seconds": 0, "image_watermark_key": "string", "hls_ready": true, "duration_seconds": 0, "created_at": "string", "updated_at": "string", "renditions": [ { "id": "string", "asset_id": "string", "height": 0, "width": 0, "bandwidth": 0, "state": "string", "job_id": "string", "output_prefix": "string", "size_bytes": 0, "created_at": "string", "updated_at": "string" } ], "asset_url": "string", "player_url": "string", "has_access_key": true } ], "meta": { "requestId": "string", "timestamp": "string" } }
POSTRegenerate a managed asset access keyDetails +/api/v1/projects/:projectId/storage/assets/regenerate-key
Replaces an asset access key and invalidates the previous key.
- Update clients that use the old key. Signed share tokens and public assets follow their own access settings.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
assetId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"assetId": {
"type": "string"
}
},
"required": [
"assetId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string" }, "url_id": { "type": "string" }, "tenant_id": { "type": "string" }, "bucket_id": { "type": "string" }, "bucket": { "type": "string" }, "object_key": { "type": "string" }, "source_version_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number" }, "file_type": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" }, "access_mode": { "type": "string" }, "allow_stream": { "type": "boolean" }, "allow_download": { "type": "boolean" }, "allow_preview": { "type": "boolean" }, "image_retention_seconds": { "type": "number", "nullable": true }, "image_watermark_key": { "type": "string" }, "hls_ready": { "type": "boolean" }, "duration_seconds": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "asset_id": { "type": "string" }, "height": { "type": "number" }, "width": { "type": "number" }, "bandwidth": { "type": "number" }, "state": { "type": "string" }, "job_id": { "type": "string" }, "output_prefix": { "type": "string" }, "size_bytes": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "asset_id", "height", "width", "bandwidth", "state", "output_prefix", "size_bytes", "created_at", "updated_at" ], "additionalProperties": false } }, "asset_url": { "type": "string" }, "player_url": { "type": "string" } }, "required": [ "id", "url_id", "tenant_id", "bucket_id", "bucket", "object_key", "content_type", "size_bytes", "file_type", "title", "state", "access_mode", "allow_stream", "allow_download", "allow_preview", "hls_ready", "duration_seconds", "created_at", "updated_at", "renditions", "asset_url", "player_url" ], "additionalProperties": false }, "access_key": { "type": "string" } }, "required": [ "asset", "access_key" ], "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": { "asset": { "id": "string", "url_id": "string", "tenant_id": "string", "bucket_id": "string", "bucket": "string", "object_key": "string", "source_version_id": "string", "content_type": "string", "size_bytes": 0, "file_type": "string", "title": "string", "state": "string", "access_mode": "string", "allow_stream": true, "allow_download": true, "allow_preview": true, "image_retention_seconds": 0, "image_watermark_key": "string", "hls_ready": true, "duration_seconds": 0, "created_at": "string", "updated_at": "string", "renditions": [ { "id": "string", "asset_id": "string", "height": 0, "width": 0, "bandwidth": 0, "state": "string", "job_id": "string", "output_prefix": "string", "size_bytes": 0, "created_at": "string", "updated_at": "string" } ], "asset_url": "string", "player_url": "string" }, "access_key": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTUpdate managed asset delivery settingsDetails +/api/v1/projects/:projectId/storage/assets/update
Changes a managed asset’s title, public/private access mode, preview/stream/download permissions, image variant retention or watermark settings.
- Only fields accepted by the schema are updated. Disabling stream or download affects future delivery requests.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
assetId | string | Yes |
title | string | No |
accessMode | public | protected | No |
allowStream | boolean | No |
allowDownload | boolean | No |
allowPreview | boolean | No |
imageRetentionSeconds | number | No |
imageWatermarkKey | string | No |
Complete request schema
{
"type": "object",
"properties": {
"assetId": {
"type": "string"
},
"title": {
"type": "string"
},
"accessMode": {
"type": "string",
"enum": [
"public",
"protected"
]
},
"allowStream": {
"type": "boolean"
},
"allowDownload": {
"type": "boolean"
},
"allowPreview": {
"type": "boolean"
},
"imageRetentionSeconds": {
"type": "number"
},
"imageWatermarkKey": {
"type": "string"
}
},
"required": [
"assetId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url_id": { "type": "string" }, "tenant_id": { "type": "string" }, "bucket_id": { "type": "string" }, "bucket": { "type": "string" }, "object_key": { "type": "string" }, "source_version_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number" }, "file_type": { "type": "string" }, "title": { "type": "string" }, "state": { "type": "string" }, "access_mode": { "type": "string" }, "allow_stream": { "type": "boolean" }, "allow_download": { "type": "boolean" }, "allow_preview": { "type": "boolean" }, "image_retention_seconds": { "type": "number", "nullable": true }, "image_watermark_key": { "type": "string" }, "hls_ready": { "type": "boolean" }, "duration_seconds": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "renditions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "asset_id": { "type": "string" }, "height": { "type": "number" }, "width": { "type": "number" }, "bandwidth": { "type": "number" }, "state": { "type": "string" }, "job_id": { "type": "string" }, "output_prefix": { "type": "string" }, "size_bytes": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "asset_id", "height", "width", "bandwidth", "state", "output_prefix", "size_bytes", "created_at", "updated_at" ], "additionalProperties": false } }, "asset_url": { "type": "string" }, "player_url": { "type": "string" } }, "required": [ "id", "url_id", "tenant_id", "bucket_id", "bucket", "object_key", "content_type", "size_bytes", "file_type", "title", "state", "access_mode", "allow_stream", "allow_download", "allow_preview", "hls_ready", "duration_seconds", "created_at", "updated_at", "renditions", "asset_url", "player_url" ], "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", "url_id": "string", "tenant_id": "string", "bucket_id": "string", "bucket": "string", "object_key": "string", "source_version_id": "string", "content_type": "string", "size_bytes": 0, "file_type": "string", "title": "string", "state": "string", "access_mode": "string", "allow_stream": true, "allow_download": true, "allow_preview": true, "image_retention_seconds": 0, "image_watermark_key": "string", "hls_ready": true, "duration_seconds": 0, "created_at": "string", "updated_at": "string", "renditions": [ { "id": "string", "asset_id": "string", "height": 0, "width": 0, "bandwidth": 0, "state": "string", "job_id": "string", "output_prefix": "string", "size_bytes": 0, "created_at": "string", "updated_at": "string" } ], "asset_url": "string", "player_url": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETReveal an asset access keyDetails +/api/v1/projects/:projectId/storage/assets/:assetId/access-key
Return the delivery key of a protected media asset (asset_id, access_key) so its ?key= link can be rebuilt without making the asset public.
- Requires the
media:key:readproject permission, whichmedia:readdoes not include (owners and admins have it). - The response contains a secret; treat it like a credential.
404 STORAGE_ASSET_KEY_NOT_CAPTUREDwhen no key has been stored for the asset; assets of other projects return404.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
assetId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "asset_id": { "type": "string" }, "access_key": { "type": "string" } }, "required": [ "asset_id", "access_key" ], "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": { "asset_id": "string", "access_key": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a generated image variantDetails +/api/v1/projects/:projectId/storage/images/variants/delete
Deletes one generated transform for an asset using both assetId and variantId.
- A later request for the same transform may render it again and count against that day’s distinct-transform allowance.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
assetId | query | Yes | string | — |
variantId | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "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 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList generated image variantsDetails +/api/v1/projects/:projectId/storage/images/variants
Lists cached transforms and their storage metadata for the specified asset.
- Pass
assetIdas a query parameter. Variants are stored as ordinary quota-counted objects under the reserved.hubfly-images/prefix.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
assetId | query | 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" }, "asset_id": { "type": "string" }, "source_version_id": { "type": "string" }, "spec_hash": { "type": "string" }, "spec_json": { "type": "string" }, "bucket_id": { "type": "string" }, "object_key": { "type": "string" }, "size_bytes": { "type": "number" }, "expires_at": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "asset_id", "source_version_id", "spec_hash", "spec_json", "bucket_id", "object_key", "size_bytes", "created_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", "asset_id": "string", "source_version_id": "string", "spec_hash": "string", "spec_json": "string", "bucket_id": "string", "object_key": "string", "size_bytes": 0, "expires_at": "string", "created_at": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }