REST API

Documentação da API

Integre dados de servidor, player, skin e comunidade do Minecraft ao vivo do mcstat.org em seus próprios aplicativos, bots e painéis.

URL base

Todas as solicitações de API começam com este URL base

https://mcstat.org/api/v1

Ver como Markdown

Documentação Markdown em bruto para IAs, bots e ferramentas

Chaves de API

Gerencie e monitore suas chaves de API

Crie, alterne e visualize análises de suas chaves de API no painel.

Abrir painel de chave de API

Parque de APIs

Teste endpoints diretamente no navegador

Verificação de bot

Este espaço de testes não requer uma chave de API; é necessária verificação humana para reduzir abusos.

Ponto final

GET

/api/v1/servers

Parâmetros de consulta

page

integer

limit

integer

sort

string

search

string

country

string

version

string

tag

string

mode

string

minPlayers

integer

maxPlayers

integer

minUptime

number

minVotes

integer

minRating

number

onlineOnly

boolean

Solicitar URL

https://mcstat.org/api/v1/servers

Execute uma solicitação para ver a resposta

Autenticação

Todos os endpoints de API públicos documentados exigem uma chave de API. Envie sua chave no cabeçalho X-API-Key.

Cabeçalho da solicitação

Adicione este cabeçalho para autenticar

X-API-Key: mcs_your_key_here

Ou como parâmetro de consulta

Ou passe como parâmetro de consulta

?api_key=mcs_your_key_here

Limites de taxa

As solicitações são autenticadas por chave de API. Uma chave ausente ou inválida retorna HTTP 401, uma chave desabilitada retorna HTTP 403 e um limite excedido retorna HTTP 429.

Sem chave API

Não permitido

Com chave API

60 solicitações por minuto, 1.000 por dia e 30.000 por mês por padrão. Exceder um limite retorna HTTP 429 com cabeçalhos X-RateLimit-* mostrando seus limites e um Retry-After informando quando a janela for reiniciada. Limites mais elevados podem ser concedidos por chave, mediante solicitação.

Cabeçalhos de limite de taxa:Uma resposta 429 carrega X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month e Retry-After. As respostas bem-sucedidas carregam um cabeçalho Cache-Control para que você possa armazenar em cache os resultados com segurança no lado do cliente.

Formato de resposta

Cada resposta bem-sucedida é JSON com um booleano e um objeto . Os erros usam o mesmo envelope com : falso.

Resposta de sucesso

JSON

{
  "success": true,
  "data": {
    "resource": {
      "id": "...",
      "name": "Example"
    }
  }
}

Resposta de erro

JSON

{
  "success": false,
  "error": "Too many requests"
}

Erros

São usados códigos de status HTTP padrão. Casos comuns:

Código	Significado
`400`	Solicitação incorreta – parâmetros inválidos
`401`	Não autorizado – chave de API ausente ou inválida
`403`	Proibido – chave de API desativada
`404`	Não encontrado — o recurso não existe
`429`	Muitas solicitações — limite de taxa excedido
`500`	Erro interno do servidor – tente novamente mais tarde

Pontos de extremidade do servidor

Navegue, filtre e inspecione servidores Minecraft rastreados por mcstat.org.

GET

/api/v1/servers

Listar servidores

Lista paginada de servidores públicos com filtros avançados.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`20`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`search`	`string`	Não	`-`	Consulta de texto livre.
`country`	`string`	Não	`-`	Filtro de nome de país ISO.
`version`	`string`	Não	`-`	Filtro de versão do Minecraft.
`tag`	`string`	Não	`-`	Filtre por tag.
`mode`	`string`	Não	`-`	Filtro de modo de jogo.
`minPlayers`	`integer`	Não	`-`	Contagem mínima atual de jogadores.
`maxPlayers`	`integer`	Não	`-`	Contagem máxima de jogadores atuais.
`minUptime`	`number`	Não	`-`	Porcentagem mínima de tempo de atividade.
`minVotes`	`integer`	Não	`-`	Contagem total mínima de votos.
`minRating`	`number`	Não	`-`	Classificação mínima (1–5).
`onlineOnly`	`boolean`	Não	`-`	Inclui apenas relatórios de servidores online.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "shortDescription": "Home of over 35 unique games…",
        "ip": "mc.hypixel.net",
        "port": 25565,
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "motd": "Hypixel Network",
        "website": null,
        "discordUrl": null,
        "visibility": "PUBLIC",
        "isOnline": true,
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "version": "Requires MC 1.8 / 1.21",
        "latency": 42,
        "lastPing": "2026-05-24T22:00:00Z",
        "country": "United States",
        "tags": [
          "bedwars",
          "pvp",
          "skyblock"
        ],
        "gameMode": null,
        "uptime": 100,
        "trend": 3.4,
        "totalVotes": 12345,
        "rating": 4.6,
        "createdAt": "2026-04-28T05:44:26Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/servers/{slug}

Detalhe do servidor

Perfil completo do servidor: histórico de estatísticas, tempo de atividade, gráfico de votos, classificações.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`period`	`string`	Não	`24h`	Janela de tempo: 24h, 7d, 30d, 90d, all-time.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "server": {
      "id": "JS6o0w88QP6oZHDj",
      "slug": "mchypixelnet",
      "name": "Hypixel Network",
      "ip": "mc.hypixel.net",
      "port": 25565,
      "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
      "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
      "motd": "Hypixel Network",
      "motdRaw": "§aHypixel §7Network",
      "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
      "website": null,
      "discordUrl": null,
      "storeUrl": null,
      "youtubeUrl": null,
      "currentPlayers": 48230,
      "maxPlayers": 200000,
      "isOnline": true,
      "country": "United States",
      "version": "Requires MC 1.8 / 1.21",
      "protocol": 767,
      "uptime": 100,
      "rating": 4.6,
      "totalVotes": 12345,
      "tags": [
        "bedwars",
        "pvp"
      ],
      "owner": null,
      "latestStats": {
        "onlinePlayers": 48230,
        "tps": 20,
        "timestamp": "2026-05-24T22:00:00Z"
      },
      "statsHistory": [
        {
          "timestamp": "2026-05-24T21:00:00Z",
          "onlinePlayers": 47000
        }
      ],
      "periodStats": {
        "24h": {
          "avgPlayers": 46500,
          "peakPlayers": 49100,
          "minPlayers": 42000,
          "uptimePct": 99.95
        }
      },
      "voteStats": {
        "24h": 412,
        "7d": 2890,
        "30d": 11200,
        "90d": 30150
      },
      "dailyVotes": [
        {
          "day": "2026-05-23",
          "votes": 405
        }
      ]
    }
  }
}

GET

/api/v1/servers/{slug}/voters

Eleitores do servidor

Eleitores recentes (autenticados e anônimos) para um determinado servidor.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/voters"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`7`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "voters": [
      {
        "id": "TanfrbogDfzGdrgD",
        "minecraftUsername": "Notch",
        "votedAt": "2026-05-24 22:10:06.544",
        "type": "auth",
        "playerId": "xq5-Lw8xk7pEdKyn",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "skinUrl": "http://textures.minecraft.net/texture/cbea0a15a5ce…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "siteUsername": "notch"
      }
    ],
    "total": 12345,
    "page": 1,
    "totalPages": 515,
    "latestVoteAt": "2026-05-24 22:10:06.544"
  }
}

GET

/api/v1/servers/{slug}/reviews

Avaliações do servidor

Avaliações e classificações de jogadores paginadas de um servidor.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/reviews"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`5`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "5g4VgYUiN4n28qcX",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": null,
        "minecraftUsername": "chibibara",
        "rating": 3,
        "content": "Great community!",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z",
        "user": {
          "id": null,
          "username": "chibibara",
          "avatar": null,
          "role": "USER"
        },
        "playerId": "suTEw8opOK2bGP-L",
        "playerMainNickname": "chibibara",
        "playerMinecraftUuid": "019f1b29-fcbe-705b-8efb-8c08b4e0fd9c",
        "playerSkinUrl": null,
        "playerSkinModel": "classic",
        "playerLinkedSkinPngPath": "https://mcstat.org/media/skins/published/default-steve.png"
      }
    ],
    "total": 128,
    "page": 1,
    "totalPages": 26,
    "avgRating": 4.2,
    "latestReviewAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/{slug}/updates

Novidades do servidor

Publicações de notícias e atualizações aprovadas de um servidor.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/updates"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`3`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "updates": [
      {
        "id": "Xk3pQ2mNbV8zR1sd",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": "Nf3kPq8sT2wVxJ7b",
        "title": "Season 5 is live!",
        "content": "New map, new kits, double XP weekend.",
        "status": "APPROVED",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "totalPages": 4,
    "latestUpdateAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/top

Principais servidores

Lista de tendências otimizada para uso na página inicial/widget.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/top"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`sort`	`string`	Não	`votes`	Ordem de classificação.
`limit`	`integer`	Não	`10`	Itens por página.
`country`	`string`	Não	`-`	Filtro de nome de país ISO.
`gameMode`	`string`	Não	`-`	Filtro de modo de jogo.

Resposta de exemplo

JSON

{
  "servers": [
    {
      "id": "JS6o0w88QP6oZHDj",
      "slug": "mchypixelnet",
      "name": "Hypixel Network",
      "ip": "mc.hypixel.net",
      "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
      "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
      "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
      "currentPlayers": 48230,
      "maxPlayers": 200000,
      "isOnline": true,
      "country": "United States",
      "totalVotes": 12345,
      "uptime": 100,
      "trend": 3.4,
      "recentVotes": 412,
      "hotScore": 9821
    }
  ],
  "total": 1240,
  "sort": "hot"
}

GET

/api/v1/servers/countries

Países servidores

Contagem agregada de servidores agrupados por país.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/countries"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "countries": [
      {
        "country": "United States",
        "serverCount": 2840
      }
    ]
  }
}

GET

/api/v1/servers/versions

Versões de servidor

Contagem agregada de servidores agrupados por versão do Minecraft.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/versions"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "versions": [
      {
        "version": "Paper 1.21.11",
        "serverCount": 980
      }
    ]
  }
}

Pontos de extremidade do jogador

Procure perfis de jogadores, sessões, níveis e histórico.

GET

/api/v1/players

Listar jogadores

Diretório de player público paginado.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`-`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`search`	`string`	Não	`-`	Consulta de texto livre.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "players": [
      {
        "id": "h6tC6lGfBEDulI8o",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "mainNickname": "Notch",
        "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "country": "United States",
        "tierOverall": "HT1",
        "tierPoints": 9820,
        "tierRank": 12,
        "lastTierSyncAt": "2026-05-24T20:00:00Z",
        "createdAt": "2026-04-01T10:00:00Z",
        "totalPlayTime": 184320,
        "sessionCount": 412
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/players/{id}

Detalhe do jogador

Perfil, sessões recentes, servidores jogados, K/D, conquistas.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players/069a79f4-44e9-4726-a5be-fca90e38aaf5"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`id`	`string`	Sim	`-`	ID do jogador, UUID ou apelido.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "player": {
      "id": "h6tC6lGfBEDulI8o",
      "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
      "mainNickname": "Notch",
      "nicknameHistory": [
        "Notch"
      ],
      "country": null,
      "skinModel": "classic",
      "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
      "linkedSkinId": "Wi_n1dUvFqgJs0aP",
      "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
      "linkedSkin": {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "player-skin-notch",
        "pngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "model": "classic",
        "name": "Notch's Skin"
      },
      "tierOverall": "MCStat Mythic",
      "tierPoints": 9820,
      "tierRank": 12,
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-05-24T22:00:00Z",
      "totalPlayTime": 184320,
      "sessionCount": 412,
      "rankScore": 9820,
      "rank": 12,
      "recentSessions": [
        {
          "id": "oWZiF6jq_UnEs7Y3",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          },
          "joinedAt": "2026-05-24T20:00:00Z",
          "leftAt": "2026-05-24T21:00:00Z",
          "totalPlayTime": 3600
        }
      ],
      "serversPlayed": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
        }
      ],
      "latestStats": {
        "statsJson": {
          "kills": 18230,
          "deaths": 9850,
          "wins": 1240
        },
        "timestamp": "2026-05-24T21:00:00Z",
        "server": {
          "slug": "mchypixelnet",
          "name": "Hypixel Network"
        }
      },
      "statsHistory": [
        {
          "statsJson": {
            "kills": 18000,
            "deaths": 9700
          },
          "timestamp": "2026-05-24T20:00:00Z",
          "serverName": "Hypixel Network"
        }
      ],
      "kdRatio": 1.85,
      "totalKills": 18230,
      "totalDeaths": 9850,
      "totalWins": 1240,
      "activityData": [
        {
          "date": "2026-05-24",
          "count": 3
        }
      ],
      "achievements": {
        "earned": [
          {
            "id": "top10",
            "label": "Top 10",
            "labelTr": "İlk 10",
            "labelRu": "Топ 10",
            "icon": "medal"
          }
        ],
        "nextGoals": [
          {
            "id": "explorer_25",
            "label": "Globe Trotter",
            "labelTr": "Dünya Gezgini",
            "labelRu": "Путешественник",
            "icon": "plane"
          }
        ]
      },
      "votedServers": [
        {
          "serverId": "JS6o0w88QP6oZHDj",
          "serverSlug": "mchypixelnet",
          "serverName": "Hypixel Network",
          "serverIconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "votedAt": "2026-05-24T22:10:00Z"
        }
      ],
      "reviews": [
        {
          "id": "Rv8xKp2mNq7wTz1a",
          "rating": 5,
          "content": "Great server!",
          "createdAt": "2026-05-20T10:00:00Z",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          }
        }
      ]
    }
  }
}

Pesquisar

Pesquisa unificada em servidores e jogadores.

GET

/api/v1/search

Pesquisa global

Pesquise servidores e jogadores numa chamada.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/search"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`q`	`string`	Sim	`-`	Consulta de pesquisa (2–100 caracteres).
`type`	`string`	Não	`all`	Tipo de resultado: all, servers, players.
`limit`	`integer`	Não	`10`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "results": {
      "servers": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
          "currentPlayers": 48230,
          "maxPlayers": 200000,
          "isOnline": true,
          "rating": 3.4
        }
      ],
      "players": [
        {
          "id": "h6JDPuUGKI3Mfw3m",
          "minecraftUuid": "de5f2979-1168-43d6-b5f3-e18f975a806b",
          "mainNickname": "Notch",
          "createdAt": "2026-04-01T10:00:00Z",
          "updatedAt": "2026-05-24T22:00:00Z"
        }
      ]
    },
    "query": "hypixel"
  }
}

Estatísticas ao vivo e globais

Atividade global em tempo real, detalhamentos por região e país.

GET

/api/v1/live

Estatísticas ao vivo

Totais on-line globais, principais servidores, atividades recentes, detalhamento por região e país.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "stats": {
      "totalPlayers": 184320,
      "totalServers": 12480,
      "onlineServers": 9821,
      "newPlayersToday": 412,
      "peakToday": 202700,
      "generatedAt": "2026-05-24T22:00:00Z",
      "latestPingAt": "2026-05-24T21:59:48Z",
      "statsAgeSeconds": 18,
      "stale": false
    },
    "topServers": [
      {
        "id": "mchypixelnet",
        "name": "Hypixel Network",
        "players": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "trend": "up",
        "change": 240
      }
    ],
    "recentActivity": [
      {
        "type": "vote",
        "actor": "Notch",
        "target": "Hypixel Network",
        "time": "2026-05-24T22:00:00Z"
      }
    ],
    "regions": [
      {
        "id": "na",
        "name": "North America",
        "players": 80120,
        "servers": 4120
      }
    ],
    "countryPlayers": {
      "United States": 60120,
      "Germany": 18230
    }
  }
}

GET

/api/v1/live/history

História ao vivo

Intervalos por hora do total de jogadores online nos últimos 7 dias.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live/history"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "history": [
      {
        "timestamp": "2026-05-23T22:00:00Z",
        "totalPlayers": 174200
      }
    ]
  }
}

Tabelas de classificação

Melhores jogadores classificados por sessões, servidores ou pontos de nível.

GET

/api/v1/leaderboards

Tabelas de classificação

Melhores jogadores para os filtros de métrica, período, nível e conquista selecionados.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/leaderboards"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`metric`	`string`	Não	`best`	Métrica de classificação: best, sessions, servers.
`period`	`string`	Não	`all-time`	Janela de tempo: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`20`	Itens por página.
`tier`	`string`	Não	`-`	Filtro de camada.
`achievement`	`string`	Não	`-`	Filtro de conquistas.
`search`	`string`	Não	`-`	Consulta de texto livre.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "leaderboard": {
      "metric": "best",
      "period": "all-time",
      "serverId": null,
      "generatedAt": "2026-05-24T22:00:00Z",
      "entries": [
        {
          "rank": 1,
          "player": {
            "id": "Vz2BaB2r6eC9TL_o",
            "mainNickname": "Notch",
            "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
            "tierOverall": "MCStat Mythic",
            "tierPoints": 224606,
            "tierRank": 1,
            "skinModel": "classic",
            "skinUrl": "http://textures.minecraft.net/texture/d71c3adef2ec…",
            "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png"
          },
          "value": 224606,
          "formattedValue": "224,606 score"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

Peles e capas

Pesquise skins e capas enviadas pela comunidade.

GET

/api/v1/skins

Listar skins

Navegue pelos uploads de skins da comunidade com classificação/filtro.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`24`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`model`	`string`	Não	`-`	Modelo de pele: clássico ou fino.
`search`	`string`	Não	`-`	Consulta de texto livre.
`tag`	`string`	Não	`-`	Filtre por tag.
`owner`	`string`	Não	`-`	Filtro de nome de usuário do proprietário.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "skins": [
      {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "cool-knight",
        "name": "Cool Knight",
        "model": "classic",
        "tags": [
          "medieval",
          "armor"
        ],
        "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
        "viewCount": 3120,
        "likeCount": 124,
        "favoriteCount": 88,
        "downloadCount": 980,
        "usageCount": 12,
        "isFeatured": false,
        "createdAt": "2026-05-01T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/skins/{slug}

Detalhe da pele

Metadados completos do tema, além do estado de curtida/favorito do visualizador.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins/hypixel-net"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "skin": {
      "id": "Wi_n1dUvFqgJs0aP",
      "slug": "cool-knight",
      "name": "Cool Knight",
      "description": "Custom medieval knight skin",
      "tags": [
        "medieval",
        "armor"
      ],
      "model": "classic",
      "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
      "viewCount": 3120,
      "likeCount": 124,
      "favoriteCount": 88,
      "downloadCount": 980,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "tierOverall": "MCStat Mythic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/cool-knight.png"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

GET

/api/v1/capes

Listar capas

Navegue pelos uploads da capa da comunidade com classificação/filtro.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`24`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`search`	`string`	Não	`-`	Consulta de texto livre.
`tag`	`string`	Não	`-`	Filtre por tag.
`owner`	`string`	Não	`-`	Filtro de nome de usuário do proprietário.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "capes": [
      {
        "id": "De-jbTlj_PTnJJ5N",
        "slug": "royal-red",
        "name": "Royal Red",
        "tags": [
          "red",
          "royal"
        ],
        "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
        "viewCount": 210,
        "likeCount": 18,
        "favoriteCount": 6,
        "downloadCount": 44,
        "isFeatured": false,
        "createdAt": "2026-05-02T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/capes/{slug}

Detalhes da capa

Metadados completos da capa mais o estado de gosto/favorito do visitante.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes/hypixel-net"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "cape": {
      "id": "De-jbTlj_PTnJJ5N",
      "slug": "royal-red",
      "name": "Royal Red",
      "description": "Deep red royal cape",
      "tags": [
        "red",
        "royal"
      ],
      "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
      "viewCount": 210,
      "likeCount": 18,
      "favoriteCount": 6,
      "downloadCount": 44,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

MCSTATLista de servidores do Minecraft

REST API

Documentação da API

Integre dados de servidor, player, skin e comunidade do Minecraft ao vivo do mcstat.org em seus próprios aplicativos, bots e painéis.

URL base

Todas as solicitações de API começam com este URL base

https://mcstat.org/api/v1

Ver como Markdown

Documentação Markdown em bruto para IAs, bots e ferramentas

Chaves de API

Gerencie e monitore suas chaves de API

Crie, alterne e visualize análises de suas chaves de API no painel.

Abrir painel de chave de API

Parque de APIs

Teste endpoints diretamente no navegador

Verificação de bot

Este espaço de testes não requer uma chave de API; é necessária verificação humana para reduzir abusos.

Ponto final

GET

/api/v1/servers

Parâmetros de consulta

page

integer

limit

integer

sort

string

search

string

country

string

version

string

tag

string

mode

string

minPlayers

integer

maxPlayers

integer

minUptime

number

minVotes

integer

minRating

number

onlineOnly

boolean

Solicitar URL

https://mcstat.org/api/v1/servers

Execute uma solicitação para ver a resposta

Autenticação

Todos os endpoints de API públicos documentados exigem uma chave de API. Envie sua chave no cabeçalho X-API-Key.

Cabeçalho da solicitação

Adicione este cabeçalho para autenticar

X-API-Key: mcs_your_key_here

Ou como parâmetro de consulta

Ou passe como parâmetro de consulta

?api_key=mcs_your_key_here

Limites de taxa

As solicitações são autenticadas por chave de API. Uma chave ausente ou inválida retorna HTTP 401, uma chave desabilitada retorna HTTP 403 e um limite excedido retorna HTTP 429.

Sem chave API

Não permitido

Com chave API

Formato de resposta

Cada resposta bem-sucedida é JSON com um booleano e um objeto . Os erros usam o mesmo envelope com : falso.

Resposta de sucesso

JSON

{
  "success": true,
  "data": {
    "resource": {
      "id": "...",
      "name": "Example"
    }
  }
}

Resposta de erro

JSON

{
  "success": false,
  "error": "Too many requests"
}

Erros

São usados códigos de status HTTP padrão. Casos comuns:

Código	Significado
`400`	Solicitação incorreta – parâmetros inválidos
`401`	Não autorizado – chave de API ausente ou inválida
`403`	Proibido – chave de API desativada
`404`	Não encontrado — o recurso não existe
`429`	Muitas solicitações — limite de taxa excedido
`500`	Erro interno do servidor – tente novamente mais tarde

Pontos de extremidade do servidor

Navegue, filtre e inspecione servidores Minecraft rastreados por mcstat.org.

GET

/api/v1/servers

Listar servidores

Lista paginada de servidores públicos com filtros avançados.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`20`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`search`	`string`	Não	`-`	Consulta de texto livre.
`country`	`string`	Não	`-`	Filtro de nome de país ISO.
`version`	`string`	Não	`-`	Filtro de versão do Minecraft.
`tag`	`string`	Não	`-`	Filtre por tag.
`mode`	`string`	Não	`-`	Filtro de modo de jogo.
`minPlayers`	`integer`	Não	`-`	Contagem mínima atual de jogadores.
`maxPlayers`	`integer`	Não	`-`	Contagem máxima de jogadores atuais.
`minUptime`	`number`	Não	`-`	Porcentagem mínima de tempo de atividade.
`minVotes`	`integer`	Não	`-`	Contagem total mínima de votos.
`minRating`	`number`	Não	`-`	Classificação mínima (1–5).
`onlineOnly`	`boolean`	Não	`-`	Inclui apenas relatórios de servidores online.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "shortDescription": "Home of over 35 unique games…",
        "ip": "mc.hypixel.net",
        "port": 25565,
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "motd": "Hypixel Network",
        "website": null,
        "discordUrl": null,
        "visibility": "PUBLIC",
        "isOnline": true,
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "version": "Requires MC 1.8 / 1.21",
        "latency": 42,
        "lastPing": "2026-05-24T22:00:00Z",
        "country": "United States",
        "tags": [
          "bedwars",
          "pvp",
          "skyblock"
        ],
        "gameMode": null,
        "uptime": 100,
        "trend": 3.4,
        "totalVotes": 12345,
        "rating": 4.6,
        "createdAt": "2026-04-28T05:44:26Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/servers/{slug}

Detalhe do servidor

Perfil completo do servidor: histórico de estatísticas, tempo de atividade, gráfico de votos, classificações.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`period`	`string`	Não	`24h`	Janela de tempo: 24h, 7d, 30d, 90d, all-time.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "server": {
      "id": "JS6o0w88QP6oZHDj",
      "slug": "mchypixelnet",
      "name": "Hypixel Network",
      "ip": "mc.hypixel.net",
      "port": 25565,
      "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
      "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
      "motd": "Hypixel Network",
      "motdRaw": "§aHypixel §7Network",
      "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
      "website": null,
      "discordUrl": null,
      "storeUrl": null,
      "youtubeUrl": null,
      "currentPlayers": 48230,
      "maxPlayers": 200000,
      "isOnline": true,
      "country": "United States",
      "version": "Requires MC 1.8 / 1.21",
      "protocol": 767,
      "uptime": 100,
      "rating": 4.6,
      "totalVotes": 12345,
      "tags": [
        "bedwars",
        "pvp"
      ],
      "owner": null,
      "latestStats": {
        "onlinePlayers": 48230,
        "tps": 20,
        "timestamp": "2026-05-24T22:00:00Z"
      },
      "statsHistory": [
        {
          "timestamp": "2026-05-24T21:00:00Z",
          "onlinePlayers": 47000
        }
      ],
      "periodStats": {
        "24h": {
          "avgPlayers": 46500,
          "peakPlayers": 49100,
          "minPlayers": 42000,
          "uptimePct": 99.95
        }
      },
      "voteStats": {
        "24h": 412,
        "7d": 2890,
        "30d": 11200,
        "90d": 30150
      },
      "dailyVotes": [
        {
          "day": "2026-05-23",
          "votes": 405
        }
      ]
    }
  }
}

GET

/api/v1/servers/{slug}/voters

Eleitores do servidor

Eleitores recentes (autenticados e anônimos) para um determinado servidor.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/voters"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`7`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "voters": [
      {
        "id": "TanfrbogDfzGdrgD",
        "minecraftUsername": "Notch",
        "votedAt": "2026-05-24 22:10:06.544",
        "type": "auth",
        "playerId": "xq5-Lw8xk7pEdKyn",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "skinUrl": "http://textures.minecraft.net/texture/cbea0a15a5ce…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "siteUsername": "notch"
      }
    ],
    "total": 12345,
    "page": 1,
    "totalPages": 515,
    "latestVoteAt": "2026-05-24 22:10:06.544"
  }
}

GET

/api/v1/servers/{slug}/reviews

Avaliações do servidor

Avaliações e classificações de jogadores paginadas de um servidor.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/reviews"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`5`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "5g4VgYUiN4n28qcX",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": null,
        "minecraftUsername": "chibibara",
        "rating": 3,
        "content": "Great community!",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z",
        "user": {
          "id": null,
          "username": "chibibara",
          "avatar": null,
          "role": "USER"
        },
        "playerId": "suTEw8opOK2bGP-L",
        "playerMainNickname": "chibibara",
        "playerMinecraftUuid": "019f1b29-fcbe-705b-8efb-8c08b4e0fd9c",
        "playerSkinUrl": null,
        "playerSkinModel": "classic",
        "playerLinkedSkinPngPath": "https://mcstat.org/media/skins/published/default-steve.png"
      }
    ],
    "total": 128,
    "page": 1,
    "totalPages": 26,
    "avgRating": 4.2,
    "latestReviewAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/{slug}/updates

Novidades do servidor

Publicações de notícias e atualizações aprovadas de um servidor.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/updates"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`3`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "updates": [
      {
        "id": "Xk3pQ2mNbV8zR1sd",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": "Nf3kPq8sT2wVxJ7b",
        "title": "Season 5 is live!",
        "content": "New map, new kits, double XP weekend.",
        "status": "APPROVED",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "totalPages": 4,
    "latestUpdateAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/top

Principais servidores

Lista de tendências otimizada para uso na página inicial/widget.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/top"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`sort`	`string`	Não	`votes`	Ordem de classificação.
`limit`	`integer`	Não	`10`	Itens por página.
`country`	`string`	Não	`-`	Filtro de nome de país ISO.
`gameMode`	`string`	Não	`-`	Filtro de modo de jogo.

Resposta de exemplo

JSON

{
  "servers": [
    {
      "id": "JS6o0w88QP6oZHDj",
      "slug": "mchypixelnet",
      "name": "Hypixel Network",
      "ip": "mc.hypixel.net",
      "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
      "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
      "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
      "currentPlayers": 48230,
      "maxPlayers": 200000,
      "isOnline": true,
      "country": "United States",
      "totalVotes": 12345,
      "uptime": 100,
      "trend": 3.4,
      "recentVotes": 412,
      "hotScore": 9821
    }
  ],
  "total": 1240,
  "sort": "hot"
}

GET

/api/v1/servers/countries

Países servidores

Contagem agregada de servidores agrupados por país.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/countries"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "countries": [
      {
        "country": "United States",
        "serverCount": 2840
      }
    ]
  }
}

GET

/api/v1/servers/versions

Versões de servidor

Contagem agregada de servidores agrupados por versão do Minecraft.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/versions"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "versions": [
      {
        "version": "Paper 1.21.11",
        "serverCount": 980
      }
    ]
  }
}

Pontos de extremidade do jogador

Procure perfis de jogadores, sessões, níveis e histórico.

GET

/api/v1/players

Listar jogadores

Diretório de player público paginado.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`-`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`search`	`string`	Não	`-`	Consulta de texto livre.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "players": [
      {
        "id": "h6tC6lGfBEDulI8o",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "mainNickname": "Notch",
        "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "country": "United States",
        "tierOverall": "HT1",
        "tierPoints": 9820,
        "tierRank": 12,
        "lastTierSyncAt": "2026-05-24T20:00:00Z",
        "createdAt": "2026-04-01T10:00:00Z",
        "totalPlayTime": 184320,
        "sessionCount": 412
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/players/{id}

Detalhe do jogador

Perfil, sessões recentes, servidores jogados, K/D, conquistas.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players/069a79f4-44e9-4726-a5be-fca90e38aaf5"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`id`	`string`	Sim	`-`	ID do jogador, UUID ou apelido.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "player": {
      "id": "h6tC6lGfBEDulI8o",
      "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
      "mainNickname": "Notch",
      "nicknameHistory": [
        "Notch"
      ],
      "country": null,
      "skinModel": "classic",
      "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
      "linkedSkinId": "Wi_n1dUvFqgJs0aP",
      "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
      "linkedSkin": {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "player-skin-notch",
        "pngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "model": "classic",
        "name": "Notch's Skin"
      },
      "tierOverall": "MCStat Mythic",
      "tierPoints": 9820,
      "tierRank": 12,
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-05-24T22:00:00Z",
      "totalPlayTime": 184320,
      "sessionCount": 412,
      "rankScore": 9820,
      "rank": 12,
      "recentSessions": [
        {
          "id": "oWZiF6jq_UnEs7Y3",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          },
          "joinedAt": "2026-05-24T20:00:00Z",
          "leftAt": "2026-05-24T21:00:00Z",
          "totalPlayTime": 3600
        }
      ],
      "serversPlayed": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
        }
      ],
      "latestStats": {
        "statsJson": {
          "kills": 18230,
          "deaths": 9850,
          "wins": 1240
        },
        "timestamp": "2026-05-24T21:00:00Z",
        "server": {
          "slug": "mchypixelnet",
          "name": "Hypixel Network"
        }
      },
      "statsHistory": [
        {
          "statsJson": {
            "kills": 18000,
            "deaths": 9700
          },
          "timestamp": "2026-05-24T20:00:00Z",
          "serverName": "Hypixel Network"
        }
      ],
      "kdRatio": 1.85,
      "totalKills": 18230,
      "totalDeaths": 9850,
      "totalWins": 1240,
      "activityData": [
        {
          "date": "2026-05-24",
          "count": 3
        }
      ],
      "achievements": {
        "earned": [
          {
            "id": "top10",
            "label": "Top 10",
            "labelTr": "İlk 10",
            "labelRu": "Топ 10",
            "icon": "medal"
          }
        ],
        "nextGoals": [
          {
            "id": "explorer_25",
            "label": "Globe Trotter",
            "labelTr": "Dünya Gezgini",
            "labelRu": "Путешественник",
            "icon": "plane"
          }
        ]
      },
      "votedServers": [
        {
          "serverId": "JS6o0w88QP6oZHDj",
          "serverSlug": "mchypixelnet",
          "serverName": "Hypixel Network",
          "serverIconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "votedAt": "2026-05-24T22:10:00Z"
        }
      ],
      "reviews": [
        {
          "id": "Rv8xKp2mNq7wTz1a",
          "rating": 5,
          "content": "Great server!",
          "createdAt": "2026-05-20T10:00:00Z",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          }
        }
      ]
    }
  }
}

Pesquisar

Pesquisa unificada em servidores e jogadores.

GET

/api/v1/search

Pesquisa global

Pesquise servidores e jogadores numa chamada.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/search"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`q`	`string`	Sim	`-`	Consulta de pesquisa (2–100 caracteres).
`type`	`string`	Não	`all`	Tipo de resultado: all, servers, players.
`limit`	`integer`	Não	`10`	Itens por página.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "results": {
      "servers": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
          "currentPlayers": 48230,
          "maxPlayers": 200000,
          "isOnline": true,
          "rating": 3.4
        }
      ],
      "players": [
        {
          "id": "h6JDPuUGKI3Mfw3m",
          "minecraftUuid": "de5f2979-1168-43d6-b5f3-e18f975a806b",
          "mainNickname": "Notch",
          "createdAt": "2026-04-01T10:00:00Z",
          "updatedAt": "2026-05-24T22:00:00Z"
        }
      ]
    },
    "query": "hypixel"
  }
}

Estatísticas ao vivo e globais

Atividade global em tempo real, detalhamentos por região e país.

GET

/api/v1/live

Estatísticas ao vivo

Totais on-line globais, principais servidores, atividades recentes, detalhamento por região e país.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "stats": {
      "totalPlayers": 184320,
      "totalServers": 12480,
      "onlineServers": 9821,
      "newPlayersToday": 412,
      "peakToday": 202700,
      "generatedAt": "2026-05-24T22:00:00Z",
      "latestPingAt": "2026-05-24T21:59:48Z",
      "statsAgeSeconds": 18,
      "stale": false
    },
    "topServers": [
      {
        "id": "mchypixelnet",
        "name": "Hypixel Network",
        "players": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "trend": "up",
        "change": 240
      }
    ],
    "recentActivity": [
      {
        "type": "vote",
        "actor": "Notch",
        "target": "Hypixel Network",
        "time": "2026-05-24T22:00:00Z"
      }
    ],
    "regions": [
      {
        "id": "na",
        "name": "North America",
        "players": 80120,
        "servers": 4120
      }
    ],
    "countryPlayers": {
      "United States": 60120,
      "Germany": 18230
    }
  }
}

GET

/api/v1/live/history

História ao vivo

Intervalos por hora do total de jogadores online nos últimos 7 dias.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live/history"

Parâmetros de consulta

Sem parâmetros

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "history": [
      {
        "timestamp": "2026-05-23T22:00:00Z",
        "totalPlayers": 174200
      }
    ]
  }
}

Tabelas de classificação

Melhores jogadores classificados por sessões, servidores ou pontos de nível.

GET

/api/v1/leaderboards

Tabelas de classificação

Melhores jogadores para os filtros de métrica, período, nível e conquista selecionados.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/leaderboards"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`metric`	`string`	Não	`best`	Métrica de classificação: best, sessions, servers.
`period`	`string`	Não	`all-time`	Janela de tempo: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`20`	Itens por página.
`tier`	`string`	Não	`-`	Filtro de camada.
`achievement`	`string`	Não	`-`	Filtro de conquistas.
`search`	`string`	Não	`-`	Consulta de texto livre.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "leaderboard": {
      "metric": "best",
      "period": "all-time",
      "serverId": null,
      "generatedAt": "2026-05-24T22:00:00Z",
      "entries": [
        {
          "rank": 1,
          "player": {
            "id": "Vz2BaB2r6eC9TL_o",
            "mainNickname": "Notch",
            "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
            "tierOverall": "MCStat Mythic",
            "tierPoints": 224606,
            "tierRank": 1,
            "skinModel": "classic",
            "skinUrl": "http://textures.minecraft.net/texture/d71c3adef2ec…",
            "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png"
          },
          "value": 224606,
          "formattedValue": "224,606 score"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

Peles e capas

Pesquise skins e capas enviadas pela comunidade.

GET

/api/v1/skins

Listar skins

Navegue pelos uploads de skins da comunidade com classificação/filtro.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`24`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`model`	`string`	Não	`-`	Modelo de pele: clássico ou fino.
`search`	`string`	Não	`-`	Consulta de texto livre.
`tag`	`string`	Não	`-`	Filtre por tag.
`owner`	`string`	Não	`-`	Filtro de nome de usuário do proprietário.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "skins": [
      {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "cool-knight",
        "name": "Cool Knight",
        "model": "classic",
        "tags": [
          "medieval",
          "armor"
        ],
        "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
        "viewCount": 3120,
        "likeCount": 124,
        "favoriteCount": 88,
        "downloadCount": 980,
        "usageCount": 12,
        "isFeatured": false,
        "createdAt": "2026-05-01T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/skins/{slug}

Detalhe da pele

Metadados completos do tema, além do estado de curtida/favorito do visualizador.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins/hypixel-net"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "skin": {
      "id": "Wi_n1dUvFqgJs0aP",
      "slug": "cool-knight",
      "name": "Cool Knight",
      "description": "Custom medieval knight skin",
      "tags": [
        "medieval",
        "armor"
      ],
      "model": "classic",
      "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
      "viewCount": 3120,
      "likeCount": 124,
      "favoriteCount": 88,
      "downloadCount": 980,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "tierOverall": "MCStat Mythic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/cool-knight.png"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

GET

/api/v1/capes

Listar capas

Navegue pelos uploads da capa da comunidade com classificação/filtro.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`page`	`integer`	Não	`1`	Número da página, começando em 1.
`limit`	`integer`	Não	`24`	Itens por página.
`sort`	`string`	Não	`recent`	Ordem de classificação.
`search`	`string`	Não	`-`	Consulta de texto livre.
`tag`	`string`	Não	`-`	Filtre por tag.
`owner`	`string`	Não	`-`	Filtro de nome de usuário do proprietário.

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "capes": [
      {
        "id": "De-jbTlj_PTnJJ5N",
        "slug": "royal-red",
        "name": "Royal Red",
        "tags": [
          "red",
          "royal"
        ],
        "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
        "viewCount": 210,
        "likeCount": 18,
        "favoriteCount": 6,
        "downloadCount": 44,
        "isFeatured": false,
        "createdAt": "2026-05-02T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/capes/{slug}

Detalhes da capa

Metadados completos da capa mais o estado de gosto/favorito do visitante.

Solicitação de exemplo

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes/hypixel-net"

Parâmetros de consulta

Nome	Tipo	obrigatório	padrão	Descrição
`slug`	`string`	Sim	`-`	Slug de servidor (da lista /servers).

Resposta de exemplo

JSON

{
  "success": true,
  "data": {
    "cape": {
      "id": "De-jbTlj_PTnJJ5N",
      "slug": "royal-red",
      "name": "Royal Red",
      "description": "Deep red royal cape",
      "tags": [
        "red",
        "royal"
      ],
      "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
      "viewCount": 210,
      "likeCount": 18,
      "favoriteCount": 6,
      "downloadCount": 44,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}