API do Wardog Servers

Visão geral

A URL base é https://api.wardogservers.com. Toda resposta é JSON e leituras não precisam de chave de API.

O contrato completo é publicado como um documento OpenAPI 3.1 em https://api.wardogservers.com/openapi.json ↗. Esse documento é a fonte da verdade; esta página é o resumo legível.

• O coletor consulta o navegador de servidores do jogo em cada região cerca de uma vez por minuto. O intervalo atual é informado em cada resposta como meta.refreshSeconds.
• Requisições de navegador só são aceitas a partir de wardogservers.com. Chame a API a partir do seu próprio servidor, bot ou script, não de uma página web em outro domínio.
• Parâmetros de consulta desconhecidos, duplicados ou malformados são rejeitados com um 400 em vez de ignorados, então um erro de digitação falha visivelmente em vez de retornar tudo silenciosamente.

Início rápido

Três requisições cobrem a maioria dos usos: os totais agora, os servidores mais cheios que correspondem a um filtro, e um servidor pelo id da instância.

# Totais agora
curl https://api.wardogservers.com/v1/stats

# Servidores da comunidade na Europa Ocidental com vagas para entrar, mais cheios primeiro
curl "https://api.wardogservers.com/v1/servers?region=eu-west&type=community&hideFull=true&limit=10"

# Um servidor pelo id da instância
curl https://api.wardogservers.com/v1/servers/$ID

Uma resposta reduzida de /v1/stats se parece com isto:

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

Todo endpoint de leitura aceita GET e HEAD, respeita If-None-Match, e usa o envelope de resposta descrito abaixo.

Filtrando a lista de servidores

Todo parâmetro em /v1/servers é opcional. Os valores diferenciam maiúsculas de minúsculas, exceto q.

Envelope de resposta

Toda resposta bem-sucedida carrega data e meta. O endpoint de lista adiciona pagination; os endpoints de histórico adicionam um objeto history descrevendo window, group, metric e o tamanho do bucket.

Verifique meta.stale antes de apresentar os números como atuais. É true quando a coleta foi pausada ou o snapshot é mais antigo que refreshSeconds mais 60 segundos. Respostas desatualizadas também são enviadas com Cache-Control: no-store e X-Data-Stale: true.

O objeto do servidor

Este é o formato resumido retornado por /v1/servers e /v1/snapshot. /v1/servers/{id} retorna os mesmos campos além de attributes, build, level e 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"]
}

Histórico

/v1/history/players retorna uma série em colunas: um array com os horários de início de cada bucket em segundos Unix e um array de valores por chave de group, alinhados por índice. Um valor null é um bucket em que nada foi registrado, geralmente porque o coletor estava pausado. Mostre uma lacuna; não interpole.

Buckets são registrados uma vez por snapshot a partir do momento em que o histórico foi ativado, sem preenchimento retroativo. Buckets de um minuto são mantidos por 7 dias, buckets de cinco minutos por 90 dias e buckets por 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 a resposta também carrega um objeto peak com o maior valor de um único snapshot em cada bucket. O endpoint heatmap calcula a média de uma métrica por dia da semana e hora em UTC nos últimos 28 dias completos, opcionalmente para uma região. Peaks reporta a maior contagem de jogadores de um único snapshot, geral e por tipo, de todos os tempos e para cada um dos últimos 30 dias UTC.

Histórico por servidor

O histórico por servidor é indexado pelo código de entrada, que persiste entre reinícios e trocas de mapa, ao contrário do id de instância. /v1/history/servers/{serverId} retorna arrays alinhados: a média de jogadores e o maior valor de uma única consulta enquanto o servidor estava listado, seu limite de jogadores, a parcela de consultas do intervalo em que ele apareceu (sua disponibilidade, de 0 a 1) e o mapa no fim do intervalo, de modo que valores consecutivos de mapa dão a rotação. A gravação começa na primeira vez que um código é visto, sem preenchimento retroativo, e até então a rota 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 um registro de mudanças de consultas consecutivas, as mais recentes primeiro: tracking_started, online, offline, restart (a instância mudou sem lacuna), build (changelist), map (variante, mundo ou céu), modifiers e limits (faixas de nível e dinheiro, senha e limite de jogadores). Cada evento traz at, kind e os objetos before e after apenas com os campos que definem aquele tipo, null quando não há estado anterior ou posterior. limit aceita de 1 a 500 e o padrão é 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 os servidores registrados, os vistos mais recentemente primeiro. q corresponde exatamente a um código de entrada ou a um último nome conhecido sem diferenciar maiúsculas, então encontra um servidor que está fora do ar agora; servidores ao vivo já trazem seu serverId em /v1/servers.

Cache e consultas

Toda resposta carrega um ETag. Envie-o de volta como If-None-Match e um snapshot inalterado responde 304 sem corpo, o que custa quase nada para nenhum dos lados. Uma consulta uma vez por minuto com If-None-Match é o padrão pretendido.

const res = await fetch('https://api.wardogservers.com/v1/snapshot', {
  headers: lastEtag ? { 'if-none-match': lastEtag } : {}
});
if (res.status === 304) return; // Nada mudou desde a última consulta
lastEtag = res.headers.get('etag');
const { data, meta } = await res.json();
if (meta.stale) console.warn('stale'); // O coletor está atrasado; continue mostrando os últimos dados conhecidos

Respostas atualizadas ficam em cache na borda por 15 segundos, então rajadas de requisições idênticas são baratas. Hoje não há um limite de taxa rígido, mas consultar mais rápido que meta.refreshSeconds não pode retornar dados mais novos e pode ser limitado no futuro. Se você precisa da lista completa, busque /v1/snapshot uma vez e filtre localmente em vez de paginar por /v1/servers.

Erros

Os erros são JSON com um code estável e uma message legível por humanos. A message pode mudar; use o code para comparação.

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

Termos de uso

A API é gratuita para projetos da comunidade: bots do Discord, overlays, dashboards, pesquisa. Credite o Wardog Servers com um link onde você mostrar os dados publicamente, e não os apresente como dados oficiais da BULKHEAD ou da Team17.

A API de leitura é versionada sob /v1. Novos campos podem ser adicionados dentro de uma versão, então tolere chaves que você não reconhece. Mudanças incompatíveis serão lançadas como uma nova versão e anunciadas primeiro nesta página.

Perguntas, um projeto para mostrar, ou um campo que você precisa: Discord @xcausxn.