API-Referenz – Endpunkte & Parameter
Echtzeit-Monitoring für Minecraft, CS2 & Rust
Verfügbare Endpunkte
Die ServerPulse REST-API bietet drei primäre Endpunkte für Serverabfragen, Statistiken und Suchanfragen. Alle Anfragen erfolgen über HTTPS auf api.serverpulse.io/v1. Authentifizierung via Bearer-Token im Header.
GET /servers
Ruft eine paginierte Liste aller gelisteten Server ab. Unterstützt Filterung nach Spielmod, Region und Spieleranzahl. Standardseitengröße: 50 Einträge. Rate-Limit: 120 Anfragen/Minute für Free-Tier, 1.000/min für Pro.
GET /stats
Liefert Aggregatstatistiken für einen spezifischen Server oder das gesamte Netzwerk. Enthält Spieler-Peaks, Uptime-Percentile, Ping-Verlauf (7/30/90 Tage) und Mod-Verteilung. Daten werden alle 60 Sekunden aktualisiert.
GET /search
Volltextsuche über Servernamen, Beschreibungen und Mod-Listen. Unterstützt fuzzy matching mit Levenshtein-Distanz ≤ 2. Optionaler Parameter boost_online priorisiert aktive Server. Max. 200 Treffer pro Anfrage.
Request-Parameter
Alle Endpunkte akzeptieren query-parameter. Pflichtparameter sind mit * markiert. Datentypen und Standardwerte sind unten dokumentiert.
| Parameter | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
game |
string | Nein | — | Spielmod-Filter: minecraft-java, minecraft-bedrock, cs2, rust, ark |
region |
string | Nein | — | ISO-3166-1 alpha-2 Code: DE, US, GB, JP, BR |
min_players |
integer | Nein | 0 | Mindestanzahl aktueller Spieler (0–10.000) |
max_players |
integer | Nein | 10000 | Maximale Kapazität des Servers |
page |
integer | Nein | 1 | Seitennummer für Paginierung (≥ 1) |
per_page |
integer | Nein | 50 | Einträge pro Seite (1–100, Free: max. 50) |
sort_by |
string | Nein | players_desc | Sortierung: players_desc, players_asc, name_asc, uptime_desc |
query* |
string | Ja (/search) | — | Suchbegriff für /search-Endpunkt (min. 2 Zeichen) |
boost_online |
boolean | Nein | false | Priorisiert online-Server in Suchergebnissen nur bei /search |
server_id* |
uuid | Ja (/stats) | — | UUID des Zielservers für /stats-Abfragen |
timeframe |
string | Nein | 7d | Zeitfenster für Statistiken: 24h, 7d, 30d, 90d |
Response-Beispiele
Alle Antworten werden als JSON mit application/json Content-Type zurückgegeben. Erfolgsantworten verwenden HTTP 200, Fehler 4xx/5xx mit strukturierter Fehlermeldung.
GET /servers?page=1&game=cs2
Beispielantwort für eine paginierte Serverliste mit CS2-Filter. Das Feld meta.pagination enthält Navigationslinks für die Paginierung. Jeder Servereintrag enthält die UUID, aktuellen Spielerstand, Host-Informationen und ein status-Flag.
{
"data": [
{
"id": "a3f8c1d2-9b4e-4a71-b8c3-2e5f6a1d0c9b",
"name": "PhoenixStrike | CS2 Competitive 5v5",
"game": "cs2",
"host": "eu-central.phoenixstrike.net",
"port": 27015,
"players": { "current": 14, "max": 24 },
"region": "DE",
"status": "online",
"map": "de_mirage",
"uptime_percent": 99.7,
"last_seen": "2025-01-15T14:32:11Z"
},
{
"id": "b7e2d4f1-3c8a-4e92-a1d5-8f3b7c2e6a0d",
"name": "NordicArena | CS2 Retakes & Surf",
"game": "cs2",
"host": "nordic-1.nordicarena.gg",
"port": 27016,
"players": { "current": 8, "max": 16 },
"region": "SE",
"status": "online",
"map": "surf_phantasm",
"uptime_percent": 98.2,
"last_seen": "2025-01-15T14:31:58Z"
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 50,
"total": 347,
"total_pages": 7
},
"request_id": "req_8f2a1b3c4d5e6f7g"
}
}
{
"data": {
"server_id": "a3f8c1d2-9b4e-4a71-b8c3-2e5f6a1d0c9b",
"name": "PhoenixStrike | CS2 Competitive 5v5",
"stats": {
"players": {
"current": 14,
"peak_24h": 24,
"peak_7d": 24,
"average_7d": 11.3
},
"uptime": {
"percent_7d": 99.7,
"percent_30d": 99.4,
"downtime_events_30d": 2,
"total_downtime_minutes_30d": 126
},
"ping": {
"median_ms": 18,
"p95_ms": 42,
"p99_ms": 67
},
"maps_played_7d": [
{ "name": "de_mirage", "rounds": 412 },
{ "name": "de_inferno", "rounds": 387 },
{ "name": "de_dust2", "rounds": 351 }
]
},
"timeframe": "7d",
"last_updated": "2025-01-15T14:32:11Z"
}
}
{
"data": {
"query": "rust survival",
"total_matches": 89,
"results": [
{
"id": "c9d1e3f5-7a2b-4c8d-9e1f-3a5b7c9d1e2f",
"name": "Ironwood Rust | 1000x Wipe Mo-Fr",
"game": "rust",
"relevance_score": 0.94,
"players": { "current": 187, "max": 500 },
"region": "US",
"status": "online",
"mods": ["RustIO", "Porkbun", "Extended Inventory"],
"last_wipe": "2025-01-13T18:00:00Z"
}
]
},
"meta": {
"request_id": "req_2d4e6f8a0b1c3d5e",
"processing_ms": 23
}
}