Box API · Dashboard
Power, resize, ops & metrics
Control power, change capacity, open console sessions, follow asynchronous operations, and inspect metrics.
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
- Submit a power or resize action and keep its operation ID.
- Read the project operation list; an accepted response does not mean the action finished.
- Use metric history to diagnose load. Console sessions are short lived and authorized per Box.
- If deletion ends partial, call finish-cleanup on the operation before considering it deleted.
Request a graceful reboot
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/boxes/$BOX_ID/control" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"reboot"}'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 (10)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/projects/:projectId/box-operations | List Box operations |
| POST | /api/v1/projects/:projectId/box-operations/:operationId/cancel | Request operation cancellation |
| POST | /api/v1/projects/:projectId/box-operations/:operationId/finish-cleanup | Resume partial cleanup |
| GET | /api/v1/projects/:projectId/boxes/metrics | Read project Box metrics |
| POST | /api/v1/projects/:projectId/boxes/:boxId/console/session | Open a Box console session |
| POST | /api/v1/projects/:projectId/boxes/:boxId/control | Control Box power |
| DELETE | /api/v1/projects/:projectId/boxes/:boxId/delete | Delete a Box |
| GET | /api/v1/projects/:projectId/boxes/:boxId/metrics/history | Read Box metric history |
| GET | /api/v1/projects/:projectId/boxes/:boxId/metrics | Read current Box metrics |
| POST | /api/v1/projects/:projectId/boxes/:boxId/resize | Resize a Box |
GETList Box operationsDetails +/api/v1/projects/:projectId/box-operations
List recent or cursor-paginated Box host operations for this project. Follow an operation ID until its terminal status is observed.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
recent | query | No | boolean | — |
before | query | No | string | — |
beforeId | query | No | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "remediationCode": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "boxId": { "type": "string", "nullable": true }, "runtimeOperationId": { "type": "string", "nullable": true }, "kind": { "type": "string" }, "status": { "type": "string" }, "phase": { "type": "string" }, "progress": { "type": "number" }, "cancelable": { "type": "boolean" }, "errorCode": { "type": "string", "nullable": true }, "retryCount": { "type": "number" }, "finishedAt": { "type": "string", "description": "Date string", "nullable": true }, "reconciledAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "remediationCode", "createdAt", "updatedAt", "id", "projectId", "boxId", "runtimeOperationId", "kind", "status", "phase", "progress", "cancelable", "errorCode", "retryCount", "finishedAt", "reconciledAt" ], "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": [ { "remediationCode": "string", "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "boxId": "string", "runtimeOperationId": "string", "kind": "string", "status": "string", "phase": "string", "progress": 0, "cancelable": true, "errorCode": "string", "retryCount": 0, "finishedAt": "string", "reconciledAt": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
POSTRequest operation cancellationDetails +/api/v1/projects/:projectId/box-operations/:operationId/cancel
Request cancellation for a pending Box operation. Work already applied may still need reconciliation or cleanup.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
operationId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "phase": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string", "nullable": true }, "cancelable": { "type": "boolean" }, "remediationCode": { "type": "string", "nullable": true } }, "required": [ "id", "status", "phase", "progress", "errorCode", "cancelable", "remediationCode" ], "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", "status": "string", "phase": "string", "progress": 0, "errorCode": "string", "cancelable": true, "remediationCode": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTResume partial cleanupDetails +/api/v1/projects/:projectId/box-operations/:operationId/finish-cleanup
Resume the checkpointed cleanup for an operation that ended partial, especially a partial Box deletion.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
operationId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "phase": { "type": "string" }, "progress": { "type": "number" }, "errorCode": { "type": "string", "nullable": true }, "cancelable": { "type": "boolean" }, "remediationCode": { "type": "string", "nullable": true } }, "required": [ "id", "status", "phase", "progress", "errorCode", "cancelable", "remediationCode" ], "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", "status": "string", "phase": "string", "progress": 0, "errorCode": "string", "cancelable": true, "remediationCode": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead project Box metricsDetails +/api/v1/projects/:projectId/boxes/metrics
Read current metrics across the project Boxes for a summary or fleet view.
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": "object", "properties": { "sampledAt": { "type": "number" }, "status": { "type": "string" }, "boxes": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" } ], "nullable": true } } } }, "required": [ "sampledAt", "status", "boxes" ], "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": { "sampledAt": 0, "status": "string", "boxes": null }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTOpen a Box console sessionDetails +/api/v1/projects/:projectId/boxes/:boxId/console/session
Request an authorized, short-lived browser console session for this Box. Treat the session capability as a secret.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|
Complete request schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "connectUrl": { "type": "string" }, "websocketProtocols": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string" } ] } }, "expiresAt": { "type": "string" } }, "required": [ "connectUrl", "websocketProtocols", "expiresAt" ], "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": { "connectUrl": "string", "websocketProtocols": [ null ], "expiresAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTControl Box powerDetails +/api/v1/projects/:projectId/boxes/:boxId/control
Request start, graceful shutdown, graceful reboot, or force stop. Graceful actions do not automatically become forceful.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
action | start | shutdown | reboot | force-stop | Yes |
Complete request schema
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"start",
"shutdown",
"reboot",
"force-stop"
]
}
},
"required": [
"action"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operationId", "status" ], "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": { "operationId": "string", "status": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDelete a BoxDetails +/api/v1/projects/:projectId/boxes/:boxId/delete
Start checkpointed Box deletion. Preserve needed data first and follow its operation; partial cleanup may need finish-cleanup.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" } }, "required": [ "operationId" ], "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": { "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead Box metric historyDetails +/api/v1/projects/:projectId/boxes/:boxId/metrics/history
Read per-Box historical metrics for the requested range to investigate load and capacity trends.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
range | query | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "range": { "type": "string", "enum": [ "7d", "1h", "6h", "24h" ] }, "from": { "type": "number" }, "to": { "type": "number" }, "points": { "type": "array", "items": { "type": "object", "properties": { "sampled_at": { "type": "number" }, "metrics": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" } ], "nullable": true } } }, "required": [ "sampled_at", "metrics" ], "additionalProperties": false } } }, "required": [ "range", "from", "to", "points" ], "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": { "range": "7d", "from": 0, "to": 0, "points": [ { "sampled_at": 0, "metrics": null } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead current Box metricsDetails +/api/v1/projects/:projectId/boxes/:boxId/metrics
Read current CPU, memory, disk and network observations. Guest-used RAM exists only when guest memory stats are available.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "sampledAt": { "type": "number" }, "status": { "type": "string" }, "metrics": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "const": false, "type": "boolean" }, { "const": true, "type": "boolean" } ], "nullable": true } } }, "required": [ "sampledAt", "status", "metrics" ], "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": { "sampledAt": 0, "status": "string", "metrics": null }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTResize a BoxDetails +/api/v1/projects/:projectId/boxes/:boxId/resize
Request CPU, MiB RAM or root disk growth with live, restart or next-boot behavior. Live growth depends on reserved topology; reductions require restart.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
vcpus | number | No |
memoryMib | number | No |
rootDiskGib | number | No |
mode | try_live_then_restart | restart_now | next_boot | No |
Complete request schema
{
"type": "object",
"properties": {
"vcpus": {
"type": "number"
},
"memoryMib": {
"type": "number"
},
"rootDiskGib": {
"type": "number"
},
"mode": {
"type": "string",
"enum": [
"try_live_then_restart",
"restart_now",
"next_boot"
]
}
},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operationId", "status" ], "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": { "operationId": "string", "status": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }