Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ohemilyy/universe/llms.txt

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

The instance endpoints are the core of the Universe REST API. They let you list running instances, create new ones from a configuration, and push state or heartbeat updates from an external process such as a Minecraft plugin. All responses use the InstanceInfo shape defined in schemas.kt.

​
GET /api/instances

Returns an array of all InstanceInfo objects currently tracked by the Master node, across all wrapper nodes. 
curl http://localhost:7000/api/instances
Response — 200 OK 
[
  {
    "id": "a1b2c3",
    "configurationName": "default",
    "wrapperNodeId": "node-1",
    "hostAddress": "127.0.0.1",
    "allocatedPort": 25565,
    "state": "ONLINE",
    "lastHeartbeat": 1717000000000,
    "processPid": 12345,
    "allocatedRamMB": 512,
    "allocatedCpu": 100
  }
]
​
id
string
required
6-character alphanumeric instance identifier generated from a random UUID.
​
configurationName
string
required
Name of the Configuration used to create this instance (matches a file in ./configuration/).
​
wrapperNodeId
string
required
ID of the cluster node running the instance process.
​
hostAddress
string
required
IP address on which the instance is bound, taken from the configuration.
​
allocatedPort
number
required
The port allocated to this instance from the configuration’s availablePorts range.
​
state
string
required
Current lifecycle state. One of CREATING, ONLINE, OFFLINE, or STOPPED.
​
lastHeartbeat
number
required
Unix timestamp (milliseconds) of the last heartbeat received from the instance.
​
processPid
number
OS process ID of the running instance. null if the process has not started or has exited.
​
allocatedRamMB
number
Maximum RAM allocated to the instance in megabytes. 0 means unlimited.
​
allocatedCpu
number
Maximum CPU units allocated to the instance. 0 means unlimited.

​
POST /api/instances

Creates a new instance from a named configuration. The Master selects an eligible wrapper node, dispatches a DeployInstanceTask via Hazelcast, and returns the new InstanceInfo immediately. Request body
​
configurationName
string
required
Name of an existing configuration file (without the .json extension) from ./configuration/.
curl -X POST http://localhost:7000/api/instances \
  -H "Content-Type: application/json" \
  -d '{"configurationName": "default"}'
Response — 201 Created 
{
  "id": "x9y8z7",
  "configurationName": "default",
  "wrapperNodeId": "node-1",
  "hostAddress": "127.0.0.1",
  "allocatedPort": 25565,
  "state": "CREATING",
  "lastHeartbeat": 1717000001000,
  "processPid": null,
  "allocatedRamMB": 512,
  "allocatedCpu": 100
}
Error responses
StatusCondition
400 Bad RequestconfigurationName is missing or does not match any loaded configuration.
503 Service UnavailableNo cluster node has sufficient resources for the configuration’s RAM/CPU requirements.

​
PUT /api/instances//state

Updates the state and optionally the lastHeartbeat of an existing instance. This endpoint is typically called by an external process (e.g., a Minecraft plugin) to report that the server is online, or to confirm a graceful shutdown. Path parameter
​
id
string
required
The 6-character instance ID returned when the instance was created.
Request body
​
state
string
required
New lifecycle state. Must be one of: CREATING, ONLINE, OFFLINE, STOPPED.
​
lastHeartbeat
number
Unix timestamp in milliseconds. If omitted, the server sets it to the current time.
curl -X PUT http://localhost:7000/api/instances/x9y8z7/state \
  -H "Content-Type: application/json" \
  -d '{"state": "ONLINE"}'
Response — 200 OK Returns the full updated InstanceInfo object. See GET /api/instances for the field reference. Error responses
StatusCondition
400 Bad Requeststate is missing or is not a valid InstanceState value.
404 Not FoundNo instance exists with the given id.

Build docs developers (and LLMs) love

Get started for freeTalk to us