A free public REST API for querying our Minecraft server toplist data. Use it to build Discord bots, server-status widgets, dashboards, plugin integrations, or anything else you can dream up. All endpoints return JSON, are CORS-enabled, and require no authentication for casual use.
Base URL: https://minecraft-java-servers.com/api/v1
Rate limit: 60 requests per hour per IP (anonymous). Need more? Contact us.
| Endpoint | Description | Cache |
|---|---|---|
GET /servers | Paginated list of servers. Filter with ?type=, ?version=, ?min_players=, ?page=, ?per_page= (max 100). | 60s |
GET /server/{id} | Full info on one server: name, IP, port, version, players, votes, types, country, uptime, description. | 60s |
GET /server/{id}/status | Live online/offline status and current player count. Best for status widgets. | 30s |
GET /server/{id}/history?period=7d | Player-count history. period = 24h (5-min raw), 7d or 30d (hourly buckets). | 5m |
GET /trending | Top 25 fastest-growing servers by 7-day average player change. Falls back to top-by-current-players while history is accumulating. | 5m |
GET /stats/versions | Minecraft version adoption across all tracked servers: server count and total players per version. | 1h |
curl https://minecraft-java-servers.com/api/v1/servers?type=Skyblock&per_page=10
curl https://minecraft-java-servers.com/api/v1/server/245/status
curl 'https://minecraft-java-servers.com/api/v1/server/245/history?period=7d'const res = await fetch('https://minecraft-java-servers.com/api/v1/server/245/status');
const { data } = await res.json();
console.log(`${data.players_online} players online`);import requests
r = requests.get('https://minecraft-java-servers.com/api/v1/trending')
for s in r.json()['data']:
print(s['name'], s.get('growth_pct', '—'))Every successful response wraps results in a data key. List responses include a meta key with pagination info. Errors return an error key with code and message.
{
"data": [
{ "id": 245, "name": "PikaNetwork", "players_online": 8421, "status": "online", ... }
],
"meta": { "page": 1, "per_page": 25, "total": 283, "total_pages": 12 }
}HTTP status codes follow REST conventions: 200 success, 400 bad request, 404 not found, 429 rate-limited, 500 server error. Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) accompany every response.
/server/{id}/status./server/{id}./trending./stats/versions on your launcher / hosting-service site.Building something cool with the API? Let us know — we'll feature it here.