Skip to main content
The Servers API lets you query, start, stop, and update running servers. Access it via api.server().

​
Get Servers

// Get all servers
api.server().getAllServers()
    .thenAccept(servers -> System.out.println("Total: " + servers.size()));

// Get servers with query filters
api.server().getAllServers(new ServerQuery())
    .thenAccept(servers -> { ... });

// Get server by ID
api.server().getServerById("server-uuid")
    .thenAccept(server -> System.out.println(server.getState()));

// Get servers in a group
api.server().getServersByGroup("lobby")
    .thenAccept(servers -> servers.forEach(s ->
        System.out.println(s.getServerId() + ": " + s.getState())));

// Get server by group and numerical ID (e.g., Lobby-1)
api.server().getServerByNumericalId("lobby", 1)
    .thenAccept(server -> System.out.println(server.getServerId()));

// Get current server (from within a running server)
api.server().getCurrentServer()
    .thenAccept(server -> System.out.println("Running on: " + server.getServerId()));

​
Start Server

StartServerRequest request = new StartServerRequest("group-uuid", "lobby");

api.server().startServer(request)
    .thenAccept(server -> System.out.println("Started: " + server.getServerId()));

​
Stop Server

api.server().stopServer("server-uuid")
    .thenAccept(success -> System.out.println("Stopped: " + success));

​
Update Server

UpdateServerRequest update = UpdateServerRequest.builder()
    .maxPlayers(64)
    .build();

api.server().updateServer("server-uuid", update)
    .thenAccept(server -> System.out.println("Updated: " + server.getMaxPlayers()));

​
Server Properties

Servers inherit properties from their group, but you can override them per-instance: 
// Add or update properties (merges with existing)
Map<String, String> props = Map.of("map", "castle", "mode", "competitive");
api.server().updateServerProperties("server-uuid", props);

// Remove specific properties
api.server().deleteServerProperties("server-uuid", List.of("mode"));

​
Server Model

PropertyTypeDescription
serverIdStringUnique identifier
groupNameStringParent group name
numericalIdlongNumerical ID within group (1, 2, 3…)
stateServerStateCurrent lifecycle state
hostStringServer host machine
ipStringIP address
portintServer port
minMemoryintMinimum memory (MB)
maxMemoryintMaximum memory (MB)
maxPlayersintPlayer limit
playerCountintCurrent online players
propertiesMap<String, String>Custom metadata
createdAtInstantCreation timestamp

​
ServerState

StateDescription
PREPARINGCopying template files
STARTINGJVM process launching
AVAILABLEReady for players
INGAMEHas active players
STOPPINGShutdown in progress

​
Environment Variables

Inside a running server, access server info without the API: 
String group = System.getenv("SIMPLECLOUD_GROUP");
String uniqueId = System.getenv("SIMPLECLOUD_UNIQUE_ID");
String numericalId = System.getenv("SIMPLECLOUD_NUMERICAL_ID");
String host = System.getenv("SIMPLECLOUD_HOST");
String ip = System.getenv("SIMPLECLOUD_IP");
String port = System.getenv("SIMPLECLOUD_PORT");
String maxPlayers = System.getenv("SIMPLECLOUD_MAX_PLAYERS");
String maxMemory = System.getenv("SIMPLECLOUD_MAX_MEMORY");
Custom group properties are also available with SIMPLECLOUD_ prefix (uppercase, dashes become underscores).