Pro majitele serverů

API pro majitele serverů

Napoj si svůj server nebo web přímo na MineList — stáhneš si hlasy, žebříček hlasujících i seznam hráčů, kteří u tebe hrají. Hodí se na odměny za hlas, statistiky nebo vlastní přehledy. Klíč k API najdeš v úpravách svého serveru.

Jak získat klíč Endpointy Ukázky Limity Ověřování hráčů

Jak získat klíč

Přihlas se a otevři úpravy svého serveru (Profil → Moje servery → Upravit, nebo tlačítko Upravit na profilu serveru).
V panelu API pro majitele klikni na Vygenerovat klíč.
Klíč se zobrazí jen jednou — hned si ho zkopíruj. V databázi držíme jen jeho otisk, takže ho později nemáme jak zobrazit. Když ho ztratíš, vygeneruj si nový (starý tím okamžitě přestane platit).

Klíč se posílá přímo v adrese (/api/v1/{klíč}/…), takže se dá použít i z prohlížeče nebo z jednoduchého skriptu. Nikomu ho neukazuj — kdokoli s ním uvidí tvoje statistiky. Když se dostane ven, klíč vyměň (nebo zruš).

Endpointy

Základ je https://www.minelist.cz/api/v1/{klíč}. Všechno se vrací jako JSON.

Metoda	Cesta	Co vrací
`GET`	`/info`	Přehled serveru (stav, hráči, adresa, herní módy) a hlasů (dnes, za měsíc, celkem) + stav klíče a vyčerpané limity.
`GET`	`/votes/month`	Hlasy za aktuální měsíc. `?nickname=Nick` zúží na jednoho hráče, `?merge=1` vrátí součty místo jednotlivých hlasů, `?limit=` počet.
`GET`	`/votes/{rok}/{měsíc}`	Hlasy za konkrétní měsíc (stejné volby jako výše), např. `/votes/2026/9`.
`GET`	`/votes/top`	Nejaktivnější hlasující. `?period=30d` (nebo `7d`, `all`) a `?limit=25` (max 100).
`GET`	`/votes/player/{nick}`	Stav jednoho hráče: kolik hlasů poslal, kdy naposledy a kdy může znovu.
`GET`	`/votes/player/{nick}/next`	Jen čas do dalšího možného hlasu (vhodné pro plugin — nemusíš nic počítat).
`GET`	`/players`	Seznam hráčů, které server nahlásil (viz níže).
`POST`	`/players`	Nahrání hráčů serveru — tělo `{"players": ["Nick1", "Nick2"]}` nebo `{"nickname": "Nick"}` (jde poslat i jako text, řádky = přezdívky).

Ukázky

Přehled serveru:

curl "https://www.minelist.cz/api/v1/TVUJ_KLIC/info"

Žebříček hlasujících za posledních 30 dní (25 nejaktivnějších):

curl "https://www.minelist.cz/api/v1/TVUJ_KLIC/votes/top?period=30d&limit=25"

Kdy může hráč Notch hlasovat znovu:

curl "https://www.minelist.cz/api/v1/TVUJ_KLIC/votes/player/Notch/next"

Nahrání hráčů ze serveru (např. z pluginu po přihlášení hráče):

curl -X POST "https://www.minelist.cz/api/v1/TVUJ_KLIC/players" \
  -H "Content-Type: application/json" \
  -d '{"players": ["Notch", "jeb_"]}'

Odpověď vypadá takhle (zkráceno):

{
  "player": {
    "nickname": "Notch",
    "votes": 12,
    "last_vote_at": "2026-09-23T11:05:00+02:00",
    "next_vote_at": "2026-09-23T23:05:00+02:00",
    "can_vote_now": false,
    "known_by_server": true
  }
}

Limity a chování

60 volání za minutu na klíč. Když limit přeteče, vrátíme 429 — stačí chvíli počkat.
Neplatný, vyměněný nebo zrušený klíč vrátí 401 s vysvětlením.
Maximálně 1000 hlasů a 100 hráčů na jedno volání (kvůli rychlosti).
Cooldown mezi hlasy je 12 hodin a hlídá se podle IP adresy hlasujícího (kvůli přepisování přezdívek). Údaj u hráče vychází z jeho posledního hlasu.
Všechny časy jsou v ISO 8601 včetně časové zóny.
Klíč se nikdy neobjeví v našich logech — v záznamech je nahrazený značkou.

Ověřování hráčů

Když nám server pošle seznam svých hráčů (POST /players), můžeme u recenzí ověřit, že pisatel na serveru opravdu hraje — a takový hráč dostane u recenze odznak. Seznam si spravuješ sám, stačí ho posílat průběžně (klidně po jednom hráči při připojení).

Potřebuješ něco navíc — jiný tvar dat, více záznamů nebo napojení na konkrétní plugin? Napiš nám a domluvíme se.