Free public API · no key
Search thousands of listed servers, look one up by address, and read its player history as plain JSON. No key, no sign-up, CORS on.
$ curl 'https://newminecraftservers.net/api/v1/servers?sort=ranked&limit=5' { "data": { "items": [ { "id": "server_da387cec01cbd54c61a0cede", "slug": "mchub", "name": "McHub", "classification": { "genreIds": ["prison", "pvp", "skyblock", "vanilla"], "crossplay": true }, "country": "United States", "primaryConnection": { "edition": "java", "host": "ms.mchub.com", "port": 25565, "latest": { "outcome": "online", "observedAt": "2026-09-21T16:00:00.000Z", "playersOnline": 44707, "playersMax": 44708, "versionName": "BungeeCord 1.8.x-26.3x" } }, "availableEditions": ["bedrock", "java"] } ], "page": 1, "pageSize": 1, "total": 10907, "totalPages": 10907, "sort": "ranked" } }
Quick start
Every endpoint is a plain GET under https://newminecraftservers.net/api/v1. Successful responses wrap the result in data; failures return error with a stable code and a readable message. Dates are ISO 8601 strings in UTC.
The list response carries page, total and totalPages, so paging is a loop until page reaches totalPages.
curl 'https://newminecraftservers.net/api/v1/servers?sort=ranked&limit=5'Reference
GET/api/v1/servers
Published servers with their latest check: players online, version, MOTD, icon and gamemodes. Filter by text, gamemode, edition or online state.
qsortmodeeditionoutcomefamilypagelimitGET/api/v1/servers/{slug}
Everything public about one listing: description, every connection (Java and Bedrock), links, awards and when we first and last saw it.
slugGET/api/v1/servers/lookup
Find the listing behind an address someone typed. Matches stored addresses only: it never resolves DNS or pings the server.
addressGET/api/v1/servers/{slug}/history
Bucketed player counts, uptime, peak and average players, version changes and the busiest UTC hour, from our own stored checks.
rangeGET/api/v1/minecraft-status
Are Minecraft sign-in, session, skin and Realms services up? Current state, 24-hour timelines, uptime and incidents from our background monitor.
{
"data": {
"items": [
{
"id": "server_da387cec01cbd54c61a0cede",
"slug": "mchub",
"name": "McHub",
"classification": {
"genreIds": ["prison", "pvp", "skyblock", "vanilla"],
"crossplay": true
},
"country": "United States",
"primaryConnection": {
"edition": "java",
"host": "ms.mchub.com",
"port": 25565,
"latest": {
"outcome": "online",
"observedAt": "2026-09-21T16:00:00.000Z",
"playersOnline": 44707,
"playersMax": 44708,
"versionName": "BungeeCord 1.8.x-26.3x"
}
},
"availableEditions": ["bedrock", "java"]
}
],
"page": 1,
"pageSize": 1,
"total": 10907,
"totalPages": 10907,
"sort": "ranked"
}
}Every field and type is in the OpenAPI specification. Load it into Swagger UI, Postman or a client generator.
Good to know
Every endpoint here is an anonymous GET. There is nothing to register and no token to rotate.
Responses send Access-Control-Allow-Origin: *, so a web page on any domain can call the API directly.
Lists and servers cache for 30 seconds, history for 60. Nothing you call makes us ping a server or Mojang.
The limit parameter caps at 25. Page through with page and cache on your side instead of re-fetching the whole list.
Player counts come from our scheduled checks of each server, not a ping made when you ask.
Names, MOTDs and descriptions are written by server owners. Render them as plain text, never as HTML.
Errors
Branch on error.code, not the message; messages may be reworded. Error responses are never cached.
{
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 25"
}
}| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter is unknown, repeated or out of range. The message says which. |
| 404 | not_found | No published server has that slug or stored address. |
| 405 | method_not_allowed | Public endpoints are read-only. Use GET. |
| 500 | internal_error | A read failed on our side. Details are not exposed; retry later. |
Built on this API
In-game /nms lookup and /nms stats read the same lookup and history endpoints. A server linked through the plugin can also read its own 90-day history.
/servers/lookup/servers/{slug}/history
The new tab page lists popular and new servers and shows whether Minecraft sign-in is up, from the list and status endpoints.
/servers/minecraft-status
The API serves what we have already checked. To query any Java or Bedrock address live, with its players, version, MOTD and ping, use the free status checker.
FAQ
Yes. The public read endpoints are free and need no API key or account. Please cache responses and send a User-Agent that names your project so we can reach you if something goes wrong.
No. Every response comes from checks we have already stored, so reading the API never contacts a server. To ping any address right now, use our free Minecraft server status checker instead.
There is no published per-client quota today, and no uptime guarantee. Lists are capped at 25 results and cached for 30 seconds, so polling faster than that returns the same data. Heavy or bulk use may be limited without notice.
The same published servers you can browse on the site, Java and Bedrock. Hidden listings never appear, and lookup only matches addresses already on the list.
The full OpenAPI 3.0 file is at /openapi.json. Load it into Swagger UI, Postman or a code generator to get every field and type.
Yes. /api/v1/minecraft-status returns the state of the Microsoft and Mojang sign-in, session and Realms services from our monitor, with 24-hour timelines and recent incidents.
Email [email protected] to tell us, or to ask for a field you need. Using the API means accepting our terms and privacy policy.
