REST API

Dokumentace API

Integrujte živá data serveru Minecraft, hráče, vzhledu a komunity z mcstat.org do svých vlastních aplikací, robotů a panelů.

Základní URL

Všechny požadavky API začínají touto základní adresou URL

https://mcstat.org/api/v1

Zobrazit jako Markdown

Surová Markdown dokumentace pro AI, boty a nástroje

Klíče API

Spravujte a sledujte své API klíče

Vytvářejte, otáčejte a zobrazujte analýzy pro klíče API na řídicím panelu.

Otevřete řídicí panel klíče API

API hřiště

Testujte koncové body přímo v prohlížeči

Kontrola bota

Toto hřiště nevyžaduje API klíč; k omezení zneužití je vyžadováno lidské ověření.

Koncový bod

GET

/api/v1/servers

Parametry dotazu

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

URL požadavku

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

Spusťte požadavek, abyste viděli odpověď

Autentizace

Všechny zdokumentované veřejné koncové body API vyžadují klíč API. Odešlete svůj klíč v záhlaví X-API-Key.

Záhlaví požadavku

Přidejte toto záhlaví k ověření

X-API-Key: mcs_your_key_here

Nebo jako parametr dotazu

Nebo předat jako parametr dotazu

?api_key=mcs_your_key_here

Sazbové limity

Požadavky jsou ověřovány klíčem API. Chybějící nebo neplatný klíč vrátí HTTP 401, zakázaný klíč vrátí HTTP 403 a překročený limit vrátí HTTP 429.

Bez klíče API

Není povoleno

S klíčem API

Standardně 60 požadavků za minutu, 1 000 za den a 30 000 za měsíc. Překročení limitu vrátí HTTP 429 s hlavičkami X-RateLimit-* zobrazujícími vaše limity a Retry-After, které vám sdělí, kdy se okno resetuje. Na požádání lze na klíč poskytnout vyšší limity.

Záhlaví limitu sazby:Odpověď 429 nese X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month a Retry-After. Úspěšné odpovědi obsahují hlavičku Cache-Control, takže výsledky můžete bezpečně ukládat do mezipaměti na straně klienta.

Formát odpovědi

Každá úspěšná odpověď je JSON s boolean a objektem . Chyby používají stejnou obálku s : false.

Úspěšná odpověď

JSON

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

Odezva na chybu

JSON

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

Chyby

Používají se standardní stavové kódy HTTP. Běžné případy:

kód	Význam
`400`	Chybný požadavek — neplatné parametry
`401`	Unauthorized – chybějící nebo neplatný klíč API
`403`	Zakázáno — Klíč API je zakázán
`404`	Nenalezeno – zdroj neexistuje
`429`	Příliš mnoho požadavků – překročen limit rychlosti
`500`	Interní chyba serveru — zkuste to znovu později

Koncové body serveru

Procházejte, filtrujte a kontrolujte servery Minecraft sledované mcstat.org.

GET

/api/v1/servers

Seznam serverů

Stránkovaný seznam veřejných serverů s bohatými filtry.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`20`	Položky na stránku.
`sort`	`string`	Ne	`recent`	Řadit pořadí.
`search`	`string`	Ne	`—`	Volný textový dotaz.
`country`	`string`	Ne	`—`	Filtr názvu země ISO.
`version`	`string`	Ne	`—`	Filtr verze Minecraft.
`tag`	`string`	Ne	`—`	Filtrovat podle značky.
`mode`	`string`	Ne	`—`	Filtr herního režimu.
`minPlayers`	`integer`	Ne	`—`	Minimální aktuální počet hráčů.
`maxPlayers`	`integer`	Ne	`—`	Maximální aktuální počet hráčů.
`minUptime`	`number`	Ne	`—`	Minimální procento provozuschopnosti.
`minVotes`	`integer`	Ne	`—`	Minimální celkový počet hlasů.
`minRating`	`number`	Ne	`—`	Minimální hodnocení (1–5).
`onlineOnly`	`boolean`	Ne	`—`	Zahrňte pouze servery, které hlásí online.

Příklad odpovědi

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}

Detail serveru

Úplný profil serveru: historie statistik, dostupnost, graf hlasování, pozice.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`slug`	`string`	Ano	`—`	Server slug (ze seznamu /servers).
`period`	`string`	Ne	`24h`	Časové okno: 24h, 7d, 30d, 90d, all-time.

Příklad odpovědi

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

Serveroví voliči

Poslední hlasující (ověření a anonymní) pro daný server.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`slug`	`string`	Ano	`—`	Server slug (ze seznamu /servers).
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`7`	Položky na stránku.

Příklad odpovědi

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

Recenze serveru

Stránkované recenze a hodnocení hráčů pro server.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`slug`	`string`	Ano	`—`	Server slug (ze seznamu /servers).
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`5`	Položky na stránku.

Příklad odpovědi

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

Novinky serveru

Schválené novinky a aktualizace pro server.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`slug`	`string`	Ano	`—`	Server slug (ze seznamu /servers).
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`3`	Položky na stránku.

Příklad odpovědi

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

Špičkové servery

Seznam trendů optimalizovaný pro použití na domovské stránce/widgetu.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`sort`	`string`	Ne	`votes`	Řadit pořadí.
`limit`	`integer`	Ne	`10`	Položky na stránku.
`country`	`string`	Ne	`—`	Filtr názvu země ISO.
`gameMode`	`string`	Ne	`—`	Filtr herního režimu.

Příklad odpovědi

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

Země serveru

Celkový počet serverů seskupených podle země.

Příklad žádosti

cURL

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

Parametry dotazu

Žádné parametry

Příklad odpovědi

JSON

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

GET

/api/v1/servers/versions

Verze serveru

Souhrnný počet serverů seskupených podle verze Minecraftu.

Příklad žádosti

cURL

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

Parametry dotazu

Žádné parametry

Příklad odpovědi

JSON

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

Koncové body hráče

Vyhledejte profily hráčů, relace, úrovně a historii.

GET

/api/v1/players

Seznam hráčů

Stránkovaný veřejný adresář přehrávače.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`—`	Položky na stránku.
`sort`	`string`	Ne	`recent`	Řadit pořadí.
`search`	`string`	Ne	`—`	Volný textový dotaz.

Příklad odpovědi

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}

Detail hráče

Profil, poslední relace, hrané servery, K/D, úspěchy.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`id`	`string`	Ano	`—`	ID hráče, UUID nebo přezdívka.

Příklad odpovědi

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

Hledat

Jednotné vyhledávání napříč servery a hráči.

GET

/api/v1/search

Globální vyhledávání

Prohledejte servery a hráče v jednom volání.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`q`	`string`	Ano	`—`	Vyhledávací dotaz (2–100 znaků).
`type`	`string`	Ne	`all`	Typ výsledku: all, servers, players.
`limit`	`integer`	Ne	`10`	Položky na stránku.

Příklad odpovědi

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

Živé a globální statistiky

Globální aktivita v reálném čase, členění podle regionů a zemí.

GET

/api/v1/live

Živé statistiky

Globální online součty, top servery, nedávná aktivita, rozdělení podle regionů a zemí.

Příklad žádosti

cURL

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

Parametry dotazu

Žádné parametry

Příklad odpovědi

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

Živá historie

Hodinové segmenty celkového počtu online hráčů za posledních 7 dní.

Příklad žádosti

cURL

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

Parametry dotazu

Žádné parametry

Příklad odpovědi

JSON

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

Žebříčky

Nejlepší hráči seřazení podle relací, serverů nebo bodů úrovně.

GET

/api/v1/leaderboards

Žebříčky

Nejlepší hráči pro vybranou metriku, období, úroveň a filtry úspěchů.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`metric`	`string`	Ne	`best`	Metrika hodnocení: best, sessions, servers.
`period`	`string`	Ne	`all-time`	Časové okno: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`20`	Položky na stránku.
`tier`	`string`	Ne	`—`	Řadový filtr.
`achievement`	`string`	Ne	`—`	Filtr úspěchu.
`search`	`string`	Ne	`—`	Volný textový dotaz.

Příklad odpovědi

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

Kůže a pláště

Prohledávejte skiny a pláště nahrané komunitou.

GET

/api/v1/skins

Seznam vzhledů

Procházejte nahrané skiny komunity pomocí řazení/filtru.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`24`	Položky na stránku.
`sort`	`string`	Ne	`recent`	Řadit pořadí.
`model`	`string`	Ne	`—`	Model pleti: klasický nebo tenký.
`search`	`string`	Ne	`—`	Volný textový dotaz.
`tag`	`string`	Ne	`—`	Filtrovat podle značky.
`owner`	`string`	Ne	`—`	Filtr uživatelského jména vlastníka.

Příklad odpovědi

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}

Detail kůže

Úplná metadata vzhledu plus stav, který se divákovi líbí/oblíbený.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`slug`	`string`	Ano	`—`	Server slug (ze seznamu /servers).

Příklad odpovědi

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

Vyjmenujte pláštěnky

Procházejte nahrání komunitního pláště pomocí řazení/filtru.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`page`	`integer`	Ne	`1`	Číslo stránky počínaje 1.
`limit`	`integer`	Ne	`24`	Položky na stránku.
`sort`	`string`	Ne	`recent`	Řadit pořadí.
`search`	`string`	Ne	`—`	Volný textový dotaz.
`tag`	`string`	Ne	`—`	Filtrovat podle značky.
`owner`	`string`	Ne	`—`	Filtr uživatelského jména vlastníka.

Příklad odpovědi

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}

Detail pláštěnky

Úplná metadata pláštěnky a stav líbí/oblíbené u diváka.

Příklad žádosti

cURL

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

Parametry dotazu

Jméno	Typ	vyžadováno	výchozí	Popis
`slug`	`string`	Ano	`—`	Server slug (ze seznamu /servers).

Příklad odpovědi

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