List Nodes GET /api/nodes Authorization : Bearer {token}
List all nodes in the system. Admin only.
Authentication Requires admin role.
Response Array of node objects HTTP | HTTPS | HTTPS_PROXY
Total memory in bytes (BigInt as string)
Total disk in bytes (BigInt as string)
File upload limit in bytes
Whether node is currently online
[ { "id" : "node-1" , "displayName" : "US East 1" , "host" : "node1.example.com" , "port" : 8080 , "protocol" : "HTTPS" , "sftpPort" : 2022 , "memoryLimit" : "34359738368" , "diskLimit" : "107374182400" , "cpuLimit" : 8 , "uploadLimit" : "104857600" , "isOnline" : true , "lastHeartbeat" : "2024-01-15T12:00:00Z" , "heartbeatLatency" : 45 , "location" : { "id" : "loc-1" , "name" : "New York" }, "_count" : { "servers" : 12 , "allocations" : 100 } } ]
Get Node GET /api/nodes/{id} Authorization : Bearer {token}
Get detailed information about a specific node.
Path Parameters Authentication Requires admin role.
Response Returns a detailed node object including allocations and servers.
{ "id" : "node-1" , "displayName" : "US East 1" , "host" : "node1.example.com" , "port" : 8080 , "protocol" : "HTTPS" , "sftpPort" : 2022 , "memoryLimit" : "34359738368" , "diskLimit" : "107374182400" , "cpuLimit" : 8 , "uploadLimit" : "104857600" , "isOnline" : true , "location" : { "id" : "loc-1" , "name" : "New York" , "country" : "US" , "city" : "New York" }, "allocations" : [ { "id" : "alloc-1" , "ip" : "0.0.0.0" , "port" : 25565 , "assigned" : true } ], "servers" : [ { "id" : "server-1" , "name" : "Minecraft Server" , "status" : "RUNNING" } ] }
Create Node POST /api/nodes Authorization : Bearer {token} Content-Type : application/json
Create a new node. Returns authentication token ONCE - store it securely.
Authentication Requires admin role.
Request Body Human-readable node name (1-100 characters)
HTTP | HTTPS | HTTPS_PROXY
uploadLimit
number
default: "104857600"
File upload limit in bytes (default 100MB)
{ "displayName" : "US East 1" , "host" : "node1.example.com" , "port" : 8080 , "protocol" : "HTTPS" , "sftpPort" : 2022 , "memoryLimit" : 34359738368 , "diskLimit" : 107374182400 , "cpuLimit" : 8 , "uploadLimit" : 104857600 , "locationId" : "loc-1" }
Response Returns the created node and authentication credentials.
Node UUID (use as token_id in daemon config)
Authentication token (use in daemon config.toml) - SHOWN ONLY ONCE
Important warning about storing credentials
{ "node" : { "id" : "node-1" , "displayName" : "US East 1" , "host" : "node1.example.com" , "port" : 8080 }, "token_id" : "node-1" , "token" : "48-character-random-token-abc123..." , "message" : "Store token_id and token securely for your daemon config.toml. They will not be shown again." }
Errors
400 - Validation failed404 - Location not found
Update Node PATCH /api/nodes/{id} Authorization : Bearer {token} Content-Type : application/json
Update node configuration.
Path Parameters Request Body All fields are optional.
HTTP | HTTPS | HTTPS_PROXY
Response Returns the updated node object.
Errors Delete Node DELETE /api/nodes/{id} Authorization : Bearer {token}
Delete a node. Cannot delete nodes with active servers.
Path Parameters Response Errors
400 - Node has associated servers404 - Node not found
Regenerate Token POST /api/nodes/:id/regenerate-token
POST /api/nodes/{id}/regenerate-token Authorization : Bearer {token}
Regenerate node authentication token. Forces node offline until reconfigured.
Path Parameters Response New authentication token - SHOWN ONLY ONCE
Warning about storing credentials
{ "token_id" : "node-1" , "token" : "new-48-character-random-token-xyz789..." , "message" : "Store token_id and token securely for your daemon config.toml. They will not be shown again." }
Allocation Management Add Single Allocation POST /api/nodes/:id/allocations
POST /api/nodes/{id}/allocations Authorization : Bearer {token} Content-Type : application/json
Add a single network allocation to the node.
Request Body IP address (IPv4 or IPv6)
Optional alias for the allocation
{ "ip" : "0.0.0.0" , "port" : 25565 , "alias" : "Minecraft Main" }
Response Returns the created allocation object with status 201.
Errors
404 - Node not found409 - Allocation already exists
Add Allocation Range POST /api/nodes/:id/allocations/range
POST /api/nodes/{id}/allocations/range Authorization : Bearer {token} Content-Type : application/json
Add a range of port allocations to the node.
Request Body Ending port (1-65535, must be greater than or equal to startPort)
{ "ip" : "0.0.0.0" , "startPort" : 25565 , "endPort" : 25665 }
Response Delete Allocation DELETE /api/nodes/:id/allocations/:allocationId
DELETE /api/nodes/{id}/allocations/{allocationId} Authorization : Bearer {token}
Delete an allocation. Cannot delete assigned allocations.
Path Parameters Response Errors
400 - Cannot delete assigned allocation404 - Allocation not found
Get Node Stats GET /api/nodes/{id}/stats Authorization : Bearer {token}
Get real-time statistics from the node daemon.
Path Parameters Response Returns node statistics from daemon.
{ "cpu_usage" : 45.2 , "memory_usage" : 17179869184 , "memory_total" : 34359738368 , "disk_usage" : 53687091200 , "disk_total" : 107374182400 , "network_rx" : 1024000 , "network_tx" : 2048000 , "uptime" : 86400 }
Errors
400 - Node is offline404 - Node not found500 - Failed to connect to daemon
Daemon Endpoints These endpoints are called by node daemons for authentication and status reporting.
Handshake POST /api/nodes/handshake
POST /api/nodes/handshake Authorization : Bearer {token_id}.{token}
Daemon calls this on startup to verify connection and get configuration.
Authentication Requires daemon authentication with Bearer token in format {token_id}.{token}.
Response Returns node configuration and list of servers.
Heartbeat POST /api/nodes/heartbeat
POST /api/nodes/heartbeat Authorization : Bearer {token_id}.{token} Content-Type : application/json
Daemon sends periodic heartbeats to maintain online status.
Request Body Optional: measured latency from previous heartbeat RTT
Response { "acknowledged" : true , "nodeId" : "node-1" , "timestamp" : "2024-01-15T12:00:00Z" }
Report Server Status POST /api/nodes/servers/:serverId/status
POST /api/nodes/servers/{serverId}/status Authorization : Bearer {token_id}.{token} Content-Type : application/json
Daemon reports server status changes.
Request Body Response