Hubfly spaceDocs
Console

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

  1. Submit a power or resize action and keep its operation ID.
  2. Read the project operation list; an accepted response does not mean the action finished.
  3. Use metric history to diagnose load. Console sessions are short lived and authorized per Box.
  4. If deletion ends partial, call finish-cleanup on the operation before considering it deleted.

Request a graceful reboot

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

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

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": {
            "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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
operationIdpathYesstring—

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": {
            "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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
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": {
            "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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
boxIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
actionstart | shutdown | reboot | force-stopYes
Complete request schema
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "start",
        "shutdown",
        "reboot",
        "force-stop"
      ]
    }
  },
  "required": [
    "action"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
boxIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
boxIdpathYesstring—
rangequeryYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
boxIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
boxIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
vcpusnumberNo
memoryMibnumberNo
rootDiskGibnumberNo
modetry_live_then_restart | restart_now | next_bootNo
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 response
    Response 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"
      }
    }

Related guides

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