REST API

Dokumentacja API

Zintegruj dane serwera, gracza, skórki i społeczności na żywo Minecraft z mcstat.org z własnymi aplikacjami, botami i pulpitami nawigacyjnymi.

Bazowy adres URL

Wszystkie żądania API zaczynają się od tego podstawowego adresu URL

https://mcstat.org/api/v1

Wyświetl jako Markdown

Surowa dokumentacja Markdown dla AI, botów i narzędzi

Klucze API

Zarządzaj i monitoruj swoje klucze API

Twórz, obracaj i przeglądaj analizy kluczy API na pulpicie nawigacyjnym.

Otwórz panel kluczy API

Plac zabaw API

Testuj punkty końcowe bezpośrednio w przeglądarce

Weryfikacja bota

Ten plac zabaw nie wymaga klucza API; do zmniejszenia nadużyć wymagana jest weryfikacja człowieka.

Punkt końcowy

GET

/api/v1/servers

Parametry zapytania

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

Adres URL żądania

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

Uruchom żądanie, aby zobaczyć odpowiedź

Uwierzytelnianie

Wszystkie udokumentowane publiczne punkty końcowe API wymagają klucza API. Wyślij swój klucz w nagłówku X-API-Key.

Nagłówek żądania

Dodaj ten nagłówek, aby uwierzytelnić

X-API-Key: mcs_your_key_here

Lub jako parametr zapytania

Lub podaj jako parametr zapytania

?api_key=mcs_your_key_here

Limity stawek

Żądania są uwierzytelniane kluczem API. Brakujący lub nieprawidłowy klucz zwraca HTTP 401, wyłączony klucz zwraca HTTP 403, a przekroczony limit zwraca HTTP 429.

Bez klucza API

Niedozwolone

Z kluczem API

Domyślnie 60 żądań na minutę, 1000 dziennie i 30 000 miesięcznie. Przekroczenie limitu powoduje zwrócenie protokołu HTTP 429 z nagłówkami X-RateLimit-* pokazującymi Twoje limity oraz komunikatem Retry-After informującym o zresetowaniu okna. Na życzenie możliwe jest przyznanie wyższych limitów na klucz.

Nagłówki limitów szybkości:Odpowiedź 429 zawiera X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month i Retry-After. Pomyślne odpowiedzi zawierają nagłówek Cache-Control, dzięki czemu można bezpiecznie buforować wyniki po stronie klienta.

Format odpowiedzi

Każda pomyślna odpowiedź to JSON z wartością logiczną i obiektem . Błędy używają tej samej koperty z : false.

Odpowiedź sukcesu

JSON

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

Odpowiedź na błąd

JSON

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

Błędy

Stosowane są standardowe kody stanu HTTP. Typowe przypadki:

Kod	Znaczenie
`400`	Złe żądanie — nieprawidłowe parametry
`401`	Nieautoryzowany — brakujący lub nieprawidłowy klucz API
`403`	Zabronione — klucz API wyłączony
`404`	Nie znaleziono — zasób nie istnieje
`429`	Zbyt wiele żądań — przekroczono limit szybkości
`500`	Wewnętrzny błąd serwera — spróbuj ponownie później

Punkty końcowe serwera

Przeglądaj, filtruj i sprawdzaj serwery Minecraft śledzone przez mcstat.org.

GET

/api/v1/servers

Lista serwerów

Paginowana lista serwerów publicznych z bogatymi filtrami.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`20`	Pozycje na stronę.
`sort`	`string`	Nie	`recent`	Kolejność sortowania.
`search`	`string`	Nie	`—`	Zapytanie tekstowe.
`country`	`string`	Nie	`—`	Filtr nazw krajów ISO.
`version`	`string`	Nie	`—`	Filtr wersji Minecrafta.
`tag`	`string`	Nie	`—`	Filtruj według tagu.
`mode`	`string`	Nie	`—`	Filtr trybu gry.
`minPlayers`	`integer`	Nie	`—`	Minimalna aktualna liczba graczy.
`maxPlayers`	`integer`	Nie	`—`	Maksymalna aktualna liczba graczy.
`minUptime`	`number`	Nie	`—`	Minimalny procent czasu sprawności.
`minVotes`	`integer`	Nie	`—`	Minimalna łączna liczba głosów.
`minRating`	`number`	Nie	`—`	Minimalna ocena (1–5).
`onlineOnly`	`boolean`	Nie	`—`	Uwzględnij tylko serwery raportujące online.

Przykładowa odpowiedź

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}

Szczegóły serwera

Pełny profil serwera: historia statystyk, czas pracy, wykres głosów, rangi.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`slug`	`string`	Tak	`—`	Błąd serwera (z listy /servers).
`period`	`string`	Nie	`24h`	Okno czasowe: 24h, 7d, 30d, 90d, all-time.

Przykładowa odpowiedź

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

Wyborcy serwera

Ostatni głosujący (uwierzytelnieni i anonimowi) dla danego serwera.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`slug`	`string`	Tak	`—`	Błąd serwera (z listy /servers).
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`7`	Pozycje na stronę.

Przykładowa odpowiedź

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

Recenzje serwera

Podzielone na strony recenzje i oceny graczy dla serwera.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`slug`	`string`	Tak	`—`	Błąd serwera (z listy /servers).
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`5`	Pozycje na stronę.

Przykładowa odpowiedź

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

Aktualizacje serwera

Zatwierdzone wpisy z newsami i aktualizacjami dla serwera.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`slug`	`string`	Tak	`—`	Błąd serwera (z listy /servers).
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`3`	Pozycje na stronę.

Przykładowa odpowiedź

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

Najlepsze serwery

Lista trendów zoptymalizowana pod kątem użycia strony głównej/widżetu.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`sort`	`string`	Nie	`votes`	Kolejność sortowania.
`limit`	`integer`	Nie	`10`	Pozycje na stronę.
`country`	`string`	Nie	`—`	Filtr nazw krajów ISO.
`gameMode`	`string`	Nie	`—`	Filtr trybu gry.

Przykładowa odpowiedź

JSON

{
  "success": true,
  "data": {
    "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

Kraje serwerów

Łączna liczba serwerów pogrupowanych według krajów.

Przykładowe żądanie

cURL

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

Parametry zapytania

Brak parametrów

Przykładowa odpowiedź

JSON

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

GET

/api/v1/servers/versions

Wersje serwerowe

Łączna liczba serwerów pogrupowanych według wersji Minecrafta.

Przykładowe żądanie

cURL

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

Parametry zapytania

Brak parametrów

Przykładowa odpowiedź

JSON

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

Punkty końcowe gracza

Przeglądaj profile graczy, sesje, poziomy i historię.

GET

/api/v1/players

Lista graczy

Paginowany publiczny katalog odtwarzaczy.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`—`	Pozycje na stronę.
`sort`	`string`	Nie	`recent`	Kolejność sortowania.
`search`	`string`	Nie	`—`	Zapytanie tekstowe.

Przykładowa odpowiedź

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}

Szczegóły gracza

Profil, ostatnie sesje, serwery, na których grałeś, K/D, osiągnięcia.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`id`	`string`	Tak	`—`	Identyfikator gracza, UUID lub pseudonim.

Przykładowa odpowiedź

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

Szukaj

Ujednolicone wyszukiwanie serwerów i graczy.

GET

/api/v1/search

Globalne wyszukiwanie

Przeszukaj serwery i graczy w jednym wywołaniu.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`q`	`string`	Tak	`—`	Zapytanie wyszukiwania (2–100 znaków).
`type`	`string`	Nie	`all`	Typ wyniku: all, servers, players.
`limit`	`integer`	Nie	`10`	Pozycje na stronę.

Przykładowa odpowiedź

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

Statystyki na żywo i globalne

Globalna aktywność, podział na regiony i kraje w czasie rzeczywistym.

GET

/api/v1/live

Statystyki na żywo

Globalne sumy online, najlepsze serwery, ostatnia aktywność, podział na regiony i kraje.

Przykładowe żądanie

cURL

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

Parametry zapytania

Brak parametrów

Przykładowa odpowiedź

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

Historia na żywo

Godzinowe zbiory wszystkich graczy online w ciągu ostatnich 7 dni.

Przykładowe żądanie

cURL

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

Parametry zapytania

Brak parametrów

Przykładowa odpowiedź

JSON

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

Tabele liderów

Najlepsi gracze uszeregowani według sesji, serwerów lub punktów poziomu.

GET

/api/v1/leaderboards

Tabele liderów

Najlepsi gracze dla wybranych filtrów wskaźników, okresu, poziomu i osiągnięć.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`metric`	`string`	Nie	`best`	Metryka rankingowa: best, sessions, servers.
`period`	`string`	Nie	`all-time`	Okno czasowe: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`20`	Pozycje na stronę.
`tier`	`string`	Nie	`—`	Filtr poziomów.
`achievement`	`string`	Nie	`—`	Filtr osiągnięć.
`search`	`string`	Nie	`—`	Zapytanie tekstowe.

Przykładowa odpowiedź

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
    }
  }
}

Skórki i peleryny

Przeszukuj przesłane przez społeczność skórki i peleryny.

GET

/api/v1/skins

Lista skórek

Przeglądaj przesłane skórki społeczności za pomocą sortowania/filtrowania.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`24`	Pozycje na stronę.
`sort`	`string`	Nie	`recent`	Kolejność sortowania.
`model`	`string`	Nie	`—`	Model skóry: klasyczny lub slim.
`search`	`string`	Nie	`—`	Zapytanie tekstowe.
`tag`	`string`	Nie	`—`	Filtruj według tagu.
`owner`	`string`	Nie	`—`	Filtr nazwy użytkownika właściciela.

Przykładowa odpowiedź

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}

Szczegóły skóry

Pełne metadane skórki oraz stan polubienia/ulubienia widza.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`slug`	`string`	Tak	`—`	Błąd serwera (z listy /servers).

Przykładowa odpowiedź

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

Lista peleryny

Przeglądaj przesłane pliki społecznościowe za pomocą sortowania/filtrowania.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`page`	`integer`	Nie	`1`	Numer strony, zaczynający się od 1.
`limit`	`integer`	Nie	`24`	Pozycje na stronę.
`sort`	`string`	Nie	`recent`	Kolejność sortowania.
`search`	`string`	Nie	`—`	Zapytanie tekstowe.
`tag`	`string`	Nie	`—`	Filtruj według tagu.
`owner`	`string`	Nie	`—`	Filtr nazwy użytkownika właściciela.

Przykładowa odpowiedź

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}

Szczegóły peleryny

Pełne metadane peleryny oraz stan polubienia/ulubionych widza.

Przykładowe żądanie

cURL

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

Parametry zapytania

Imię	Wpisz	wymagane	domyślny	Opis
`slug`	`string`	Tak	`—`	Błąd serwera (z listy /servers).

Przykładowa odpowiedź

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,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
          "tierOverall": "MCStat Mythic"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}