Groups API

A group describes a set of servers that share the same software, resources, and scaling behavior. Use api.group() to manage groups or request another server for a group.

Create a group

This example creates a Paper lobby group and its blueprint. SimpleCloud keeps one lobby running and can scale the group up to three servers while maintaining 20 available player slots.

CreateGroupRequest request = CreateGroupRequest.builder()
    .name("lobby")
    .type(GroupServerType.SERVER)
    .minMemory(1024)
    .maxMemory(2048)
    .maxPlayers(100)
    .createBlueprint(CreateBlueprintRequest.builder()
        .configurator("paper")
        .serverSoftware("paper")
        .minecraftVersion("1.21.11")
        .build())
    .scaling(ScalingConfig.builder()
        .scalingMode(ScalingMode.SLOTS)
        .minServers(1)
        .maxServers(3)
        .availableSlots(20)
        .build())
    .build();

api.group().createGroup(request)
    .thenAccept(group -> System.out.println(
        "Created " + group.getName() + " with ID " + group.getServerGroupId()
    ));

The group name is also used for the new blueprint. To use a blueprint that already exists, replace createBlueprint(...) with:

.source(SourceConfig.builder()
    .type(SourceType.BLUEPRINT)
    .blueprint("blueprint-uuid")
    .build())

Do not set both createBlueprint and an existing blueprint or image source.

CreateGroupRequest fields

string

required

Group name. Up to 100 characters of ASCII letters, digits, underscores, and hyphens ([A-Za-z0-9_-]). Must be unique within the network, case-insensitive — Lobby and lobby are treated as the same name. A group and a persistent server may share a name. Creating or renaming to a name that only differs by case from an existing group returns 409 Conflict.

GroupServerType

SERVER for game servers or PROXY for proxies. Defaults to SERVER.

integer | null

Minimum memory in MB.

integer | null

Maximum memory in MB.

integer

Player limit per server. Defaults to 50.

boolean

Whether the group may create servers. Defaults to true.

integer | null

Group priority.

DeploymentConfig | null

Host selection settings.

ScalingConfig | null

Minimum and maximum servers and scaling behavior.

SourceConfig | null

Existing blueprint or container image used by the group.

CreateBlueprintRequest | null

Blueprint to create with the group.

WorkflowsConfig | null

Lifecycle and manual workflows.

Map<String, Object> | null

Custom group properties.

List<String> | null

Tags used to organize and filter groups.

Find groups

Look up a group by name or ID:

api.group().getGroupByName("lobby")
    .thenAccept(group -> System.out.println(group.getServerGroupId()));

api.group().getGroupById("group-uuid")
    .thenAccept(group -> System.out.println(group.getName()));

Both methods complete exceptionally when the group does not exist. Name lookups are case-insensitive. Use GroupQuery to filter the group list by type, tag, or result limit:

GroupQuery query = GroupQuery.create()
    .filterByType(GroupServerType.SERVER)
    .filterByTag("production")
    .limit(25);

api.group().getAllGroups(query)
    .thenAccept(groups -> groups.forEach(group ->
        System.out.println(group.getName())
    ));

Call getAllGroups() without a query to return every group.

Update a group

UpdateGroupRequest changes only the fields you set:

UpdateGroupRequest update = UpdateGroupRequest.builder()
    .maxPlayers(120)
    .build();

api.group().updateGroup("group-uuid", update)
    .thenAccept(group -> System.out.println("Updated " + group.getName()));

You can update name, type, minMemory, maxMemory, maxPlayers, active, priority, deployment, scaling, source, workflows, properties, and tags. When updating a nested object such as ScalingConfig, provide all values you want it to contain. Use the property methods below when you only want to merge individual properties.

Manage group properties

Group properties store custom data for your plugins. Updates merge with the existing map.

Map<String, Object> properties = Map.of(
    "gameMode", "ADVENTURE",
    "region", "eu-west"
);

api.group().updateGroupProperties("group-uuid", properties)
    .thenAccept(updated -> System.out.println("Properties: " + updated));

api.group().deleteGroupProperty("group-uuid", "region")
    .thenAccept(remaining -> System.out.println("Properties: " + remaining));

Use deleteGroupProperties to remove several keys at once. Each property method returns the resulting map.

Start another server

Request one additional server when a specific application action needs another instance:

api.group().getGroupByName("lobby")
    .thenCompose(api.group()::requestServerStart)
    .thenRun(() -> System.out.println("Start requested"));

This queues one start request without changing the group’s scaling configuration. Use the Servers API or server events when your plugin needs to wait for the new server.

Inspect the start queue

The queue shows pending and failed manual start requests:

api.group().getServerStartQueue()
    .thenAccept(queue -> {
        GroupStartQueueEntry lobby = queue.findByServerGroupName("lobby");
        if (lobby == null) {
            return;
        }

        lobby.getStarts().stream()
            .filter(start -> start.getStatus() == GroupStartQueueItemStatus.FAILED)
            .forEach(start -> System.err.println(start.getFailureReason()));
    });

findByServerGroupId and findByServerGroupName return null when the queue has no entry for the group. Clear pending start requests for a group with:

api.group().clearServerStartQueue("group-uuid");

This does not stop servers that have already been created.

Start queue fields

GroupStartQueue contains totals across every group and a list of GroupStartQueueEntry objects.

integer

required

Number of group entries.

integer

required

Number of pending starts.

integer

required

Number of failed starts.

integer

required

Total number of start requests.

List<GroupStartQueueEntry>

required

Queue entries grouped by server group.

Each GroupStartQueueEntry provides the group ID and name, its start counts, and a starts list. A GroupStartQueueItem provides its ID, creation time, status, and failure reason. Its status is PENDING, FAILED, or UNKNOWN.

Delete a group

api.group().deleteGroup("group-uuid");

Deactivate the group first so it cannot replace stopped instances. Stop its servers, wait for them to stop, then delete the group.

Group model reference

The following fields are available through Group getters.

string

required

Unique group identifier.

string

required

Group name.

GroupServerType

required

SERVER, PROXY, or UNKNOWN_SERVER.

integer | null

Minimum memory in MB.

integer | null

Maximum memory in MB.

integer | null

Player limit per server.

boolean | null

Whether the group may create servers.

integer | null

Group priority.

DeploymentConfig | null

Host selection configuration.

ScalingConfig | null

Scaling configuration.

SourceConfig | null

Blueprint or container image source.

WorkflowsConfig | null

Lifecycle and manual workflows.

Map<String, Object> | null

Custom group properties.

List<String> | null

Group tags.

string

required

Creation timestamp in ISO 8601 format.

string

required

Last-update timestamp in ISO 8601 format.

ScalingConfig fields

integer

required

Minimum number of servers to maintain.

integer

required

Maximum number of servers the group may create.

ScalingMode | null

SLOTS maintains free capacity. PLAYERS scales from player utilization.

integer

required

Free player slots to maintain in SLOTS mode.

number

required

Player utilization threshold between 0 and 1.

ScaleDownConfig | null

Scale-down settings.

Group create and update operations support SLOTS and PLAYERS scaling modes.

Group server types

Value	Description
`SERVER`	Game server, such as Paper or Spigot
`PROXY`	Proxy server, such as Velocity or BungeeCord
`UNKNOWN_SERVER`	Unknown server type returned by the API

Getting Started

Cloud API

Guides

REST API Reference

Create a group

Find groups

Update a group

Manage group properties

Start another server

Inspect the start queue

Delete a group

Group model reference

Group server types

​Create a group

​Find groups

​Update a group

​Manage group properties

​Start another server

​Inspect the start queue

​Delete a group

​Group model reference

​Group server types

Create a group

Find groups

Update a group

Manage group properties

Start another server

Inspect the start queue

Delete a group

Group model reference

Group server types