API Developer MSID

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/public

Autentikasi

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 tersedia
RateLimit-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,
        "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}`

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",
      "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`

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

GET`/stats/overview`

Penghitung agregat untuk seluruh direktori: total server, berapa yang online, dan total pemain yang online saat ini.

Contoh

curl 'https://api.minecraftserver.id/api/v1/public/stats/overview'

{
  "success": true,
  "data": {
    "totalServers": 48,
    "onlineServers": 41,
    "totalPlayersOnline": 1862
  }
}

GET`/stats/ecosystem`

Potret keseluruhan: total, pembagian Java/Bedrock/cross-play, versi Minecraft dan tag terpopuler, penyedia hosting dan negara teratas, server teratas saat ini, dan seri pemain per hari selama 30 hari. Di-cache sebentar.

Contoh

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

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.

Webhook

Webhook bukan bagian dari API publik (read-only) ini. Webhook adalah notifikasi push yang dikonfigurasi owner per server di dashboard: tempel URL webhook Discord, pilih event (vote, milestone vote, server offline/online), dan kami yang mengirim pesannya. Karena URL-nya rahasia dan terkait satu server yang Anda miliki, pengaturannya ada di dashboard, bukan di endpoint publik ini.

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.

2026-06-24 - Menambahkan /stats/overview dan /stats/ecosystem. Menambahkan protocolVersion dan versionFamily pada objek server, serta hostProvider/hostCountry pada detail server.
2026-04-24 - Rilis awal. /servers, /servers/{slug}, /servers/{slug}/stats, /tags.

Ringkasan

Base URL

Autentikasi

Rate limit

Format respons

Endpoint

GET/servers

Parameter query

Contoh

GET/servers/{slug}

Parameter path

Contoh

GET/servers/{slug}/stats

Parameter query

Contoh

GET/tags

Contoh

GET/stats/overview

Contoh

GET/stats/ecosystem

Contoh

Kode error

Webhook

Atribusi

Changelog

GET`/servers`

GET`/servers/{slug}`

GET`/servers/{slug}/stats`

GET`/tags`

GET`/stats/overview`

GET`/stats/ecosystem`