> ## 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.

# Groups API

> Manage server groups programmatically

The Groups API lets you create, query, update, and delete server groups. Access it via `api.group()`.

## Get Groups

```java theme={null}
// 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

```java theme={null}
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

```java theme={null}
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

```java theme={null}
api.group().deleteGroup("group-uuid")
    .thenAccept(success -> System.out.println("Deleted: " + success));
```

<Warning>
  Deleting a group doesn't stop running servers. Stop servers first if needed.
</Warning>

## Group Properties

Groups support custom key-value properties for metadata:

```java theme={null}
// 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"));
```

Properties are available in servers as environment variables prefixed with `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.

<Info>
  The start queue is only available for groups using the `SERVERS` scaling mode. Groups using `SLOTS` mode do not support queued starts.
</Info>

### Queue a server start

You can request a start by passing the server group ID directly or by resolving a `Group` first:

```java theme={null}
// 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"));
```

The reconciler picks up queued starts on the next reconciliation tick and attempts to allocate a server. If the group is at its `max_servers` limit, the queued start is marked as `FAILED` with a reason.

### List queued starts

```java theme={null}
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:

```java theme={null}
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              |

<Warning>
  Failed starts are automatically cleaned up after 1 hour. Use the list endpoint to check for failures and requeue if needed.
</Warning>

## GroupServerType

| Value    | Description                         |
| -------- | ----------------------------------- |
| `SERVER` | Game server (Paper, Spigot, etc.)   |
| `PROXY`  | Proxy server (Velocity, BungeeCord) |