Overview
The MSID public API exposes the same server listings, details, and daily stats that power minecraftserver.id, in a format suitable for Discord bots, owner dashboards, analytics tools, or any third-party integration. It is read-only, requires no authentication, and is free to use within the rate limits described below. Attribution is required, see the Attribution section.
Base URL
All endpoints live under the following base URL. Paths below are relative to this base.
https://api.minecraftserver.id/api/v1/publicAuthentication
None required. All endpoints are public. Do not send an Authorization header; it will be ignored. API keys are not offered at this time.
Rate limits
The public API is limited to 60 requests per minute per client IP. The limit is shared across all /api/v1/public/* endpoints. When exceeded, the API returns HTTP 429 with the standard error envelope. Every response includes the following headers so your client can pace itself:
RateLimit-Limit - the ceiling for this window (60)RateLimit-Remaining - requests you have leftRateLimit-Reset - seconds until the window resets
Response format
Successful responses wrap the result in a data field:
{
"success": true,
"data": { ... }
}Errors use a consistent envelope with a machine-readable code and a human-readable message:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid query parameters"
}
}Endpoints
GET/servers
Paginated list of non-deleted servers. Supports filtering by edition, status, verified flag, tag, free-text search, and sorting.
Query parameters
| page | Page number (default 1) |
| limit | Results per page, max 50 (default 20) |
| q | Case-insensitive search across server name and description (2–100 chars) |
| edition | JAVA, BEDROCK, or CROSS_PLAY |
| tag | One of the predefined tag values (see /tags) |
| status | ONLINE or OFFLINE |
| verified | true or false - filter to MOTD-verified servers only |
| sort | score (default), votes, players, or newest |
Example
curl 'https://api.minecraftserver.id/api/v1/public/servers?limit=10&sort=votes&edition=JAVA'{
"success": true,
"data": {
"servers": [
{
"slug": "example-smp",
"name": "Example SMP",
"description": "A friendly survival server…",
"address": "play.example.com",
"port": 25565,
"edition": "JAVA",
"status": "ONLINE",
"currentPlayers": 42,
"maxPlayers": 100,
"version": "1.21.4",
"protocolVersion": 769,
"versionFamily": "1.21.x",
"uptimePercent30d": 98.7,
"iconUrl": "https://cdn.minecraftserver.id/…",
"bannerUrl": null,
"score": 95.5,
"monthlyVotes": 1240,
"rank": 1,
"isVerified": true,
"tags": ["Survival", "SMP"],
"owner": { "username": "owner1" }
}
],
"total": 48,
"page": 1,
"totalPages": 5
}
}GET/servers/{slug}
Full detail for a single server, including MOTD, 30-day uptime, contacts, owner, and the current month's top voters.
Path parameters
| slug | The server slug (the stable identifier in the URL) |
Returns HTTP 404 with error code SERVER_NOT_FOUND when no active server matches the slug.
Example
curl 'https://api.minecraftserver.id/api/v1/public/servers/example-smp'{
"success": true,
"data": {
"server": {
"slug": "example-smp",
"name": "Example SMP",
"description": "A friendly survival server…",
"address": "play.example.com",
"port": 25565,
"bedrockAddress": null,
"bedrockPort": null,
"edition": "JAVA",
"status": "ONLINE",
"currentPlayers": 42,
"maxPlayers": 100,
"version": "1.21.4",
"protocolVersion": 769,
"versionFamily": "1.21.x",
"motd": "§6Welcome§r to the server!",
"iconUrl": "https://cdn.minecraftserver.id/…",
"bannerUrl": null,
"uptimePercent30d": 99.5,
"score": 95.5,
"monthlyVotes": 1240,
"rank": 1,
"isVerified": true,
"hostProvider": "OVH SAS",
"hostCountry": "SG",
"createdAt": "2026-01-15T10:00:00.000Z",
"tags": ["Survival", "SMP"],
"contacts": [
{ "type": "DISCORD", "value": "https://discord.gg/example" }
],
"owner": {
"username": "owner1",
"displayName": "Server Owner",
"avatarUrl": "https://cdn.minecraftserver.id/…"
},
"topVoters": [
{ "minecraftUsername": "Steve", "votes": 28 },
{ "minecraftUsername": "Alex", "votes": 25 }
]
}
}
}GET/servers/{slug}/stats
Daily uptime, average player count, and vote totals for a server. Returns one data point per day for both the selected period and the equivalent previous period (for comparison). Dates are ISO (YYYY-MM-DD).
Query parameters
| days | 30, 60, or 90 (default 30) |
Example
curl 'https://api.minecraftserver.id/api/v1/public/servers/example-smp/stats?days=30'{
"success": true,
"data": {
"server": { "name": "Example SMP", "slug": "example-smp" },
"days": 30,
"current": [
{ "date": "2026-03-26", "uptimePercent": 99.8, "avgPlayers": 38.5, "totalVotes": 41 },
...
],
"previous": [
{ "date": "2026-02-24", "uptimePercent": 99.2, "avgPlayers": 35.2, "totalVotes": 38 },
...
]
}
}GET/tags
The full list of server-tag values accepted by the listings API, plus the maximum number of tags a server can have.
Example
curl 'https://api.minecraftserver.id/api/v1/public/tags'{
"success": true,
"data": {
"tags": ["Survival", "Creative", "SkyBlock", ...],
"maxPerServer": 5
}
}GET/stats/overview
Aggregate counters for the whole directory: total servers, how many are online, and total players online right now.
Example
curl 'https://api.minecraftserver.id/api/v1/public/stats/overview'{
"success": true,
"data": {
"totalServers": 48,
"onlineServers": 41,
"totalPlayersOnline": 1862
}
}GET/stats/ecosystem
A snapshot of the scene: totals, the Java/Bedrock/cross-play split, the most common Minecraft versions and tags, top hosting providers and countries, the current top servers, and a 30-day players-per-day series. Cached briefly.
Example
curl 'https://api.minecraftserver.id/api/v1/public/stats/ecosystem'{
"success": true,
"data": {
"totals": {
"servers": 48, "online": 41, "playersOnline": 1862,
"totalVotes": 51200, "avgUptime30d": 98.1, "newThisMonth": 6
},
"editions": [ { "edition": "CROSS_PLAY", "count": 27 }, ... ],
"topVersions": [ { "key": "1.21.x", "count": 39 }, ... ],
"topTags": [ { "key": "Survival", "count": 22 }, ... ],
"topProviders": [ { "key": "OVH SAS", "count": 9 }, ... ],
"topCountries": [ { "key": "SG", "count": 31 }, ... ],
"topServers": [ { "slug": "example-smp", "name": "Example SMP", "iconUrl": null, "value": 95.5 }, ... ],
"playersTrend": [ { "date": "2026-05-26", "value": 1740 }, ... ],
"generatedAt": "2026-06-24T12:00:00.000Z"
}
}Error codes
Errors always have HTTP status ≥ 400 and the envelope shown in the response format section. The most common codes:
| Code | Meaning |
|---|---|
| VALIDATION_ERROR | Query or path parameter failed validation. |
| SERVER_NOT_FOUND | The slug did not match an active (non-deleted) server. |
| INVALID_SLUG | The slug parameter was missing or empty. |
| RATE_LIMITED | You exceeded 60 requests per minute. Back off and check the RateLimit-Reset header. |
Webhooks
Webhooks are not part of this (read-only) public API. They are owner-configured push notifications set up per server in the dashboard: paste a Discord webhook URL, pick the events (vote, vote milestone, server offline/online), and we send the message. Because the URL is a secret tied to one server you own, it lives in the dashboard rather than on this public endpoint.
Attribution
When you display data from this API in a product, please credit "minecraftserver.id" somewhere visible to the end user, a link back to the server's detail page on minecraftserver.id is the preferred form. This helps server owners find new audiences and keeps the data free to access.
Changelog
Breaking changes will bump the version prefix (/api/v1/ → /api/v2/). Non-breaking additions ship under the current version.
- 2026-06-24 - Added /stats/overview and /stats/ecosystem. Added protocolVersion and versionFamily to server objects, and hostProvider/hostCountry to server detail.
- 2026-04-24 - Initial release. /servers, /servers/{slug}, /servers/{slug}/stats, /tags.