Box API · Dashboard
Create and inspect Boxes
Check eligibility and pricing, select a regional image, create a Box, and read its state and runtime configuration.
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
- Check eligibility and current regional pricing before creating a Box project.
- List available images and use an imageId from that response. Pick CPU, memory in MiB, root disk in GiB, and SSH keys or generated password access.
- Save the returned Box ID and operation ID. Poll operations until provisioning reaches a terminal state, then inspect initialization separately.
- If you requested a generated password, reveal it once and store it safely.
Create a Box
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/boxes/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"app-01","imageId":"'"$IMAGE_ID"'","vcpus":2,"memoryMib":4096,"rootDiskGib":50,"sshKeys":["ssh-ed25519 AAAA... user@host"]}'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/provisioning/sync | Refresh Box project provisioning |
| GET | /api/v1/pricing/boxes | Read Box prices |
| GET | /api/v1/projects/box-eligibility | Check Box project eligibility |
| POST | /api/v1/projects/:projectId/boxes/create | Create a Box virtual machine |
| GET | /api/v1/projects/:projectId/boxes/images | List available Box images |
| GET | /api/v1/projects/:projectId/boxes | List project Boxes |
| GET | /api/v1/projects/:projectId/boxes/:boxId/initialization | Read guest initialization |
| POST | /api/v1/projects/:projectId/boxes/:boxId/password/reveal | Reveal initial Box password |
| GET | /api/v1/projects/:projectId/boxes/:boxId/runtime | Read runtime configuration |
POSTRefresh Box project provisioningDetails +/api/v1/projects/:projectId/provisioning/sync
Refresh the provisioning state of a Box project's network and return status, phase and progress. When provisioning ends, the project becomes healthy or provisioning_failed; a project that is no longer provisioning returns its current status unchanged.
- Requires the
project:readproject permission (allowed while hibernating). - Non-Box projects return
409 BOX_PROJECT_REQUIRED;409 PROJECT_PROVISIONINGwhen provisioning has not started.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | 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": { "status": { "type": "string" }, "phase": { "type": "string", "nullable": true }, "progress": { "type": "number", "nullable": true } }, "required": [ "status", "phase", "progress" ], "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": { "status": "string", "phase": "string", "progress": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead Box pricesDetails +/api/v1/pricing/boxes
Return current CPU, memory, root-disk and related Box pricing. Use this before showing or confirming an estimated cost.
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "hoursPerMonth": { "const": 730, "type": "number" }, "vCpuPerHour": { "type": "number" }, "ramGibPerHour": { "type": "number" }, "storageGibPerHour": { "type": "number" }, "egressGib": { "const": 0, "type": "number" }, "ingressGib": { "const": 0, "type": "number" }, "portMapping": { "const": 0, "type": "number" } }, "required": [ "currency", "hoursPerMonth", "vCpuPerHour", "ramGibPerHour", "storageGibPerHour", "egressGib", "ingressGib", "portMapping" ], "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": { "currency": "string", "hoursPerMonth": 0, "vCpuPerHour": 0, "ramGibPerHour": 0, "storageGibPerHour": 0, "egressGib": 0, "ingressGib": 0, "portMapping": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETCheck Box project eligibilityDetails +/api/v1/projects/box-eligibility
Check whether the owning account may create a Box project, including relevant balance and product conditions.
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "minimumDepositUsd": { "type": "string" } }, "required": [ "eligible", "minimumDepositUsd" ], "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": { "eligible": true, "minimumDepositUsd": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTCreate a Box virtual machineDetails +/api/v1/projects/:projectId/boxes/create
Create a VM from a regional image with CPU, MiB RAM and GiB root disk. Optional SSH keys, generated password and cloud-init configure first boot. Returns Box and operation IDs before completion.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
name | string | Yes |
imageId | string | Yes |
vcpus | number | Yes |
memoryMib | number | Yes |
rootDiskGib | number | Yes |
username | string | No |
sshKeys | string[] | No |
generatePassword | boolean | No |
cloudConfigYaml | string | No |
Complete request schema
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"imageId": {
"type": "string"
},
"vcpus": {
"type": "number"
},
"memoryMib": {
"type": "number"
},
"rootDiskGib": {
"type": "number"
},
"username": {
"type": "string"
},
"sshKeys": {
"type": "array",
"items": {
"type": "string"
}
},
"generatePassword": {
"type": "boolean"
},
"cloudConfigYaml": {
"type": "string"
}
},
"required": [
"name",
"imageId",
"vcpus",
"memoryMib",
"rootDiskGib"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "operationId": { "type": "string" }, "passwordRevealAvailable": { "type": "boolean" } }, "required": [ "id", "operationId", "passwordRevealAvailable" ], "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", "operationId": "string", "passwordRevealAvailable": true }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList available Box imagesDetails +/api/v1/projects/:projectId/boxes/images
Read images offered in this project region. Use one returned imageId when creating a Box.
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" }, "name": { "type": "string" }, "description": { "type": "string" }, "defaultUser": { "type": "string" }, "minimumDiskGib": { "type": "number" }, "sourceKind": { "type": "string" }, "guestOs": { "type": "string" } }, "required": [ "id", "name", "description", "defaultUser", "minimumDiskGib", "sourceKind", "guestOs" ], "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", "name": "string", "description": "string", "defaultUser": "string", "minimumDiskGib": 0, "sourceKind": "string", "guestOs": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
GETList project BoxesDetails +/api/v1/projects/:projectId/boxes
Read Box IDs, lifecycle state, configured resources and current operation for this project.
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" }, "name": { "type": "string" }, "status": { "type": "string" }, "imageId": { "type": "string" }, "vcpus": { "type": "number" }, "memoryMib": { "type": "number" }, "rootDiskGib": { "type": "number" }, "initializationStatus": { "type": "string" }, "activeOperationId": { "type": "string", "nullable": true }, "privateIpv4": { "type": "string", "nullable": true } }, "required": [ "id", "name", "status", "imageId", "vcpus", "memoryMib", "rootDiskGib", "initializationStatus", "activeOperationId", "privateIpv4" ], "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", "name": "string", "status": "string", "imageId": "string", "vcpus": 0, "memoryMib": 0, "rootDiskGib": 0, "initializationStatus": "string", "activeOperationId": "string", "privateIpv4": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
GETRead guest initializationDetails +/api/v1/projects/:projectId/boxes/:boxId/initialization
Read cloud-init and guest readiness state separately from VM power state; running does not imply successful initialization.
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": { "state": { "type": "string" }, "username": { "type": "string" }, "sshKeyFingerprints": { "type": "array", "items": { "type": "string" } }, "completedAt": { "type": "string", "nullable": true } }, "required": [ "state", "username", "sshKeyFingerprints", "completedAt" ], "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": { "state": "string", "username": "string", "sshKeyFingerprints": [ "string" ], "completedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTReveal initial Box passwordDetails +/api/v1/projects/:projectId/boxes/:boxId/password/reveal
Reveal the generated initial password when available. Save it immediately; plaintext is not returned by Box listing.
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": { "password": { "type": "string" } }, "required": [ "password" ], "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": { "password": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead runtime configurationDetails +/api/v1/projects/:projectId/boxes/:boxId/runtime
Read current, desired and next-boot CPU and RAM and disk configuration while resize operations settle.
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": { "status": { "type": "string" }, "vcpus": { "type": "number" }, "memoryMib": { "type": "number" }, "rootDiskGib": { "type": "number" }, "desiredConfiguration": { "type": "object", "properties": { "vcpus": { "type": "number" }, "memoryMib": { "type": "number" } }, "required": [ "vcpus", "memoryMib" ], "additionalProperties": false }, "effectiveNow": { "type": "object", "properties": { "vcpus": { "type": "number", "nullable": true }, "memoryMib": { "type": "number", "nullable": true } }, "required": [ "vcpus", "memoryMib" ], "additionalProperties": false }, "effectiveAfterRestart": { "type": "object", "properties": { "vcpus": { "type": "number", "nullable": true }, "memoryMib": { "type": "number", "nullable": true } }, "required": [ "vcpus", "memoryMib" ], "additionalProperties": false }, "capabilityState": { "type": "string" }, "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "runtimeId": { "type": "string", "nullable": true }, "name": { "type": "string" }, "runtimeName": { "type": "string" }, "imageId": { "type": "string" }, "initializationStatus": { "type": "string" }, "activeOperationId": { "type": "string", "nullable": true }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "deletedAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "status", "vcpus", "memoryMib", "rootDiskGib", "desiredConfiguration", "effectiveNow", "effectiveAfterRestart", "capabilityState", "createdAt", "updatedAt", "id", "projectId", "runtimeId", "name", "runtimeName", "imageId", "initializationStatus", "activeOperationId", "labels", "deletedAt" ], "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": { "status": "string", "vcpus": 0, "memoryMib": 0, "rootDiskGib": 0, "desiredConfiguration": { "vcpus": 0, "memoryMib": 0 }, "effectiveNow": { "vcpus": 0, "memoryMib": 0 }, "effectiveAfterRestart": { "vcpus": 0, "memoryMib": 0 }, "capabilityState": "string", "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "runtimeId": "string", "name": "string", "runtimeName": "string", "imageId": "string", "initializationStatus": "string", "activeOperationId": "string", "labels": null, "deletedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }