Ringkasan
API publik MSID mengekspos daftar server, detail, dan statistik harian yang sama dengan yang digunakan di minecraftserver.id, dalam format yang cocok untuk bot Discord, dashboard owner, tool analitik, atau integrasi pihak ketiga lainnya. API ini read-only, tidak memerlukan autentikasi, dan gratis selama masih dalam batas rate limit yang dijelaskan di bawah. Atribusi diwajibkan — lihat bagian Atribusi.
Base URL
Seluruh endpoint berada di bawah base URL berikut. Path di bawah bersifat relatif terhadap base URL ini.
https://api.minecraftserver.id/api/v1/publicAutentikasi
Tidak perlu. Seluruh endpoint bersifat publik. Jangan mengirim header Authorization; akan diabaikan. API key belum tersedia saat ini.
Rate limit
API publik dibatasi 60 request per menit per IP klien. Batas ini berlaku untuk seluruh endpoint /api/v1/public/*. Jika terlampaui, API mengembalikan HTTP 429 dengan envelope error standar. Setiap respons menyertakan header berikut agar klien Anda dapat mengatur tempo:
RateLimit-Limit — batas maksimum per window (60)RateLimit-Remaining — sisa request yang tersediaRateLimit-Reset — detik hingga window berikutnya
Format respons
Respons sukses membungkus hasil dalam field data:
{
"success": true,
"data": { ... }
}Error memakai envelope yang konsisten dengan kode yang machine-readable dan pesan yang human-readable:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid query parameters"
}
}Endpoint
GET/servers
Daftar server non-terhapus dengan paginasi. Mendukung filter berdasarkan edition, status, flag verified, tag, pencarian teks bebas, dan sorting.
Parameter query
| page | Nomor halaman (default 1) |
| limit | Hasil per halaman, maksimum 50 (default 20) |
| q | Pencarian case-insensitive pada nama dan deskripsi server (2–100 karakter) |
| edition | JAVA, BEDROCK, atau CROSS_PLAY |
| tag | Salah satu nilai tag yang telah ditentukan (lihat /tags) |
| status | ONLINE atau OFFLINE |
| verified | true atau false — filter hanya server terverifikasi MOTD |
| sort | score (default), votes, players, atau newest |
Contoh
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,
"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}
Detail lengkap satu server, mencakup MOTD, uptime 30 hari, kontak, pemilik, dan top voters bulan berjalan.
Parameter path
| slug | Slug server (identifier stabil di URL) |
Mengembalikan HTTP 404 dengan kode error SERVER_NOT_FOUND jika tidak ada server aktif yang cocok dengan slug.
Contoh
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",
"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,
"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
Uptime harian, rata-rata jumlah pemain, dan total vote untuk sebuah server. Mengembalikan satu data point per hari untuk periode yang dipilih dan periode sebelumnya (sebagai pembanding). Tanggal dalam format ISO (YYYY-MM-DD).
Parameter query
| days | 30, 60, atau 90 (default 30) |
Contoh
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
Daftar lengkap nilai tag server yang diterima API listing, plus jumlah tag maksimum per server.
Contoh
curl 'https://api.minecraftserver.id/api/v1/public/tags'{
"success": true,
"data": {
"tags": ["Survival", "Creative", "SkyBlock", ...],
"maxPerServer": 5
}
}Kode error
Error selalu memiliki HTTP status ≥ 400 dan memakai envelope yang ditunjukkan di bagian format respons. Kode yang umum:
| Code | Meaning |
|---|---|
| VALIDATION_ERROR | Parameter query atau path gagal divalidasi. |
| SERVER_NOT_FOUND | Slug tidak cocok dengan server aktif (non-terhapus). |
| INVALID_SLUG | Parameter slug hilang atau kosong. |
| RATE_LIMITED | Melebihi 60 request per menit. Turunkan tempo dan cek header RateLimit-Reset. |
Atribusi
Bila Anda menampilkan data dari API ini dalam produk, mohon kredit "minecraftserver.id" di tempat yang terlihat oleh end user — idealnya berupa link balik ke halaman detail server di minecraftserver.id. Ini membantu owner server menjangkau audiens baru dan menjaga data tetap gratis diakses.
Changelog
Breaking change akan menaikkan prefiks versi (/api/v1/ → /api/v2/). Tambahan non-breaking dirilis di versi berjalan.
- Developers.changelog.initialRelease