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 Universe REST API is a Ktor-based HTTP interface exposed exclusively on Master nodes. It gives you programmatic control over the entire cluster — from deploying and managing instances to syncing templates, querying node health, and streaming live logs over WebSocket. All responses are JSON unless otherwise noted.

​
Base URL

The API binds to port 7000 by default (the apiPort field in UniverseMainConfiguration). Every endpoint lives under the /api prefix: 
http://<master-ip>:7000/api
The REST API is only available on the node configured as isMasterNode: true. Worker nodes do not expose the HTTP interface. Point all API clients at the master node’s address.

​
Authentication

All endpoints except GET /api/ping and GET /api/metrics require a valid Bearer token in the Authorization header. Two permission levels are supported:
LevelDescriptionRate Limit
ALLFull admin access — instances, configs, templates, commandsUnlimited
PUBLICTracked by the rate limiter; no protected route accepts this level (all routes use ALL)100 req / 60 s
See the Authentication guide for how to generate keys and pass the token in requests.

​
Rate Limiting

Universe uses a sliding window rate limiter applied per API key. Keys with PUBLIC permission are capped at 100 calls per 60 seconds. Keys with ALL permission bypass the limiter entirely. When the limit is exceeded the API returns 429 Too Many Requests: 
{
  "error": "Rate limit exceeded",
  "message": "100 calls were already made during 1m",
  "retryAfterMs": 45000
}

​
Endpoint Index

The table below lists every route in the API. Rows marked WS are WebSocket upgrade endpoints.
MethodPathDescription
GET/pingHealth check — returns node status, no auth required
GET/nodeSystem stats and uptime for the current node
GET/node/configFull UniverseMainConfiguration for the current node
POST/node/reloadReload node configuration from disk (not yet implemented)
GET/cluster/nodesList all Hazelcast cluster members
GET/cluster/nodes/{id}Detailed info and instances for a specific node
POST/cluster/nodes/{id}/commandDispatch a console command to a node
GET/instancesList all instances across the cluster
POST/instancesCreate and deploy a new instance
GET/instances/{id}Get details for a single instance
DELETE/instances/{id}Stop and remove an instance
PATCH/instances/{id}/lifecycleStart, stop, or restart an instance
PUT/instances/{id}/stateUpdate instance state and heartbeat timestamp
POST/instances/{id}/executeSend a command to an instance’s stdin
GET/instances/{id}/logsFetch recent log lines for an instance
WS/instances/{id}/live-logStream live log output from an instance
GET/configurationsList all instance configurations
GET/configurations/{name}Get a single configuration by name
PUT/configurations/{name}Create or update a configuration
DELETE/configurations/{name}Delete a configuration
GET/templatesList all templates organised by group
GET/templates/{group}/{name}Get details for a specific template
GET/templates/{group}/{name}/filesList files inside a local template directory
GET/templates/{group}/{name}/files/{path}Read the contents of a template file
PATCH/templates/{group}/{name}/files/{path}Edit the contents of a template file
POST/templates/{group}/{name}/files/{path}Create a new file inside a template
DELETE/templates/{group}/{name}/files/{path}Delete a file from a template
POST/templates/{group}/{name}/exportExport a local template as a .zip
POST/templates/{group}/{name}/importImport a template from a .zip
POST/templates/{group}/{name}/syncSync a template from a remote storage provider
POST/templates/syncDispatch a cluster-wide template sync via Hazelcast
POST/commands/executeExecute a console command on the master node
WS/consoleInteractive WebSocket console for the master node
GET/metricsPrometheus metrics scrape endpoint — no auth required

​
Resource Groups

Instances

Create, inspect, stop, and control the lifecycle of running instances across the cluster.

Configurations

Manage instance configurations — the blueprints that define how instances are deployed.

Templates

Browse, edit, export, import, and sync file templates used during instance provisioning.

Cluster

Inspect cluster membership and dispatch commands to individual nodes via Hazelcast.

Node

Query system stats, configuration, and reload settings on the current master node.

Commands

Execute console commands on the master node and capture their output synchronously.

WebSockets

Stream live instance logs or open an interactive console session over WebSocket.
WebSocket endpoints (/instances/{id}/live-log and /console) require the same Authorization: Bearer TOKEN header to be included in the HTTP upgrade request. Authentication is validated before the connection is promoted to a WebSocket.

Build docs developers (and LLMs) love

Get started for freeTalk to us