> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Servers API

> Find, inspect, update, and stop running server instances

A server is one running instance created from a group or persistent server. Use `api.server()` to inspect and manage that instance. To change how servers are created, update the owning [group](/docs/en/developer/api/groups) or [persistent server](/docs/en/developer/api/persistent-servers) instead.

## Find available capacity

Use `ServerQuery` to find instances by source, state, host, or numerical ID. This example calculates the reported free slots across playable lobby servers:

```java theme={null}
ServerQuery query = ServerQuery.create()
    .filterByServerGroupName("lobby")
    .filterByState(ServerState.AVAILABLE, ServerState.INGAME);

api.server().getAllServers(query)
    .thenApply(servers -> servers.stream()
        .filter(server -> server.getPlayerCount() != null)
        .mapToInt(server -> Math.max(
            0,
            server.getMaxPlayers() - server.getPlayerCount()
        ))
        .sum())
    .thenAccept(capacity ->
        System.out.println("Lobby capacity: " + capacity));
```

The result is a snapshot, not a reservation. If you use it to choose where a player should connect, keep the routing policy in your application and handle the connection result. See [Route players with autoscaling](/docs/en/developer/guides/server-management) for a complete routing workflow.

Call `getAllServers()` without a query to return every instance, or use `getServersByGroup("lobby")` as a group-name shortcut. List methods return an empty list when nothing matches.

<Accordion title="ServerQuery filters">
  Repeated calls to a multi-value filter add values to the query.

  <ParamField body="filterByServerGroupId(String... ids)" type="ServerQuery">
    Match one or more group IDs.
  </ParamField>

  <ParamField body="filterByState(ServerState... states)" type="ServerQuery">
    Match one or more lifecycle states.
  </ParamField>

  <ParamField body="filterByServerhostId(String id)" type="ServerQuery">
    Match instances running on one serverhost.
  </ParamField>

  <ParamField body="filterByPersistentServerId(String id)" type="ServerQuery">
    Match the instance of one persistent server.
  </ParamField>

  <ParamField body="filterByServerGroupType(GroupServerType... types)" type="ServerQuery">
    Match `SERVER` or `PROXY` sources.
  </ParamField>

  <ParamField body="filterByServerGroupName(String... names)" type="ServerQuery">
    Match one or more group or persistent server names.
  </ParamField>

  <ParamField body="filterByServerGroupTags(String... tags)" type="ServerQuery">
    Match sources with any supplied tag.
  </ParamField>

  <ParamField body="filterByNumericalId(Integer... ids)" type="ServerQuery">
    Match one or more numerical IDs.
  </ParamField>

  <ParamField body="sortBy(String field)" type="ServerQuery">
    Sort by `created_at`, `updated_at`, `numerical_id`, or `state`.
  </ParamField>

  <ParamField body="sortOrder(String order)" type="ServerQuery">
    Use `asc` or `desc`.
  </ParamField>
</Accordion>

## Find one server

Look up an instance by its unique ID, or by its group name and numerical ID:

```java theme={null}
api.server().getServerById("server-uuid")
    .thenAccept(server -> System.out.println(server.getState()));

api.server().getServerByNumericalId("lobby", 1)
    .thenAccept(server -> System.out.println(server.getServerId()));
```

These lookups complete exceptionally when no matching server exists.

### Get the current server

Code running inside a SimpleCloud-managed server can resolve its own instance:

```java theme={null}
api.server().getCurrentServer()
    .thenAccept(server -> System.out.println(server.getServerId()));
```

`getCurrentServer()` uses the `SIMPLECLOUD_UNIQUE_ID` environment variable and completes exceptionally when the current process is not associated with an instance.

## Access the owning configuration

Every instance belongs to either a group or a persistent server. `getServerBase()` provides their shared configuration, while `getGroup()` and `getPersistentServer()` expose source-specific fields.

```java theme={null}
api.server().getServerById("server-uuid")
    .thenAccept(server -> {
        if (server.isFromGroup()) {
            System.out.println("Group: " + server.getGroup().getName());
        } else {
            System.out.println(
                "Persistent server: " +
                server.getPersistentServer().getName()
            );
        }

        System.out.println(
            "Configured slots: " + server.getServerBase().getMaxPlayers()
        );
    });
```

Only one of `getGroup()` and `getPersistentServer()` is available for an instance. Avoid the deprecated `getServerGroup()`, which throws for persistent server instances.

## Update an instance

`UpdateServerRequest` changes only the fields you set:

```java theme={null}
UpdateServerRequest update = UpdateServerRequest.builder()
    .maxPlayers(64)
    .maxMemory(2048)
    .build();

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

The builder supports `playerCount`, `state`, `properties`, `minMemory`, `maxMemory`, and `maxPlayers`. Changes apply to this instance, not its owning configuration. The platform normally reports `state` and `playerCount`; only set them when your integration owns that reporting.

## Manage instance properties

Properties attach application data to one instance. Updates merge with the existing map.

```java theme={null}
api.server().updateServerProperties(
    "server-uuid",
    Map.of("gameMode", "competitive", "map", "castle")
);

api.server().deleteServerProperty("server-uuid", "map");
```

Use `updateServerProperty` to set one key and `deleteServerProperties` to remove several keys. Each method returns the resulting property map.

## Stop an instance

```java theme={null}
api.server().stopServer("server-uuid")
    .thenRun(() -> System.out.println("Shutdown initiated"));
```

The future completes when SimpleCloud initiates the stop, not when cleanup finishes. Use [server state events](/docs/en/developer/api/events) if your plugin must observe the later lifecycle transitions.

<Warning>
  Stopping an instance does not disable its group or persistent server. SimpleCloud may create a replacement to maintain the source configuration. Change that configuration first when the server must stay offline.
</Warning>

## Server model

<ResponseField name="serverId" type="string" required>
  Unique instance ID.
</ResponseField>

<ResponseField name="numericalId" type="integer" required>
  Numerical ID within the source group or persistent server.
</ResponseField>

<ResponseField name="serverGroupId" type="string | null">
  Source group ID, or `null` for a persistent server instance.
</ResponseField>

<ResponseField name="persistentServerId" type="string | null">
  Source persistent server ID, or `null` for a group instance.
</ResponseField>

<ResponseField name="serverhostId" type="string" required>
  Serverhost running the instance.
</ResponseField>

<ResponseField name="networkId" type="string" required>
  Network that owns the instance.
</ResponseField>

<ResponseField name="ip" type="string | null">
  Assigned IP address, or `null` before one is available.
</ResponseField>

<ResponseField name="port" type="integer | null">
  Assigned port, or `null` before one is available.
</ResponseField>

<ResponseField name="minMemory" type="integer" required>
  Minimum memory in MB.
</ResponseField>

<ResponseField name="maxMemory" type="integer" required>
  Maximum memory in MB.
</ResponseField>

<ResponseField name="cpuUsage" type="number | null">
  Current CPU usage percentage, or `null` when unavailable.
</ResponseField>

<ResponseField name="memoryUsage" type="number | null">
  Current memory usage in MB, or `null` when unavailable.
</ResponseField>

<ResponseField name="playerCount" type="integer | null">
  Current connected player count, or `null` when unavailable.
</ResponseField>

<ResponseField name="maxPlayers" type="integer" required>
  Player limit for the instance.
</ResponseField>

<ResponseField name="state" type="ServerState" required>
  Current lifecycle state.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  Creation timestamp in ISO 8601 format.
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  Last update timestamp in ISO 8601 format.
</ResponseField>

<ResponseField name="lastActivity" type="string | null">
  Last activity timestamp in ISO 8601 format, or `null` when unavailable.
</ResponseField>

<ResponseField name="properties" type="Map<String, Object> | null">
  Instance properties, or `null` when none are available.
</ResponseField>

<ResponseField name="blueprint" type="Blueprint | null">
  Reserved accessor. The current implementation returns `null`; use the source configuration instead.
</ResponseField>

<ResponseField name="serverBase" type="ServerBase" required>
  Shared configuration from the source group or persistent server.
</ResponseField>

<ResponseField name="group" type="Group | null">
  Source group, or `null` for a persistent server instance.
</ResponseField>

<ResponseField name="persistentServer" type="PersistentServer | null">
  Source persistent server, or `null` for a group instance.
</ResponseField>

## Server states

| State           | Meaning                                             |
| --------------- | --------------------------------------------------- |
| `UNKNOWN_STATE` | Unknown or unspecified.                             |
| `PREPARING`     | SimpleCloud is preparing the instance.              |
| `STARTING`      | The server process is starting.                     |
| `AVAILABLE`     | Ready to accept connections.                        |
| `INGAME`        | Running with active players.                        |
| `STOPPING`      | Shutdown is in progress.                            |
| `CLEANUP`       | The process has stopped and cleanup is in progress. |