Wardog Servers API

Resumen

La URL base es https://api.wardogservers.com. Todas las respuestas son JSON y las lecturas no necesitan clave de API.

El contrato completo se publica como un documento OpenAPI 3.1 en https://api.wardogservers.com/openapi.json ↗. Ese documento es la fuente de verdad; esta página es el resumen legible.

• El recolector consulta el navegador de servidores del juego en cada región aproximadamente una vez por minuto. El intervalo actual se indica en cada respuesta como meta.refreshSeconds.
• Las solicitudes desde el navegador solo se aceptan desde wardogservers.com. Llama a la API desde tu propio servidor, bot o script, no desde una página web en otro dominio.
• Los parámetros de consulta desconocidos, duplicados o mal formados se rechazan con un 400 en lugar de ignorarse, así que una errata falla de forma visible en lugar de devolver todo silenciosamente.

Inicio rápido

Tres solicitudes cubren la mayoría de los usos: los totales ahora mismo, los servidores con más jugadores que coinciden con un filtro y un servidor por su id de instancia.

# Totales ahora mismo
curl https://api.wardogservers.com/v1/stats

# Servidores de la comunidad en Europa Occidental con plazas libres, los más concurridos primero
curl "https://api.wardogservers.com/v1/servers?region=eu-west&type=community&hideFull=true&limit=10"

# Un servidor por id de instancia
curl https://api.wardogservers.com/v1/servers/$ID

Una respuesta recortada de /v1/stats tiene este aspecto:

{
  "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

Todos los endpoints de lectura aceptan GET y HEAD, respetan If-None-Match y usan la estructura de respuesta que se describe más abajo.

Filtrar la lista de servidores

Todos los parámetros de /v1/servers son opcionales. Los valores distinguen mayúsculas y minúsculas excepto q.

Estructura de la respuesta

Toda respuesta correcta incluye data y meta. El endpoint de lista añade paginación; los endpoints de historial añaden un objeto history que describe la ventana, el grupo, la métrica y el tamaño del bucket.

Comprueba meta.stale antes de presentar los números como actuales. Es true cuando la recolección se ha pausado o el snapshot es más antiguo que refreshSeconds más 60 segundos. Las respuestas obsoletas también se envían con Cache-Control: no-store y X-Data-Stale: true.

El objeto de servidor

Esta es la forma resumida que devuelven /v1/servers y /v1/snapshot. /v1/servers/{id} devuelve los mismos campos más atributos, build, nivel y dinero.

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

Historial

/v1/history/players devuelve una serie columnar: un array con los tiempos de inicio de cada bucket en segundos Unix y un array de valores por clave de grupo, alineados por índice. Un valor null es un bucket en el que no se registró nada, normalmente porque el recolector estaba en pausa. Muestra un hueco; no interpoles.

Los buckets se registran una vez por snapshot desde el momento en que se activó el historial, sin relleno retroactivo. Los buckets de un minuto se conservan 7 días, los de cinco minutos 90 días y los de una hora indefinidamente.

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

Para metric=players la respuesta también incluye un objeto peak con el snapshot más alto de cada bucket. El endpoint heatmap calcula la media de una métrica por día de la semana y hora en UTC durante los últimos 28 días completos, opcionalmente para una región. Peaks reporta el número de jugadores más alto de un solo snapshot, en total y por tipo, histórico y para cada uno de los últimos 30 días UTC.

Historial por servidor

El historial por servidor se indexa por el código de unión, que se conserva entre reinicios y cambios de mapa, a diferencia del id de instancia. /v1/history/servers/{serverId} devuelve arrays alineados: la media de jugadores y el máximo de un solo sondeo mientras el servidor estaba listado, su límite de jugadores, la proporción de sondeos del intervalo en los que apareció (su tiempo activo, de 0 a 1) y el mapa al final del intervalo, de modo que los valores consecutivos de mapa dan la rotación. El registro empieza la primera vez que se ve un código, sin datos retroactivos, y hasta entonces la ruta responde 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 deriva un registro de cambios a partir de sondeos consecutivos, los más recientes primero: tracking_started, online, offline, restart (la instancia cambió sin hueco), build (changelist), map (variante, mundo o cielo), modifiers y limits (rangos de nivel y dinero, contraseña y límite de jugadores). Cada evento lleva at, kind y los objetos before y after con solo los campos que definen ese tipo, null cuando no hay estado anterior o posterior. limit acepta de 1 a 500 y por defecto es 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 lista los servidores registrados, los vistos más recientemente primero. q coincide con un código de unión de forma exacta o con un último nombre conocido sin distinguir mayúsculas, así que encuentra un servidor que ahora mismo está desconectado; los servidores en vivo ya llevan su serverId en /v1/servers.

Caché y sondeo

Toda respuesta incluye un ETag. Envíalo de vuelta como If-None-Match, y un snapshot sin cambios responde con 304 sin cuerpo, lo que apenas cuesta nada en ningún lado. El patrón previsto es una consulta por minuto con If-None-Match.

const res = await fetch('https://api.wardogservers.com/v1/snapshot', {
  headers: lastEtag ? { 'if-none-match': lastEtag } : {}
});
if (res.status === 304) return; // Nada cambió desde la última consulta
lastEtag = res.headers.get('etag');
const { data, meta } = await res.json();
if (meta.stale) console.warn('stale'); // El recolector va con retraso; sigue mostrando los últimos datos conocidos

Las respuestas nuevas se cachean en el edge durante 15 segundos, así que las ráfagas de solicitudes idénticas salen baratas. Hoy no hay un límite de frecuencia estricto, pero consultar más rápido que meta.refreshSeconds no puede devolver datos más nuevos y podría limitarse en el futuro. Si necesitas la lista completa, obtén /v1/snapshot una vez y filtra localmente en lugar de paginar por /v1/servers.

Errores

Los errores son JSON con un code estable y un message legible para humanos. El message puede cambiar; compara por el code.

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

Condiciones de uso

La API es gratuita para proyectos de la comunidad: bots de Discord, overlays, paneles, investigación. Da crédito a Wardog Servers con un enlace donde muestres los datos públicamente, y no los presentes como datos oficiales de BULKHEAD o Team17.

La API de lectura está versionada bajo /v1. Pueden añadirse campos nuevos dentro de una versión, así que tolera las claves que no reconozcas. Los cambios incompatibles se publicarán como una nueva versión y se anunciarán antes en esta página.

Preguntas, un proyecto para presumir o un campo que necesites: Discord @xcausxn.