Wardog Servers API

Überblick

Die Basis-URL ist https://api.wardogservers.com. Jede Antwort ist JSON, und Lesezugriffe benötigen keinen API-Key.

Der vollständige Vertrag wird als OpenAPI-3.1-Dokument veröffentlicht unter https://api.wardogservers.com/openapi.json ↗. Dieses Dokument ist die maßgebliche Quelle; diese Seite ist die lesbare Zusammenfassung.

• Der Collector fragt den Serverbrowser im Spiel in jeder Region etwa einmal pro Minute ab. Das aktuelle Intervall wird in jeder Antwort als meta.refreshSeconds gemeldet.
• Browseranfragen werden nur von wardogservers.com akzeptiert. Rufe die API von deinem eigenen Server, Bot oder Skript auf, nicht von einer Webseite auf einer anderen Domain.
• Unbekannte, doppelte oder fehlerhafte Query-Parameter werden mit 400 abgelehnt statt ignoriert, sodass sich ein Tippfehler deutlich bemerkbar macht, statt still alles zurückzugeben.

Schnellstart

Drei Anfragen decken die meisten Anwendungsfälle ab: die aktuellen Gesamtzahlen, die vollsten Server zu einem Filter und ein einzelner Server über seine Instanz-ID.

# Aktuelle Gesamtzahlen
curl https://api.wardogservers.com/v1/stats

# Community-Server in Westeuropa mit freien Plätzen, vollste zuerst
curl "https://api.wardogservers.com/v1/servers?region=eu-west&type=community&hideFull=true&limit=10"

# Ein Server über die Instanz-ID
curl https://api.wardogservers.com/v1/servers/$ID

Eine gekürzte Antwort von /v1/stats sieht so aus:

{
  "data": {
    "serverCount": 3544,
    "playerCount": 252109,
    "officialServerCount": 2765,
    "communityServerCount": 779
  },
  "meta": {
    "fetchedAt": "2026-09-13T12:54:57.302Z",
    "snapshotId": "95635cb938811a34…",
    "refreshSeconds": 60,
    "stale": false,
    "requestedRegions": ["asia-east", "asia-southeast", "…"],
    "observedRegions": ["asia-east", "asia-west", "…"]
  }
}

Endpunkte

Jeder Lese-Endpunkt akzeptiert GET und HEAD, respektiert If-None-Match und verwendet die unten beschriebene Antwortstruktur.

Die Serverliste filtern

Jeder Parameter bei /v1/servers ist optional. Werte unterscheiden Groß-/Kleinschreibung, außer bei q.

Antwortstruktur

Jede erfolgreiche Antwort enthält data und meta. Der Listen-Endpunkt ergänzt pagination; History-Endpunkte ergänzen ein history-Objekt, das window, group, metric und die Bucket-Größe beschreibt.

Prüfe meta.stale, bevor du Zahlen als aktuell darstellst. Es ist true, wenn die Erfassung pausiert hat oder der Snapshot älter ist als refreshSeconds plus 60 Sekunden. Veraltete Antworten werden außerdem mit Cache-Control: no-store und X-Data-Stale: true gesendet.

Das Server-Objekt

Dies ist die Kurzform, die /v1/servers und /v1/snapshot liefern. /v1/servers/{id} liefert dieselben Felder plus attributes, build, level und cash.

{
  "id": "001ab36e-9985-4a9c-8dff-9dc137826dfe",
  "serverId": "756872",
  "serverIdUpdatedAt": "2026-09-13T11:14:32.995Z",
  "name": "Official #4",
  "nativeName": "f14859cce268",
  "type": "official",
  "region": "eu-south",
  "players": 100,
  "maxPlayers": 100,
  "reservedPlayers": 0,
  "passwordProtected": false,
  "serverNumber": 4,
  "map": { "variant": "Bakurani", "base": "Europe" },
  "mode": { "experience": "Bakurani_KOTH_01", "gameMode": "GM_Session_C", "modifiers": [] },
  "rulesets": ["standard"]
}

Verlauf

/v1/history/players liefert eine spaltenweise Zeitreihe: ein Array mit den Startzeiten der Buckets in Unix-Sekunden und ein Array mit Werten pro Gruppenschlüssel, per Index zugeordnet. Ein null-Wert ist ein Bucket, in dem nichts erfasst wurde, meist weil der Collector pausiert war. Zeige eine Lücke; interpoliere nicht.

Buckets werden einmal pro Snapshot ab dem Moment erfasst, an dem der Verlauf aktiviert wurde, ohne rückwirkende Befüllung. Minuten-Buckets werden 7 Tage aufbewahrt, Fünf-Minuten-Buckets 90 Tage und Stunden-Buckets unbegrenzt.

GET /v1/history/players?window=24h&group=type

{
  "data": {
    "t": [1789217880, 1789217940, 1789218000, "…"],
    "series": {
      "official": [248112, 248390, null, "…"],
      "community": [3902, 3911, null, "…"]
    },
    "peak": { "official": ["…"], "community": ["…"] }
  },
  "history": {
    "window": "24h", "group": "type", "metric": "players",
    "step": 60, "from": 1789217880, "to": 1789304280, "since": 1789257600
  },
  "meta": { "…": "…" }
}

Bei metric=players enthält die Antwort außerdem ein peak-Objekt mit dem höchsten Einzelwert je Bucket-Snapshot. Der Heatmap-Endpunkt mittelt eine Kennzahl nach UTC-Wochentag und -Stunde über die letzten 28 vollen Tage, optional für eine einzelne Region. Peaks meldet die höchste Einzelsnapshot-Spielerzahl insgesamt und pro Typ, für alle Zeit und für jeden der letzten 30 UTC-Tage.

Verlauf pro Server

Der Verlauf pro Server ist über den Beitrittscode indiziert, der anders als die Instanz-ID über Neustarts und Kartenwechsel hinweg erhalten bleibt. /v1/history/servers/{serverId} liefert ausgerichtete Arrays: durchschnittliche Spieler und den höchsten Einzelwert, während der Server gelistet war, sein Spielerlimit, den Anteil der Abfragen im Intervall, in denen er gelistet war (seine Verfügbarkeit, 0 bis 1) und die Karte am Ende des Intervalls, sodass aufeinanderfolgende Kartenwerte die Rotation ergeben. Die Aufzeichnung beginnt, sobald ein Code zum ersten Mal gesehen wird, ohne Rückwirkung; bis dahin antwortet die Route mit 404.

GET /v1/history/servers/756872?window=24h

{
  "data": {
    "server": {
      "serverId": "756872",
      "name": "Official #4",
      "type": "official",
      "region": "eu-south",
      "instanceId": "001ab36e-9985-4a9c-8dff-9dc137826dfe",
      "firstSeen": "2026-09-13T00:00:39.000Z",
      "lastSeen": "2026-09-14T11:53:22.000Z",
      "samples": 2132,
      "live": true
    },
    "t": [1789300800, 1789301100, 1789301400, "…"],
    "players": [100, 98, null, "…"],
    "peak": [100, 100, null, "…"],
    "capacity": [100, 100, null, "…"],
    "online": [1, 0.8, null, "…"],
    "map": ["Bakurani", "Bakurani", null, "…"]
  },
  "history": {
    "window": "24h", "step": 300,
    "from": 1789300800, "to": 1789387200, "since": 1789257600
  },
  "meta": { "…": "…" }
}

/v1/history/servers/{serverId}/events leitet aus aufeinanderfolgenden Abfragen ein Änderungsprotokoll ab, neueste zuerst: tracking_started, online, offline, restart (Instanz ohne Lücke gewechselt), build (Changelist), map (Variante, Welt oder Himmel), modifiers und limits (Level- und Geldbereiche, Passwort und Spielerlimit). Jedes Ereignis trägt at, kind sowie before- und after-Objekte mit nur den Feldern, die diese Art definieren, null wenn es keinen früheren oder späteren Zustand gibt. limit nimmt 1 bis 500, Standard 100.

GET /v1/history/servers/756872/events?limit=3

{
  "data": {
    "server": { "serverId": "756872", "name": "Official #4", "…": "…" },
    "events": [
      {
        "at": "2026-09-14T12:40:30.000Z",
        "kind": "map",
        "before": { "map": "Madrid", "world": "Europe", "sky": "DayEarlyFog" },
        "after": { "map": "Detroit", "world": "Europe", "sky": "DayLateGray" }
      },
      {
        "at": "2026-09-14T09:12:04.000Z",
        "kind": "restart",
        "before": { "instanceId": "001ab36e-9985-4a9c-8dff-9dc137826dfe" },
        "after": { "instanceId": "7c1e0b52-3d9a-4e1f-9b6e-2f4c8a9d0e11" }
      },
      {
        "at": "2026-09-13T00:00:39.000Z",
        "kind": "tracking_started",
        "before": null,
        "after": { "instanceId": "…", "changelist": "501228", "map": "Bakurani", "…": "…" }
      }
    ]
  },
  "history": { "limit": 3, "since": 1789257600 },
  "meta": { "…": "…" }
}

/v1/history/servers listet erfasste Server, zuletzt gesehene zuerst. q trifft einen Beitrittscode exakt oder einen zuletzt bekannten Namen ohne Beachtung der Groß- und Kleinschreibung und findet so einen Server, der gerade offline ist; laufende Server tragen ihre serverId bereits in /v1/servers.

Caching und Abfragen

Jede Antwort enthält einen ETag. Sende ihn als If-None-Match zurück, und ein unveränderter Snapshot antwortet mit 304 ohne Body, was auf beiden Seiten fast nichts kostet. Ein einmal pro Minute erfolgender Abruf mit If-None-Match ist das vorgesehene Muster.

const res = await fetch('https://api.wardogservers.com/v1/snapshot', {
  headers: lastEtag ? { 'if-none-match': lastEtag } : {}
});
if (res.status === 304) return; // Nichts hat sich seit der letzten Abfrage geändert
lastEtag = res.headers.get('etag');
const { data, meta } = await res.json();
if (meta.stale) console.warn('stale'); // Collector hinkt hinterher; zeige weiterhin die zuletzt bekannten Daten

Frische Antworten werden am Edge für 15 Sekunden zwischengespeichert, sodass Bursts identischer Anfragen kaum ins Gewicht fallen. Derzeit gibt es kein hartes Rate-Limit, aber schneller abzufragen als meta.refreshSeconds liefert keine neueren Daten und kann künftig gedrosselt werden. Wenn du die gesamte Liste brauchst, rufe /v1/snapshot einmal ab und filtere lokal, statt dich durch /v1/servers zu paginieren.

Fehler

Fehler sind JSON mit einem stabilen code und einer menschenlesbaren message. Die message kann sich ändern; prüfe anhand des code.

{
  "error": {
    "code": "bad_request",
    "message": "An unsupported query parameter was supplied."
  }
}

Nutzungsbedingungen

Die API ist kostenlos für Community-Projekte: Discord-Bots, Overlays, Dashboards, Recherche. Nenne Wardog Servers mit einem Link, wo immer du die Daten öffentlich zeigst, und stelle sie nicht als offizielle Daten von BULKHEAD oder Team17 dar.

Die Lese-API ist unter /v1 versioniert. Innerhalb einer Version können neue Felder hinzukommen, toleriere also Schlüssel, die du nicht kennst. Breaking Changes erscheinen als neue Version und werden zuerst auf dieser Seite angekündigt.

Fragen, ein Projekt zum Zeigen oder ein Feld, das du brauchst: Discord @xcausxn.