> ## 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.
# Servers API
> Laufende Server-Instanzen abfragen und verwalten
Die Servers API ermöglicht das Abfragen, Starten, Stoppen und Aktualisieren von laufenden Servern. Zugriff über `api.server()`.
## Server abrufen
```java theme={null}
// Alle Server
api.server().getAllServers()
.thenAccept(servers -> System.out.println("Total: " + servers.size()));
// Server nach ID
api.server().getServerById("server-uuid")
.thenAccept(server -> System.out.println(server.getState()));
// Server in einer Gruppe
api.server().getServersByGroup("lobby")
.thenAccept(servers -> servers.forEach(s ->
System.out.println(s.getServerId() + ": " + s.getState())));
// Server nach Gruppe und numerischer ID (z.B. Lobby-1)
api.server().getServerByNumericalId("lobby", 1)
.thenAccept(server -> System.out.println(server.getServerId()));
// Aktuellen Server (aus laufendem Server)
api.server().getCurrentServer()
.thenAccept(server -> System.out.println("Läuft auf: " + server.getServerId()));
```
## Server starten
```java theme={null}
StartServerRequest request = new StartServerRequest("group-uuid", "lobby");
api.server().startServer(request)
.thenAccept(server -> System.out.println("Gestartet: " + server.getServerId()));
```
## Server stoppen
```java theme={null}
api.server().stopServer("server-uuid")
.thenAccept(success -> System.out.println("Gestoppt: " + success));
```
## Server aktualisieren
```java theme={null}
UpdateServerRequest update = UpdateServerRequest.builder()
.maxPlayers(64)
.build();
api.server().updateServer("server-uuid", update)
.thenAccept(server -> System.out.println("Aktualisiert: " + server.getMaxPlayers()));
```
## Server auflisten (REST)
Um Server in einem Netzwerk mit optionalen Filtern aufzulisten, verwende den REST-API-Endpunkt `GET /v0/servers`. Die Antwort enthält Server-Details, Server-Gruppen- oder Persistent-Server-Metadaten, Blueprint-Informationen und Workflow-Konfigurationen.
```bash theme={null}
curl "https://your-controller/v0/servers?state=AVAILABLE&type=lobby" \
-H "X-Network-ID: your-network-id" \
-H "X-Network-Secret: your-network-secret"
```
| Parameter | Ort | Erforderlich | Beschreibung |
| ---------------------- | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Network-ID` | Header | Ja | Deine Netzwerk-ID |
| `X-Network-Secret` | Header | Ja | Dein Netzwerk-Secret **oder** ein App-JWT für das Zielnetzwerk. Wenn der Controller mit JWT-Authentifizierung konfiguriert ist, werden beide Credential-Typen akzeptiert. JWTs müssen für das in `X-Network-ID` angegebene Netzwerk gültig sein und werden mit subject-basierten Berechtigungen gescoped; Netzwerk-Secrets gewähren vollen Netzwerkzugriff. |
| `X-SC-Component` | Header | Nein | Optionaler Name der aufrufenden Komponente (zum Beispiel `serverhost`). Wenn gesetzt, wird der Wert dem Request-Wide-Event des Controllers als Feld `component` angehängt, sodass Request-Logs nach der ursprünglichen SimpleCloud-Komponente gefiltert werden können. Führende und nachgestellte Leerzeichen werden entfernt. |
| `server_group_id` | Query | Nein | Nach Server-Gruppen-ID(s) filtern, kommagetrennt |
| `state` | Query | Nein | Nach Status filtern, kommagetrennt (z.B. `AVAILABLE,STARTING`) |
| `serverhost_id` | Query | Nein | Nach Serverhost-ID filtern |
| `persistent_server_id` | Query | Nein | Nach Persistent-Server-ID filtern |
| `type` | Query | Nein | Nach Typ(en) filtern, kommagetrennt (Server-Gruppen- ODER Persistent-Server-Typ) |
| `name` | Query | Nein | Nach Name(n) filtern, kommagetrennt (Server-Gruppen- ODER Persistent-Server-Name) |
| `tags` | Query | Nein | Nach Tag(s) filtern, kommagetrennt (matcht wenn irgendein Tag passt) |
| `numerical_id` | Query | Nein | Nach numerischer ID filtern, kommagetrennt (z.B. `1,5,10`) |
| `sort_by` | Query | Nein | Sortierfeld: `created_at`, `updated_at`, `numerical_id`, `state` |
| `sort_order` | Query | Nein | Sortierreihenfolge: `asc` (Standard) oder `desc` |
### Response-Cache
Um die Datenbanklast durch hochfrequente Aufrufer (Dashboards, Panels, Polling-Clients) zu reduzieren, cached der Controller die zugrundeliegenden Datenbankzeilen für `GET /v0/servers` für **2 Sekunden**. Identische, aufeinanderfolgende Anfragen innerhalb dieses Fensters werden aus dem In-Memory-Response-Cache bedient anstatt Postgres erneut abzufragen.
Caching greift nur, wenn der Aufrufer keine benutzerspezifische Berechtigungsfilterung anwendet. Berechtigungsgefilterte Aufrufer umgehen den Cache immer, um zu verhindern, dass Ergebnisse zwischen Aufrufern mit unterschiedlichen Berechtigungen vermischt werden.
Wenn Caching aktiv ist, enthält die Antwort einen `X-DB-Cache`-Header zur Beobachtbarkeit:
| Header-Wert | Bedeutung |
| ------------------ | -------------------------------------------------------------------- |
| `X-DB-Cache: HIT` | Zeilen wurden aus dem Response-Cache bedient |
| `X-DB-Cache: MISS` | Zeilen wurden aus der Datenbank geladen und in den Cache geschrieben |
Der Header wird bei berechtigungsgefilterten Anfragen (die den Cache immer umgehen) und wenn der Response-Cache nicht konfiguriert ist, nicht gesetzt.
Die TTL von 2 Sekunden ist kurz genug, damit Antworten für UI-Anwendungsfälle effektiv in Echtzeit bleiben. Wenn striktere Aktualitätsgarantien benötigt werden, behandle jede Antwort mit `X-DB-Cache: HIT` als bis zu 2 Sekunden veraltet.
## Server-Datensatz löschen
Um einen Server-Datensatz direkt aus der Datenbank zu entfernen, ohne den Prozess zu stoppen oder Lifecycle-Events auszulösen, verwende den REST-API-Endpunkt `DELETE /v0/servers/database`. Dies ist nützlich, um veraltete oder verwaiste Datensätze zu bereinigen, wenn der Serverprozess bereits beendet wurde.
Diese Operation entfernt nur den Datenbankeintrag. Sie stoppt nicht den Serverprozess, löst keine Cleanup-Workflows aus und sendet keine Events. Verwende `stopServer` für normales Herunterfahren.
```bash theme={null}
curl -X DELETE "https://your-controller/v0/servers/database?server_id=SERVER_UUID" \
-H "X-Network-ID: your-network-id" \
-H "X-Network-Secret: your-network-secret"
```
**Antwort:**
```json theme={null}
{
"server_id": "123e4567-e89b-12d3-a456-426614174000",
"message": "Server row deleted successfully"
}
```
| Parameter | Ort | Erforderlich | Beschreibung |
| ------------------ | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server_id` | Query | Ja | UUID des zu löschenden Server-Datensatzes |
| `X-Network-ID` | Header | Ja | Deine Netzwerk-ID |
| `X-Network-Secret` | Header | Ja | Dein Netzwerk-Secret **oder** ein App-JWT für das Zielnetzwerk. Wenn der Controller mit JWT-Authentifizierung konfiguriert ist, werden beide Credential-Typen akzeptiert. |
| `X-SC-Component` | Header | Nein | Optionaler Name der aufrufenden Komponente, der dem Request-Wide-Event des Controllers als Feld `component` angehängt wird. Führende und nachgestellte Leerzeichen werden entfernt. |
## Server Model
| Property | Typ | Beschreibung |
| ------------- | --------------------- | ------------------------------------ |
| `serverId` | `String` | Eindeutige Kennung |
| `groupName` | `String` | Eltern-Gruppenname |
| `numericalId` | `long` | Numerische ID in Gruppe (1, 2, 3...) |
| `state` | `ServerState` | Aktueller Lifecycle-Status |
| `host` | `String` | Server-Host-Maschine |
| `ip` | `String` | IP-Adresse |
| `port` | `int` | Server-Port |
| `maxPlayers` | `int` | Spielerlimit |
| `playerCount` | `int` | Aktuelle Online-Spieler |
| `properties` | `Map` | Eigene Metadaten |
## ServerState
| Status | Beschreibung |
| ----------- | ------------------------------- |
| `PREPARING` | Template-Dateien werden kopiert |
| `STARTING` | JVM-Prozess startet |
| `AVAILABLE` | Bereit für Spieler |
| `INGAME` | Hat aktive Spieler |
| `STOPPING` | Shutdown läuft |
## Umgebungsvariablen
Innerhalb eines laufenden Servers kannst du Server-Info ohne API abrufen:
```java theme={null}
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 port = System.getenv("SIMPLECLOUD_PORT");
String maxPlayers = System.getenv("SIMPLECLOUD_MAX_PLAYERS");
```