Documentation Index
Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt
Use this file to discover all available pages before exploring further.
The Groups API lets you create, query, update, and delete server groups. Access it via api.group().
Get Groups
// Get all groups
api.group().getAllGroups()
.thenAccept(groups -> groups.forEach(g -> System.out.println(g.getName())));
// Get all groups with query filters
api.group().getAllGroups(new GroupQuery())
.thenAccept(groups -> { ... });
// Get group by name
api.group().getGroupByName("lobby")
.thenAccept(group -> System.out.println(group.getId()));
// Get group by ID
api.group().getGroupById("group-uuid")
.thenAccept(group -> System.out.println(group.getName()));
Create Group
CreateGroupRequest request = CreateGroupRequest.builder()
.name("bedwars")
.type(GroupServerType.SERVER)
.minMemory(512)
.maxMemory(1024)
.maxPlayers(16)
.minOnlineCount(1)
.maxOnlineCount(10)
.build();
api.group().createGroup(request)
.thenAccept(group -> System.out.println("Created: " + group.getId()));
Update Group
UpdateGroupRequest update = UpdateGroupRequest.builder()
.maxPlayers(32)
.maxOnlineCount(20)
.build();
api.group().updateGroup("group-uuid", update)
.thenAccept(group -> System.out.println("Updated: " + group.getName()));
Delete Group
api.group().deleteGroup("group-uuid")
.thenAccept(success -> System.out.println("Deleted: " + success));
Deleting a group doesn’t stop running servers. Stop servers first if needed.
Group Properties
Groups support custom key-value properties for metadata:
// Add or update properties (merges with existing)
Map<String, String> props = Map.of(
"gameMode", "ADVENTURE",
"region", "eu-west"
);
api.group().updateGroupProperties("group-uuid", props);
// Remove specific properties
api.group().deleteGroupProperties("group-uuid", List.of("region"));
SIMPLECLOUD_.
Group Model
| Property | Type | Description |
|---|
id | String | Unique identifier |
name | String | Group name |
type | GroupServerType | SERVER or PROXY |
minMemory | int | Minimum memory (MB) |
maxMemory | int | Maximum memory (MB) |
maxPlayers | int | Player limit per server |
minOnlineCount | int | Minimum servers running |
maxOnlineCount | int | Maximum servers allowed |
properties | Map<String, String> | Custom metadata |
scalingConfig | ScalingConfig | Auto-scaling settings |
deploymentConfig | DeploymentConfig | Host deployment settings |
sourceConfig | SourceConfig | Blueprint or image source |
ScalingConfig
| Property | Type | Description |
|---|
min_servers | int | Minimum servers to keep running |
max_servers | int | Maximum servers allowed |
scaling_mode | ScalingMode | SLOTS or SERVERS |
available_slots | int | Open slots to maintain (Slots mode) |
player_threshold | float | Scale-up threshold between 0 and 1 |
scale_down | ScaleDownConfig | Scale-down behavior settings |
Server start queue
Groups using the SERVERS scaling mode support a manual start queue. Instead of starting a server immediately, you can request a queued start that the reconciler processes on its next tick. This is useful when you want to control exactly when new servers are created while still respecting the group’s max_servers limit.
The start queue is only available for groups using the SERVERS scaling mode. Groups using SLOTS mode do not support queued starts.
Queue a server start
You can request a start by passing the server group ID directly or by resolving a Group first:
// Request a start by server group ID
api.group().requestServerStart("group-uuid")
.thenRun(() -> System.out.println("Start request accepted"));
// Request a start using the Group overload
api.group().getGroupByName("lobby")
.thenCompose(group -> {
if (group == null) {
return CompletableFuture.failedFuture(
new IllegalArgumentException("Group not found: lobby"));
}
return api.group().requestServerStart(group);
})
.thenRun(() -> System.out.println("Start request accepted for lobby"));
max_servers limit, the queued start is marked as FAILED with a reason.
List queued starts
api.group().getServerStartQueue()
.thenAccept(queue -> {
System.out.println("Groups with queue data: " + queue.getCount());
System.out.println("Queued starts: " + queue.getQueuedStarts());
System.out.println("Failed starts: " + queue.getFailedStarts());
GroupStartQueueEntry lobby = queue.findByServerGroupName("lobby");
if (lobby != null) {
System.out.println("Lobby starts: " + lobby.getTotalStarts());
}
});
Clear queued starts
Remove all pending and failed starts for a specific group:
api.group().clearServerStartQueue("group-uuid")
.thenRun(() -> System.out.println("Cleared queue for group-uuid"));
Queue overview model
getServerStartQueue() returns a GroupStartQueue.
| Property | Type | Description |
|---|
count | int | Number of groups with queue data |
queuedStarts | int | Number of queued starts across all groups |
failedStarts | int | Number of failed starts across all groups |
totalStarts | int | Total number of queue items across all groups |
items | List<GroupStartQueueEntry> | Queue data grouped by server group |
Queue entry model
Each GroupStartQueueEntry describes the queue state for one server group.
| Property | Type | Description |
|---|
serverGroupId | String? | Server group ID |
serverGroupName | String? | Server group name |
queuedStarts | int | Number of pending starts for the group |
failedStarts | int | Number of failed starts for the group |
totalStarts | int | Total number of queue items for the group |
starts | List<GroupStartQueueItem> | Persisted queue items for the group |
Queue item model
Each GroupStartQueueItem represents one persisted start request.
| Property | Type | Description |
|---|
id | String | Unique identifier for the queued start |
createdAt | String? | Timestamp when the start was queued (ISO 8601) |
status | GroupStartQueueItemStatus | PENDING, FAILED, or UNKNOWN |
failureReason | String? | Reason for failure, if applicable |
Failed starts are automatically cleaned up after 1 hour. Use the list endpoint to check for failures and requeue if needed.
GroupServerType
| Value | Description |
|---|
SERVER | Game server (Paper, Spigot, etc.) |
PROXY | Proxy server (Velocity, BungeeCord) |
