Cluster API
Discover the nodes in the Hazelcast cluster and inspect each node's instances and resource usage. A remote command dispatch endpoint is defined for running console commands on other nodes.
Every node in a Universe deployment is a member of one Hazelcast cluster. The cluster endpoints, served by the Master, enumerate those members and report the instances and resources each one owns. They draw on the same distributed state the Master uses to schedule instances.
All cluster endpoints require a token with ALL permission.
List cluster nodes
GET /api/cluster/nodesReturns every node in the cluster with its address, master flag, and current resource usage.
| Field | Type | Description |
|---|---|---|
nodeId | string | Unique node identifier. |
address | string | Node address advertised to the cluster. |
master | boolean | Whether this node runs the REST API and owns authoritative state. |
resources | NodeResources | usedRamMB and usedCpu currently in use on the node. |
curl http://<master>:7000/api/cluster/nodes \
-H "Authorization: Bearer YOUR_TOKEN"[
{
"nodeId": "node-1",
"address": "127.0.0.1",
"master": true,
"resources": { "usedRamMB": 4096, "usedCpu": 200 }
},
{
"nodeId": "node-2",
"address": "10.0.0.12",
"master": false,
"resources": { "usedRamMB": 2048, "usedCpu": 100 }
}
]Get a node
GET /api/cluster/nodes/{id}Returns detailed information about a single node, including the full list of instances it hosts and its resource usage.
| Parameter | In | Description |
|---|---|---|
id | path | The node ID. Required. |
curl http://<master>:7000/api/cluster/nodes/node-2 \
-H "Authorization: Bearer YOUR_TOKEN"{
"nodeId": "node-2",
"address": "10.0.0.12",
"master": false,
"instances": [
{
"id": "a1b2c3",
"configurationName": "lobby",
"wrapperNodeId": "node-2",
"hostAddress": "10.0.0.12",
"allocatedPort": 25565,
"state": "ONLINE",
"lastHeartbeat": 1718000000000,
"processPid": 12345,
"allocatedRamMB": 2048,
"allocatedCpu": 100,
"runtime": "screen"
}
],
"resources": { "usedRamMB": 2048, "usedCpu": 100 }
}Execute a command on a node
POST /api/cluster/nodes/{id}Dispatches a console command to the specified node. Remote dispatch travels over Hazelcast to the target member. Commands intended for the node serving the request cannot be run through this endpoint; use the Commands API on the Master instead.
| Body field | Type | Description |
|---|---|---|
command | string | Console command to execute on the node, such as instance list. Required. |
curl -X POST http://<master>:7000/api/cluster/nodes/node-2 \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"command": "instance list"}'Targeting the local node returns 400 Bad Request:
{
"error": "Cannot execute command on local node via API"
}Remote node command execution is defined in the API surface but not yet fully wired up; a request to a remote node may return 501 Not Implemented. For commands on the Master itself, use POST /api/commands/execute.