Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/universeclouddev/Universe/llms.txt

Use this file to discover all available pages before exploring further.

The Node API gives you visibility into the specific Universe node you are talking to. It includes a public health check endpoint (no auth required), a detailed node status endpoint, the raw UniverseMainConfiguration the node loaded at startup, a (stub) config reload endpoint, and the Prometheus metrics scrape target. These endpoints operate on the local node only. To inspect other nodes in the cluster, use the Cluster API.

​
The UniverseMainConfiguration Object

This schema mirrors ./config.json on disk and is returned verbatim by GET /api/node/config.
​
address
string
IP address this node binds Hazelcast to (e.g., 127.0.0.1).
​
port
integer
Hazelcast cluster port (default 6000).
​
apiPort
integer
REST API HTTP port (default 7000 / 8080 in development).
​
nodeId
string
Human-readable node identifier (e.g., node-1). Shown in GET /api/ping and cluster listings.
​
clusterName
string
Name of the Hazelcast cluster this node joins (e.g., universe-cluster).
​
isMasterNode
boolean
true if this node is the master. Master nodes expose the REST API and own the console WebSocket. Wrapper nodes only execute instances.
​
masterAddress
string
IP address of the master node. Used by wrapper nodes to reach the master’s Hazelcast interface.
​
masterPort
integer
Hazelcast port of the master node.
​
masterApiPort
integer
REST API port of the master node. Wrapper nodes use this to resolve the %MASTER_API_PORT% template variable.
​
debug
boolean
When true, enables verbose DEBUG logging to both the console and log files.
​
maxRamMB
integer
Maximum RAM (in MB) this node will accept when scheduling new instances. The scheduler rejects placements that would exceed this limit.
​
maxCpu
integer
Maximum CPU units this node will accept. 100 = 1 core.

​
Endpoints

​
GET /api/ping

A lightweight health check that requires no authentication. Returns basic identity information about the node. Use this endpoint for load balancer health probes and uptime monitors. Authentication: None required. 
curl http://localhost:8080/api/ping
Response — 200 OK
​
status
string
Always "ok" when the node is running.
​
nodeId
string
The node’s human-readable identifier.
​
clusterName
string
The Hazelcast cluster this node belongs to.
​
master
boolean
Whether this node is the master node.
{
  "status": "ok",
  "nodeId": "node-1",
  "clusterName": "universe-cluster",
  "master": true
}
StatusMeaning
200Node is running and responsive.

​
GET /api/node

Returns detailed runtime information about the local node: identity, version, uptime, and JVM/OS system statistics. Authentication: ALL permission required. 
curl http://localhost:8080/api/node \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK
​
id
string
The node ID from config.
​
clusterName
string
The Hazelcast cluster name.
​
version
string
Universe version string (e.g., 0.0.1).
​
master
boolean
Whether this is the master node.
​
address
string
Hazelcast bind address.
​
port
integer
Hazelcast cluster port.
​
apiPort
integer
REST API port.
​
uptimeMs
integer
JVM uptime in milliseconds since process start.
​
system
object
{
  "id": "node-1",
  "clusterName": "universe-cluster",
  "version": "0.0.1",
  "master": true,
  "address": "127.0.0.1",
  "port": 6000,
  "apiPort": 8080,
  "uptimeMs": 345678,
  "system": {
    "availableProcessors": 8,
    "systemLoadAverage": 1.23,
    "freeMemory": 536870912,
    "totalMemory": 1073741824,
    "maxMemory": 4294967296
  }
}
StatusMeaning
200Node info returned.
401Unauthorized.

​
GET /api/node/config

Returns the full UniverseMainConfiguration that this node loaded at startup. Useful for verifying the active config without SSHing into the node. Authentication: ALL permission required. 
curl http://localhost:8080/api/node/config \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK The complete UniverseMainConfiguration object (see schema above). 
{
  "address": "127.0.0.1",
  "port": 6000,
  "apiPort": 8080,
  "nodeId": "node-1",
  "clusterName": "universe-cluster",
  "isMasterNode": true,
  "masterAddress": "127.0.0.1",
  "masterPort": 6000,
  "masterApiPort": 8080,
  "debug": false,
  "maxRamMB": 16384,
  "maxCpu": 800
}
StatusMeaning
200Config returned.
401Unauthorized.

​
POST /api/node/reload

Triggers a configuration reload from disk. Not yet implemented — always returns 501. Authentication: ALL permission required. 
curl -X POST http://localhost:8080/api/node/reload \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 501 Not Implemented 
{
  "error": "Configuration reload is not yet implemented"
}
Until this endpoint is implemented, reload configurations by restarting the node or using the config reload console command, which re-reads all ./configuration/*.json files from disk.
StatusMeaning
501Not yet implemented.
401Unauthorized.

​
GET /api/metrics

Returns metrics in Prometheus exposition format (text/plain). This endpoint requires no authentication and is designed to be scraped directly by Prometheus or compatible monitoring tools. Metric collection requires the metrics-prometheus extension to be installed in ./extensions/. If no provider is registered, the endpoint returns 503 with a comment line. Authentication: None required. 
curl http://localhost:8080/api/metrics
Response — 200 OK — Prometheus plain-text format. 
# HELP universe_instances_total Total number of instances
# TYPE universe_instances_total gauge
universe_instances_total 5

# HELP universe_instances_online Instances currently in ONLINE state
# TYPE universe_instances_online gauge
universe_instances_online 4

# HELP universe_node_used_ram_mb RAM used by instances on this node in MB
# TYPE universe_node_used_ram_mb gauge
universe_node_used_ram_mb 8192
StatusMeaning
200Metrics scraped and returned.
503No metrics provider registered (metrics-prometheus extension not loaded).
Point your Prometheus scrape_configs at http://<node-host>:<apiPort>/api/metrics with a short interval (e.g., 15s) to get live cluster dashboards.

Build docs developers (and LLMs) love

Get started for freeTalk to us