Box API · Dashboard
NICs, ports, IPs & HTTP domains
Manage interfaces, expose TCP or UDP ports, purchase a static IP, and publish HTTP services.
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
- List NICs to find the interface ID that will receive traffic.
- For raw TCP or UDP, create a mapping for the guest port; the service assigns the public host port.
- For HTTP, add a subdomain and target port, then use the returned hostname and URL.
- A static IP is a separately purchased project resource and must be attached to a NIC.
Publish a guest TCP port
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/box-port-mappings/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"boxId":"'"$BOX_ID"'","nicId":"'"$NIC_ID"'","protocol":"tcp","guestPort":22}'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 (14)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
POSTPublish a guest portDetails +/api/v1/projects/:projectId/box-port-mappings/create
Create a TCP or UDP mapping from an assigned public host port to the selected NIC and guest port; follow the returned operation.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
boxId | string | Yes |
nicId | string | Yes |
protocol | tcp | udp | Yes |
guestPort | number | Yes |
guestPortEnd | number | No |
Complete request schema
{
"type": "object",
"properties": {
"boxId": {
"type": "string"
},
"nicId": {
"type": "string"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
]
},
"guestPort": {
"type": "number"
},
"guestPortEnd": {
"type": "number"
}
},
"required": [
"boxId",
"nicId",
"protocol",
"guestPort"
],
"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" } }, "required": [ "id", "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": { "id": "string", "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList published portsDetails +/api/v1/projects/:projectId/box-port-mappings
Read all project Box port mappings and their assigned public endpoints and states.
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": { "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "boxId": { "type": "string" }, "nicId": { "type": "string" }, "runtimeId": { "type": "string", "nullable": true }, "protocol": { "type": "string" }, "bindIp": { "type": "string" }, "hostPort": { "type": "number" }, "guestPort": { "type": "number" }, "hostPortEnd": { "type": "number", "nullable": true }, "guestPortEnd": { "type": "number", "nullable": true }, "status": { "type": "string" }, "deletedAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "createdAt", "updatedAt", "id", "projectId", "boxId", "nicId", "runtimeId", "protocol", "bindIp", "hostPort", "guestPort", "hostPortEnd", "guestPortEnd", "status", "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": [ { "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "boxId": "string", "nicId": "string", "runtimeId": "string", "protocol": "string", "bindIp": "string", "hostPort": 0, "guestPort": 0, "hostPortEnd": 0, "guestPortEnd": 0, "status": "string", "deletedAt": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
DELETERemove a port mappingDetails +/api/v1/projects/:projectId/box-port-mappings/:mappingId/delete
Stop publishing this mapped guest port. Follow the removal operation before assuming traffic is blocked.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
mappingId | 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" } }
POSTAttach a static IPDetails +/api/v1/projects/:projectId/box-static-ip/attach
Assign the purchased regional static IP to a selected Box NIC. This is separate from purchasing the IP.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
boxId | string | Yes |
nicId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"boxId": {
"type": "string"
},
"nicId": {
"type": "string"
}
},
"required": [
"boxId",
"nicId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "oneOf": [ { "type": "object", "properties": { "operationId": { "const": null }, "alreadyAttached": { "type": "boolean" } }, "required": [ "operationId", "alreadyAttached" ], "additionalProperties": false }, { "type": "object", "properties": { "operationId": { "type": "string" }, "alreadyAttached": { "type": "boolean" } }, "required": [ "operationId", "alreadyAttached" ], "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": null, "meta": { "requestId": "string", "timestamp": "string" } }
POSTDetach a static IPDetails +/api/v1/projects/:projectId/box-static-ip/detach
Remove the static IP attachment from its current NIC while retaining the purchased project resource.
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": { "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 static IP stateDetails +/api/v1/projects/:projectId/box-static-ip
Read purchased static IP inventory, pending changes, and current Box/NIC assignment.
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": { "address": { "type": "object", "properties": { "id": { "type": "string" }, "regionId": { "type": "string" }, "address": { "type": "string" }, "status": { "type": "string" }, "attachedProjectId": { "type": "string", "nullable": true }, "attachedBoxId": { "type": "string", "nullable": true }, "attachedNicId": { "type": "string", "nullable": true }, "pendingProjectId": { "type": "string", "nullable": true }, "pendingBoxId": { "type": "string", "nullable": true }, "pendingNicId": { "type": "string", "nullable": true }, "activeOperationId": { "type": "string", "nullable": true }, "lastErrorCode": { "type": "string", "nullable": true }, "purchasedAt": { "type": "string", "nullable": true } }, "required": [ "id", "regionId", "address", "status", "attachedProjectId", "attachedBoxId", "attachedNicId", "pendingProjectId", "pendingBoxId", "pendingNicId", "activeOperationId", "lastErrorCode", "purchasedAt" ], "additionalProperties": false, "nullable": true }, "priceMicroUsd": { "type": "string" }, "priceUsd": { "type": "string" } }, "required": [ "address", "priceMicroUsd", "priceUsd" ], "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": { "address": { "id": "string", "regionId": "string", "address": "string", "status": "string", "attachedProjectId": "string", "attachedBoxId": "string", "attachedNicId": "string", "pendingProjectId": "string", "pendingBoxId": "string", "pendingNicId": "string", "activeOperationId": "string", "lastErrorCode": "string", "purchasedAt": "string" }, "priceMicroUsd": "string", "priceUsd": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTPurchase a static IPDetails +/api/v1/projects/:projectId/box-static-ip/purchase
Confirm purchase of a regional static IP for the project and request assignment to the selected Box NIC.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
boxId | string | Yes |
nicId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"boxId": {
"type": "string"
},
"nicId": {
"type": "string"
}
},
"required": [
"boxId",
"nicId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "oneOf": [ { "type": "object", "properties": { "attachmentQueued": { "type": "boolean" }, "operationId": { "const": null }, "alreadyAttached": { "type": "boolean" }, "address": { "type": "object", "properties": { "id": { "type": "string" }, "regionId": { "type": "string" }, "address": { "type": "string" }, "status": { "type": "string" }, "attachedProjectId": { "type": "string", "nullable": true }, "attachedBoxId": { "type": "string", "nullable": true }, "attachedNicId": { "type": "string", "nullable": true }, "pendingProjectId": { "type": "string", "nullable": true }, "pendingBoxId": { "type": "string", "nullable": true }, "pendingNicId": { "type": "string", "nullable": true }, "activeOperationId": { "type": "string", "nullable": true }, "lastErrorCode": { "type": "string", "nullable": true }, "purchasedAt": { "type": "string", "nullable": true } }, "required": [ "id", "regionId", "address", "status", "attachedProjectId", "attachedBoxId", "attachedNicId", "pendingProjectId", "pendingBoxId", "pendingNicId", "activeOperationId", "lastErrorCode", "purchasedAt" ], "additionalProperties": false } }, "required": [ "attachmentQueued", "operationId", "alreadyAttached", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "attachmentQueued": { "type": "boolean" }, "operationId": { "type": "string" }, "alreadyAttached": { "type": "boolean" }, "address": { "type": "object", "properties": { "id": { "type": "string" }, "regionId": { "type": "string" }, "address": { "type": "string" }, "status": { "type": "string" }, "attachedProjectId": { "type": "string", "nullable": true }, "attachedBoxId": { "type": "string", "nullable": true }, "attachedNicId": { "type": "string", "nullable": true }, "pendingProjectId": { "type": "string", "nullable": true }, "pendingBoxId": { "type": "string", "nullable": true }, "pendingNicId": { "type": "string", "nullable": true }, "activeOperationId": { "type": "string", "nullable": true }, "lastErrorCode": { "type": "string", "nullable": true }, "purchasedAt": { "type": "string", "nullable": true } }, "required": [ "id", "regionId", "address", "status", "attachedProjectId", "attachedBoxId", "attachedNicId", "pendingProjectId", "pendingBoxId", "pendingNicId", "activeOperationId", "lastErrorCode", "purchasedAt" ], "additionalProperties": false } }, "required": [ "attachmentQueued", "operationId", "alreadyAttached", "address" ], "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": null, "meta": { "requestId": "string", "timestamp": "string" } }
POSTPublish an HTTP domainDetails +/api/v1/projects/:projectId/boxes/:boxId/http-domains/create
Create an HTTP hostname pointing at a guest targetPort. The response includes its hostname, URL and route status.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
subdomain | string | Yes |
targetPort | number | Yes |
Complete request schema
{
"type": "object",
"properties": {
"subdomain": {
"type": "string"
},
"targetPort": {
"type": "number"
}
},
"required": [
"subdomain",
"targetPort"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "boxId": { "type": "string" }, "subdomain": { "type": "string" }, "hostname": { "type": "string" }, "targetPort": { "type": "number" }, "status": { "type": "string" }, "url": { "type": "string" }, "proxySiteId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "boxId", "subdomain", "hostname", "targetPort", "status", "url", "proxySiteId", "createdAt" ], "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", "boxId": "string", "subdomain": "string", "hostname": "string", "targetPort": 0, "status": "string", "url": "string", "proxySiteId": "string", "createdAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList Box HTTP domainsDetails +/api/v1/projects/:projectId/boxes/:boxId/http-domains
Read HTTP hostnames, target ports and status for this Box.
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": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "boxId": { "type": "string" }, "subdomain": { "type": "string" }, "hostname": { "type": "string" }, "targetPort": { "type": "number" }, "status": { "type": "string" }, "url": { "type": "string" }, "proxySiteId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "boxId", "subdomain", "hostname", "targetPort", "status", "url", "proxySiteId", "createdAt" ], "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", "boxId": "string", "subdomain": "string", "hostname": "string", "targetPort": 0, "status": "string", "url": "string", "proxySiteId": "string", "createdAt": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
DELETERemove an HTTP domainDetails +/api/v1/projects/:projectId/boxes/:boxId/http-domains/:domainId/delete
Remove the selected Box HTTP hostname and its proxy route.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
domainId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "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": { "success": true }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTRetarget an HTTP domainDetails +/api/v1/projects/:projectId/boxes/:boxId/http-domains/:domainId
Change an existing hostname to a new guest targetPort.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
domainId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
targetPort | number | Yes |
Complete request schema
{
"type": "object",
"properties": {
"targetPort": {
"type": "number"
}
},
"required": [
"targetPort"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "boxId": { "type": "string" }, "subdomain": { "type": "string" }, "hostname": { "type": "string" }, "targetPort": { "type": "number" }, "status": { "type": "string" }, "url": { "type": "string" }, "proxySiteId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "boxId", "subdomain", "hostname", "targetPort", "status", "url", "proxySiteId", "createdAt" ], "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", "boxId": "string", "subdomain": "string", "hostname": "string", "targetPort": 0, "status": "string", "url": "string", "proxySiteId": "string", "createdAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTAttach a Box NICDetails +/api/v1/projects/:projectId/boxes/:boxId/nics/attach
Request another managed network interface for this Box and follow its operation.
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": { "id": { "type": "string" }, "operationId": { "type": "string" } }, "required": [ "id", "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": { "id": "string", "operationId": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList Box NICsDetails +/api/v1/projects/:projectId/boxes/:boxId/nics
Read NIC IDs, addresses and states before adding mappings, static IPs or NIC firewall policies.
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": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Date string" }, "updatedAt": { "type": "string", "description": "Date string" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "boxId": { "type": "string" }, "runtimeId": { "type": "string" }, "mac": { "type": "string", "nullable": true }, "ipv4": { "type": "string", "nullable": true }, "status": { "type": "string" }, "deletedAt": { "type": "string", "description": "Date string", "nullable": true } }, "required": [ "createdAt", "updatedAt", "id", "projectId", "boxId", "runtimeId", "mac", "ipv4", "status", "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": [ { "createdAt": "string", "updatedAt": "string", "id": "string", "projectId": "string", "boxId": "string", "runtimeId": "string", "mac": "string", "ipv4": "string", "status": "string", "deletedAt": "string" } ], "meta": { "requestId": "string", "timestamp": "string" } }
POSTRemove a Box NICDetails +/api/v1/projects/:projectId/boxes/:boxId/nics/:nicId/delete
Request removal of a NIC. Check routes and static IP assignments that depend on it.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
boxId | path | Yes | string | — |
nicId | 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": { "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" } }