Wardog Servers API

Overzicht

De basis-URL is https://api.wardogservers.com. Elke response is JSON en voor lezen is geen API-sleutel nodig.

Het volledige contract is gepubliceerd als OpenAPI 3.1-document op https://api.wardogservers.com/openapi.json ↗. Dat document is de bron van waarheid; deze pagina is de leesbare samenvatting.

• De collector polt de in-game serverbrowser in elke regio ongeveer eens per minuut. Het huidige interval wordt in elke response gemeld als meta.refreshSeconds.
• Browserverzoeken worden alleen geaccepteerd vanaf wardogservers.com. Roep de API aan vanaf je eigen server, bot of script, niet vanaf een webpagina op een ander domein.
• Onbekende, dubbele of ongeldige queryparameters worden afgewezen met een 400 in plaats van genegeerd, zodat een typefout luid faalt in plaats van stilletjes alles terug te geven.

Snel starten

Drie verzoeken dekken de meeste toepassingen: de totalen op dit moment, de drukste servers die aan een filter voldoen, en één server via het instantie-id.

# Totalen op dit moment
curl https://api.wardogservers.com/v1/stats

# Communityservers in West-Europa met ruimte om te joinen, drukste eerst
curl "https://api.wardogservers.com/v1/servers?region=eu-west&type=community&hideFull=true&limit=10"

# Eén server via het instantie-id
curl https://api.wardogservers.com/v1/servers/$ID

Een ingekorte response van /v1/stats ziet er zo uit:

{
  "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", "…"]
  }
}

Endpoints

Elk leesendpoint accepteert GET en HEAD, respecteert If-None-Match en gebruikt de hieronder beschreven response-envelope.

De serverlijst filteren

Elke parameter op /v1/servers is optioneel. Waarden zijn hoofdlettergevoelig, behalve q.

Response-envelope

Elke geslaagde response bevat data en meta. Het lijstendpoint voegt paginering toe; historie-endpoints voegen een history-object toe dat het venster, de groep, de metric en de bucketgrootte beschrijft.

Controleer meta.stale voordat je cijfers als actueel presenteert. Dit is true wanneer het verzamelen is gepauzeerd of de snapshot ouder is dan refreshSeconds plus 60 seconden. Verouderde responses worden ook verstuurd met Cache-Control: no-store en X-Data-Stale: true.

Het server-object

Dit is de samenvattingsvorm die wordt geretourneerd door /v1/servers en /v1/snapshot. /v1/servers/{id} retourneert dezelfde velden plus attributes, build, level en 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"]
}

Geschiedenis

/v1/history/players retourneert een kolomsgewijze reeks: één array met starttijden van buckets in Unix-seconden en één array met waarden per groepssleutel, uitgelijnd op index. Een null-waarde is een bucket waarin niets is vastgelegd, meestal omdat de collector gepauzeerd was. Toon een gat; interpoleer niet.

Buckets worden één keer per snapshot vastgelegd vanaf het moment dat geschiedenis werd ingeschakeld, zonder terugvullen. Minuutbuckets worden 7 dagen bewaard, vijfminutenbuckets 90 dagen en uurbuckets voor onbepaalde tijd.

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": { "…": "…" }
}

Voor metric=players bevat de response ook een peak-object met de hoogste losse snapshot in elke bucket. Het heatmap-endpoint middelt een metric per UTC-weekdag en -uur over de laatste 28 volledige dagen, optioneel voor één regio. Peaks meldt het hoogste losse-snapshot-spelersaantal, in totaal en per type, aller tijden en voor elk van de laatste 30 UTC-dagen.

Geschiedenis per server

De geschiedenis per server is gekoppeld aan de joincode, die anders dan het instance-id behouden blijft bij herstarts en mapwissels. /v1/history/servers/{serverId} geeft uitgelijnde arrays terug: het gemiddelde aantal spelers en de hoogste losse peiling terwijl de server vermeld stond, de spelerslimiet, het aandeel peilingen in het interval waarin de server voorkwam (de uptime, 0 tot 1) en de map aan het einde van het interval, zodat opeenvolgende mapwaarden de rotatie geven. Het opnemen begint zodra een code voor het eerst wordt gezien, zonder terugwerkende kracht; tot die tijd antwoordt de route met 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 leidt uit opeenvolgende peilingen een wijzigingslog af, nieuwste eerst: tracking_started, online, offline, restart (instance gewisseld zonder gat), build (changelist), map (variant, wereld of lucht), modifiers en limits (level- en cashbereik, wachtwoord en spelerslimiet). Elk event bevat at, kind en before- en after-objecten met alleen de velden die dat soort definiëren, null als er geen eerdere of latere toestand is. limit accepteert 1 tot 500, standaard 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 toont vastgelegde servers, meest recent gezien eerst. q komt exact overeen met een joincode of hoofdletterongevoelig met een laatst bekende naam, en vindt zo een server die nu offline is; live servers hebben hun serverId al in /v1/servers.

Caching en polling

Elke response bevat een ETag. Stuur die terug als If-None-Match en een ongewijzigde snapshot antwoordt met 304 zonder body, wat aan beide kanten vrijwel niets kost. Eén keer per minuut pollen met If-None-Match is het bedoelde patroon.

const res = await fetch('https://api.wardogservers.com/v1/snapshot', {
  headers: lastEtag ? { 'if-none-match': lastEtag } : {}
});
if (res.status === 304) return; // Niets veranderd sinds de laatste poll
lastEtag = res.headers.get('etag');
const { data, meta } = await res.json();
if (meta.stale) console.warn('stale'); // Collector loopt achter; blijf de laatst bekende data tonen

Verse responses worden 15 seconden gecachet aan de rand, zodat pieken van identieke verzoeken goedkoop zijn. Er is nu geen harde rate limit, maar sneller pollen dan meta.refreshSeconds kan geen nieuwere data opleveren en kan in de toekomst worden beperkt. Heb je de hele lijst nodig, haal dan eenmalig /v1/snapshot op en filter lokaal in plaats van door /v1/servers te pagineren.

Fouten

Fouten zijn JSON met een stabiele code en een leesbare boodschap. De boodschap kan veranderen; match op de code.

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

Gebruiksvoorwaarden

De API is gratis voor communityprojecten: Discord-bots, overlays, dashboards, onderzoek. Vermeld Wardog Servers met een link waar je de data publiekelijk toont, en presenteer het niet als officiële data van BULKHEAD of Team17.

De lees-API is geversioneerd onder /v1. Er kunnen binnen een versie nieuwe velden worden toegevoegd, dus tolereer sleutels die je niet herkent. Breaking changes verschijnen als nieuwe versie en worden eerst op deze pagina aangekondigd.

Vragen, een project om te laten zien, of een veld dat je nodig hebt: Discord @xcausxn.