Hubfly spaceDocs
Console

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

  1. Check eligibility and current regional pricing before creating a Box project.
  2. 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.
  3. Save the returned Box ID and operation ID. Poll operations until provisioning reaches a terminal state, then inspect initialization separately.
  4. If you requested a generated password, reveal it once and store it safely.

Create a Box

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

Open interactive API explorer
MethodPathPurpose
POST/api/v1/projects/:projectId/provisioning/syncRefresh Box project provisioning
GET/api/v1/pricing/boxesRead Box prices
GET/api/v1/projects/box-eligibilityCheck Box project eligibility
POST/api/v1/projects/:projectId/boxes/createCreate a Box virtual machine
GET/api/v1/projects/:projectId/boxes/imagesList available Box images
GET/api/v1/projects/:projectId/boxesList project Boxes
GET/api/v1/projects/:projectId/boxes/:boxId/initializationRead guest initialization
POST/api/v1/projects/:projectId/boxes/:boxId/password/revealReveal initial Box password
GET/api/v1/projects/:projectId/boxes/:boxId/runtimeRead 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:read project permission (allowed while hibernating).
  • Non-Box projects return 409 BOX_PROJECT_REQUIRED; 409 PROJECT_PROVISIONING when provisioning has not started.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—

JSON request body

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

JSON request body

FieldType / allowed valuesRequired
namestringYes
imageIdstringYes
vcpusnumberYes
memoryMibnumberYes
rootDiskGibnumberYes
usernamestringNo
sshKeysstring[]No
generatePasswordbooleanNo
cloudConfigYamlstringNo
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 response
    Response 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
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"
              },
              "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
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"
              },
              "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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
boxIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
boxIdpathYesstring—

JSON request body

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

Related guides

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