For server owners

API for server owners

Connect your server or website directly to MinecraftList — you can pull votes, the voter leaderboard, and a list of players who play on your server. It comes in handy for vote rewards, statistics, or custom overviews. You can find the API key in modifications to your server.

How to get a key Endpointy Examples Limity Player verification

How to get a key

Log in and open modifications to your server (Profile → My servers → Edit, or button Edit on the server profile).
In the panel API for owners click on Generate key.
The key will be displayed only once — copy it right away. We only store its hash in the database, so we have no way to show it later. If you lose it, generate a new one (the old one will immediately become invalid).

The key is sent directly in the address (/api/v1/{klíč}/…), so it can also be used from a browser or from a simple script. Don’t show it to anyone — anyone who has it will see your stats. If it gets out, replace the key (or revoke it).

Endpointy

The basis is https://minecraftlist.eu/api/v1/{klíč}. Everything is returned as JSON.

Metoda	Cesta	What does it return?
`GET`	`/info`	Server overview (status, players, address, game modes) and votes (today, monthly, total) + key status and exhausted limits.
`GET`	`/votes/month`	Votes for the current month. `?nickname=Nick` narrows to one player, `?merge=1` returns totals instead of individual votes, `?limit=` count.
`GET`	`/votes/{rok}/{měsíc}`	Votes for a specific month (same options as above), e.g. `/votes/2026/9`.
`GET`	`/votes/top`	Most active voters. `?period=30d` (or `7d`, `all`) a `?limit=25` (max 100).
`GET`	`/votes/player/{nick}`	A player's status: how many votes they have sent, when they last voted, and when they can vote again.
`GET`	`/votes/player/{nick}/next`	Just the time until the next possible vote (suitable for a plugin — you don't have to calculate anything).
`GET`	`/players`	List of players reported by the server (see below).
`POST`	`/players`	Uploading server players — body `{"players": ["Nick1", "Nick2"]}` or `{"nickname": "Nick"}` (It can also be sent as text, lines = nicknames).

Examples

Server overview:

curl "https://minecraftlist.eu/api/v1/TVUJ_KLIC/info"

Voter leaderboard for the last 30 days (25 most active):

curl "https://minecraftlist.eu/api/v1/TVUJ_KLIC/votes/top?period=30d&limit=25"

When can a player Notch hlasovat znovu:

curl "https://minecraftlist.eu/api/v1/TVUJ_KLIC/votes/player/Notch/next"

Loading players from the server (e.g. from a plugin after the player logs in):

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

The answer looks like this (shortened):

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

Limits and behavior

60 calls per minute turnkey. When the limit overflows, we'll return it 429 — just wait a moment.
An invalid, exchanged, or revoked key returns 401 with explanation.
Maximally 1000 votes a 100 players in a single call (for speed).
Cooldown mezi hlasy je 2 hours and it is tracked based on the voter's IP address (to prevent nickname changes). The player's entry is based on their last vote.
All times are in ISO 8601 including the time zone.
The key never appears in our logs — in the records, it is replaced by a marker.

Player verification

When the server sends us a list of its players (POST /players), we can verify in reviews that the writer really plays on the server — and such a player gets a badge on the review. You manage the list yourself; just send it continuously (even one player at a time when they connect).

Do you need anything extra — a different data format, more records, or integration with a specific plugin? Write to us at contact form and we'll come to an agreement.