REST API

Dokumentasi API

Integrasikan pelayan Minecraft secara langsung, pemain, kulit dan data komuniti daripada mcstat.org ke dalam apl, bot dan papan pemuka anda sendiri.

URL asas

Semua permintaan API bermula dengan URL asas ini

https://mcstat.org/api/v1

Lihat sebagai Markdown

Dokumentasi Markdown mentah untuk AI, bot dan alat

Kunci API

Urus dan pantau kunci API anda

Buat, putar dan lihat analitis untuk kunci API anda dalam papan pemuka.

Buka Papan Pemuka Kunci API

Taman Permainan API

Uji titik akhir terus dalam penyemak imbas

Semakan Bot

Taman permainan ini tidak memerlukan kunci API; pengesahan manusia diperlukan untuk mengurangkan penyalahgunaan.

Titik akhir

GET

/api/v1/servers

Parameter Pertanyaan

page

integer

limit

integer

sort

string

search

string

country

string

version

string

tag

string

mode

string

minPlayers

integer

maxPlayers

integer

minUptime

number

minVotes

integer

minRating

number

onlineOnly

boolean

Minta URL

https://mcstat.org/api/v1/servers

Jalankan permintaan untuk melihat respons

Pengesahan

Semua titik akhir API awam yang didokumenkan memerlukan kunci API. Hantar kunci anda dalam pengepala X-API-Key.

Pengepala permintaan

Tambahkan pengepala ini untuk mengesahkan

X-API-Key: mcs_your_key_here

Atau sebagai parameter pertanyaan

Atau lulus sebagai parameter pertanyaan

?api_key=mcs_your_key_here

Had kadar

Permintaan disahkan oleh kunci API. Kunci yang hilang atau tidak sah mengembalikan HTTP 401, kunci yang dilumpuhkan mengembalikan HTTP 403 dan had yang melebihi mengembalikan HTTP 429.

Tanpa kunci API

Tidak dibenarkan

Dengan kunci API

60 permintaan seminit, 1,000 sehari dan 30,000 sebulan secara lalai. Melebihi had mengembalikan HTTP 429 dengan pengepala X-RateLimit-* yang menunjukkan had anda dan Retry-After memberitahu anda apabila tetingkap ditetapkan semula. Had yang lebih tinggi boleh diberikan setiap kunci atas permintaan.

Pengepala Had Kadar:Respons 429 membawa X-RateLimit-Limit-Minit, X-RateLimit-Limit-Hari, X-RateLimit-Baki-Hari, X-RateLimit-Limit-Bulan, X-RateLimit-Baki-Bulan dan Cuba Semula Selepas. Respons yang berjaya membawa pengepala Kawalan Cache supaya anda boleh menyimpan hasil cache di sisi klien dengan selamat.

Format jawapan

Setiap respons yang berjaya ialah JSON dengan boolean dan objek . Ralat menggunakan sampul yang sama dengan : false.

Sambutan kejayaan

JSON

{
  "success": true,
  "data": {
    "resource": {
      "id": "...",
      "name": "Example"
    }
  }
}

Respons ralat

JSON

{
  "success": false,
  "error": "Too many requests"
}

Kesilapan

Kod status HTTP standard digunakan. Kes biasa:

Kod	Maknanya
`400`	Permintaan buruk — parameter tidak sah
`401`	Tanpa kebenaran — kunci API tiada atau tidak sah
`403`	Dilarang — kunci API dilumpuhkan
`404`	Tidak ditemui — sumber tidak wujud
`429`	Terlalu banyak permintaan — melebihi had kadar
`500`	Ralat pelayan dalaman — cuba lagi kemudian

Titik akhir pelayan

Semak imbas, tapis dan periksa pelayan Minecraft yang dijejaki oleh mcstat.org.

GET

/api/v1/servers

Senaraikan pelayan

Senarai pelayan awam bermuka surat dengan penapis kaya.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`20`	Item setiap halaman.
`sort`	`string`	Tidak	`recent`	Susun urutan.
`search`	`string`	Tidak	`—`	Pertanyaan teks percuma.
`country`	`string`	Tidak	`—`	Penapis nama negara ISO.
`version`	`string`	Tidak	`—`	Penapis versi Minecraft.
`tag`	`string`	Tidak	`—`	Tapis mengikut teg.
`mode`	`string`	Tidak	`—`	Penapis mod permainan.
`minPlayers`	`integer`	Tidak	`—`	Kiraan pemain semasa minimum.
`maxPlayers`	`integer`	Tidak	`—`	Kiraan pemain semasa maksimum.
`minUptime`	`number`	Tidak	`—`	Peratusan masa operasi minimum.
`minVotes`	`integer`	Tidak	`—`	Jumlah undian minimum.
`minRating`	`number`	Tidak	`—`	Penilaian minimum (1–5).
`onlineOnly`	`boolean`	Tidak	`—`	Hanya sertakan pelaporan pelayan dalam talian.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "shortDescription": "Home of over 35 unique games…",
        "ip": "mc.hypixel.net",
        "port": 25565,
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "motd": "Hypixel Network",
        "website": null,
        "discordUrl": null,
        "visibility": "PUBLIC",
        "isOnline": true,
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "version": "Requires MC 1.8 / 1.21",
        "latency": 42,
        "lastPing": "2026-05-24T22:00:00Z",
        "country": "United States",
        "tags": [
          "bedwars",
          "pvp",
          "skyblock"
        ],
        "gameMode": null,
        "uptime": 100,
        "trend": 3.4,
        "totalVotes": 12345,
        "rating": 4.6,
        "createdAt": "2026-04-28T05:44:26Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/servers/{slug}

Butiran pelayan

Profil pelayan penuh: sejarah statistik, masa beroperasi, carta undian, kedudukan.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`slug`	`string`	ya	`—`	Slug pelayan (dari / senarai pelayan).
`period`	`string`	Tidak	`24h`	Tetingkap masa: 24h, 7d, 30d, 90d, all-time.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "server": {
      "id": "JS6o0w88QP6oZHDj",
      "slug": "mchypixelnet",
      "name": "Hypixel Network",
      "ip": "mc.hypixel.net",
      "port": 25565,
      "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
      "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
      "motd": "Hypixel Network",
      "motdRaw": "§aHypixel §7Network",
      "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
      "website": null,
      "discordUrl": null,
      "storeUrl": null,
      "youtubeUrl": null,
      "currentPlayers": 48230,
      "maxPlayers": 200000,
      "isOnline": true,
      "country": "United States",
      "version": "Requires MC 1.8 / 1.21",
      "protocol": 767,
      "uptime": 100,
      "rating": 4.6,
      "totalVotes": 12345,
      "tags": [
        "bedwars",
        "pvp"
      ],
      "owner": null,
      "latestStats": {
        "onlinePlayers": 48230,
        "tps": 20,
        "timestamp": "2026-05-24T22:00:00Z"
      },
      "statsHistory": [
        {
          "timestamp": "2026-05-24T21:00:00Z",
          "onlinePlayers": 47000
        }
      ],
      "periodStats": {
        "24h": {
          "avgPlayers": 46500,
          "peakPlayers": 49100,
          "minPlayers": 42000,
          "uptimePct": 99.95
        }
      },
      "voteStats": {
        "24h": 412,
        "7d": 2890,
        "30d": 11200,
        "90d": 30150
      },
      "dailyVotes": [
        {
          "day": "2026-05-23",
          "votes": 405
        }
      ]
    }
  }
}

GET

/api/v1/servers/{slug}/voters

Pengundi pelayan

Pengundi terkini (disahkan dan tanpa nama) untuk pelayan yang diberikan.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/voters"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`slug`	`string`	ya	`—`	Slug pelayan (dari / senarai pelayan).
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`7`	Item setiap halaman.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "voters": [
      {
        "id": "TanfrbogDfzGdrgD",
        "minecraftUsername": "Notch",
        "votedAt": "2026-05-24 22:10:06.544",
        "type": "auth",
        "playerId": "xq5-Lw8xk7pEdKyn",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "skinUrl": "http://textures.minecraft.net/texture/cbea0a15a5ce…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "siteUsername": "notch"
      }
    ],
    "total": 12345,
    "page": 1,
    "totalPages": 515,
    "latestVoteAt": "2026-05-24 22:10:06.544"
  }
}

GET

/api/v1/servers/{slug}/reviews

Ulasan pelayan

Ulasan dan penilaian pemain berhalaman untuk pelayan.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/reviews"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`slug`	`string`	ya	`—`	Slug pelayan (dari / senarai pelayan).
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`5`	Item setiap halaman.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "5g4VgYUiN4n28qcX",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": null,
        "minecraftUsername": "chibibara",
        "rating": 3,
        "content": "Great community!",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z",
        "user": {
          "id": null,
          "username": "chibibara",
          "avatar": null,
          "role": "USER"
        },
        "playerId": "suTEw8opOK2bGP-L",
        "playerMainNickname": "chibibara",
        "playerMinecraftUuid": "019f1b29-fcbe-705b-8efb-8c08b4e0fd9c",
        "playerSkinUrl": null,
        "playerSkinModel": "classic",
        "playerLinkedSkinPngPath": "https://mcstat.org/media/skins/published/default-steve.png"
      }
    ],
    "total": 128,
    "page": 1,
    "totalPages": 26,
    "avgRating": 4.2,
    "latestReviewAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/{slug}/updates

Kemas kini pelayan

Siaran berita dan kemas kini diluluskan untuk pelayan.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/updates"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`slug`	`string`	ya	`—`	Slug pelayan (dari / senarai pelayan).
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`3`	Item setiap halaman.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "updates": [
      {
        "id": "Xk3pQ2mNbV8zR1sd",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": "Nf3kPq8sT2wVxJ7b",
        "title": "Season 5 is live!",
        "content": "New map, new kits, double XP weekend.",
        "status": "APPROVED",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "totalPages": 4,
    "latestUpdateAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/top

Pelayan teratas

Senarai sohor kini dioptimumkan untuk penggunaan halaman utama/widget.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/top"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`sort`	`string`	Tidak	`votes`	Susun urutan.
`limit`	`integer`	Tidak	`10`	Item setiap halaman.
`country`	`string`	Tidak	`—`	Penapis nama negara ISO.
`gameMode`	`string`	Tidak	`—`	Penapis mod permainan.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "ip": "mc.hypixel.net",
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "totalVotes": 12345,
        "uptime": 100,
        "trend": 3.4,
        "recentVotes": 412,
        "hotScore": 9821
      }
    ],
    "total": 1240,
    "sort": "hot"
  }
}

GET

/api/v1/servers/countries

Negara pelayan

Kiraan agregat pelayan dikumpulkan mengikut negara.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/countries"

Parameter Pertanyaan

Tiada parameter

Contoh respons

JSON

{
  "success": true,
  "data": {
    "countries": [
      {
        "country": "United States",
        "serverCount": 2840
      }
    ]
  }
}

GET

/api/v1/servers/versions

Versi pelayan

Kiraan agregat pelayan dikumpulkan mengikut versi Minecraft.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/versions"

Parameter Pertanyaan

Tiada parameter

Contoh respons

JSON

{
  "success": true,
  "data": {
    "versions": [
      {
        "version": "Paper 1.21.11",
        "serverCount": 980
      }
    ]
  }
}

Titik akhir pemain

Cari profil pemain, sesi, peringkat dan sejarah.

GET

/api/v1/players

Senaraikan pemain

Direktori pemain awam bernombor.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`—`	Item setiap halaman.
`sort`	`string`	Tidak	`recent`	Susun urutan.
`search`	`string`	Tidak	`—`	Pertanyaan teks percuma.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "players": [
      {
        "id": "h6tC6lGfBEDulI8o",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "mainNickname": "Notch",
        "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "country": "United States",
        "tierOverall": "HT1",
        "tierPoints": 9820,
        "tierRank": 12,
        "lastTierSyncAt": "2026-05-24T20:00:00Z",
        "createdAt": "2026-04-01T10:00:00Z",
        "totalPlayTime": 184320,
        "sessionCount": 412
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/players/{id}

Perincian pemain

Profil, sesi baru-baru ini, pelayan dimainkan, K/D, pencapaian.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players/069a79f4-44e9-4726-a5be-fca90e38aaf5"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`id`	`string`	ya	`—`	ID pemain, UUID atau nama panggilan.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "player": {
      "id": "h6tC6lGfBEDulI8o",
      "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
      "mainNickname": "Notch",
      "nicknameHistory": [
        "Notch"
      ],
      "country": null,
      "skinModel": "classic",
      "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
      "linkedSkinId": "Wi_n1dUvFqgJs0aP",
      "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
      "linkedSkin": {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "player-skin-notch",
        "pngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "model": "classic",
        "name": "Notch's Skin"
      },
      "tierOverall": "MCStat Mythic",
      "tierPoints": 9820,
      "tierRank": 12,
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-05-24T22:00:00Z",
      "totalPlayTime": 184320,
      "sessionCount": 412,
      "rankScore": 9820,
      "rank": 12,
      "recentSessions": [
        {
          "id": "oWZiF6jq_UnEs7Y3",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          },
          "joinedAt": "2026-05-24T20:00:00Z",
          "leftAt": "2026-05-24T21:00:00Z",
          "totalPlayTime": 3600
        }
      ],
      "serversPlayed": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
        }
      ],
      "latestStats": {
        "statsJson": {
          "kills": 18230,
          "deaths": 9850,
          "wins": 1240
        },
        "timestamp": "2026-05-24T21:00:00Z",
        "server": {
          "slug": "mchypixelnet",
          "name": "Hypixel Network"
        }
      },
      "statsHistory": [
        {
          "statsJson": {
            "kills": 18000,
            "deaths": 9700
          },
          "timestamp": "2026-05-24T20:00:00Z",
          "serverName": "Hypixel Network"
        }
      ],
      "kdRatio": 1.85,
      "totalKills": 18230,
      "totalDeaths": 9850,
      "totalWins": 1240,
      "activityData": [
        {
          "date": "2026-05-24",
          "count": 3
        }
      ],
      "achievements": {
        "earned": [
          {
            "id": "top10",
            "label": "Top 10",
            "labelTr": "İlk 10",
            "labelRu": "Топ 10",
            "icon": "medal"
          }
        ],
        "nextGoals": [
          {
            "id": "explorer_25",
            "label": "Globe Trotter",
            "labelTr": "Dünya Gezgini",
            "labelRu": "Путешественник",
            "icon": "plane"
          }
        ]
      },
      "votedServers": [
        {
          "serverId": "JS6o0w88QP6oZHDj",
          "serverSlug": "mchypixelnet",
          "serverName": "Hypixel Network",
          "serverIconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "votedAt": "2026-05-24T22:10:00Z"
        }
      ],
      "reviews": [
        {
          "id": "Rv8xKp2mNq7wTz1a",
          "rating": 5,
          "content": "Great server!",
          "createdAt": "2026-05-20T10:00:00Z",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          }
        }
      ]
    }
  }
}

Cari

Carian bersatu merentasi pelayan dan pemain.

GET

/api/v1/search

Carian global

Cari pelayan dan pemain dalam satu panggilan.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/search"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`q`	`string`	ya	`—`	Pertanyaan carian (2–100 aksara).
`type`	`string`	Tidak	`all`	Jenis keputusan: all, servers, players.
`limit`	`integer`	Tidak	`10`	Item setiap halaman.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "results": {
      "servers": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
          "currentPlayers": 48230,
          "maxPlayers": 200000,
          "isOnline": true,
          "rating": 3.4
        }
      ],
      "players": [
        {
          "id": "h6JDPuUGKI3Mfw3m",
          "minecraftUuid": "de5f2979-1168-43d6-b5f3-e18f975a806b",
          "mainNickname": "Notch",
          "createdAt": "2026-04-01T10:00:00Z",
          "updatedAt": "2026-05-24T22:00:00Z"
        }
      ]
    },
    "query": "hypixel"
  }
}

Statistik langsung & Global

Aktiviti global masa nyata, pecahan wilayah dan negara.

GET

/api/v1/live

Statistik langsung

Jumlah dalam talian global, pelayan teratas, aktiviti terkini, pecahan wilayah dan negara.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live"

Parameter Pertanyaan

Tiada parameter

Contoh respons

JSON

{
  "success": true,
  "data": {
    "stats": {
      "totalPlayers": 184320,
      "totalServers": 12480,
      "onlineServers": 9821,
      "newPlayersToday": 412,
      "peakToday": 202700,
      "generatedAt": "2026-05-24T22:00:00Z",
      "latestPingAt": "2026-05-24T21:59:48Z",
      "statsAgeSeconds": 18,
      "stale": false
    },
    "topServers": [
      {
        "id": "mchypixelnet",
        "name": "Hypixel Network",
        "players": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "trend": "up",
        "change": 240
      }
    ],
    "recentActivity": [
      {
        "type": "vote",
        "actor": "Notch",
        "target": "Hypixel Network",
        "time": "2026-05-24T22:00:00Z"
      }
    ],
    "regions": [
      {
        "id": "na",
        "name": "North America",
        "players": 80120,
        "servers": 4120
      }
    ],
    "countryPlayers": {
      "United States": 60120,
      "Germany": 18230
    }
  }
}

GET

/api/v1/live/history

Sejarah langsung

Baldi setiap jam daripada jumlah pemain dalam talian sepanjang 7 hari lalu.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live/history"

Parameter Pertanyaan

Tiada parameter

Contoh respons

JSON

{
  "success": true,
  "data": {
    "history": [
      {
        "timestamp": "2026-05-23T22:00:00Z",
        "totalPlayers": 174200
      }
    ]
  }
}

Papan pendahulu

Kedudukan pemain teratas mengikut sesi, pelayan atau mata peringkat.

GET

/api/v1/leaderboards

Papan pendahulu

Pemain teratas untuk penapis metrik, tempoh, peringkat dan pencapaian yang dipilih.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/leaderboards"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`metric`	`string`	Tidak	`best`	Metrik kedudukan: best, sessions, servers.
`period`	`string`	Tidak	`all-time`	Tetingkap masa: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`20`	Item setiap halaman.
`tier`	`string`	Tidak	`—`	Penapis peringkat.
`achievement`	`string`	Tidak	`—`	Penapis pencapaian.
`search`	`string`	Tidak	`—`	Pertanyaan teks percuma.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "leaderboard": {
      "metric": "best",
      "period": "all-time",
      "serverId": null,
      "generatedAt": "2026-05-24T22:00:00Z",
      "entries": [
        {
          "rank": 1,
          "player": {
            "id": "Vz2BaB2r6eC9TL_o",
            "mainNickname": "Notch",
            "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
            "tierOverall": "MCStat Mythic",
            "tierPoints": 224606,
            "tierRank": 1,
            "skinModel": "classic",
            "skinUrl": "http://textures.minecraft.net/texture/d71c3adef2ec…",
            "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png"
          },
          "value": 224606,
          "formattedValue": "224,606 score"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

Kulit & Jubah

Cari kulit dan jubah yang dimuat naik komuniti.

GET

/api/v1/skins

Senaraikan kulit

Semak imbas muat naik kulit komuniti dengan isihan/tapis.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`24`	Item setiap halaman.
`sort`	`string`	Tidak	`recent`	Susun urutan.
`model`	`string`	Tidak	`—`	Model kulit: klasik atau langsing.
`search`	`string`	Tidak	`—`	Pertanyaan teks percuma.
`tag`	`string`	Tidak	`—`	Tapis mengikut teg.
`owner`	`string`	Tidak	`—`	Penapis nama pengguna pemilik.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "skins": [
      {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "cool-knight",
        "name": "Cool Knight",
        "model": "classic",
        "tags": [
          "medieval",
          "armor"
        ],
        "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
        "viewCount": 3120,
        "likeCount": 124,
        "favoriteCount": 88,
        "downloadCount": 980,
        "usageCount": 12,
        "isFeatured": false,
        "createdAt": "2026-05-01T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/skins/{slug}

Perincian kulit

Metadata kulit penuh serta keadaan suka/kegemaran penonton.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins/hypixel-net"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`slug`	`string`	ya	`—`	Slug pelayan (dari / senarai pelayan).

Contoh respons

JSON

{
  "success": true,
  "data": {
    "skin": {
      "id": "Wi_n1dUvFqgJs0aP",
      "slug": "cool-knight",
      "name": "Cool Knight",
      "description": "Custom medieval knight skin",
      "tags": [
        "medieval",
        "armor"
      ],
      "model": "classic",
      "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
      "viewCount": 3120,
      "likeCount": 124,
      "favoriteCount": 88,
      "downloadCount": 980,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "tierOverall": "MCStat Mythic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/cool-knight.png"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

GET

/api/v1/capes

Senaraikan jubah

Semak imbas muat naik tanjung komuniti dengan isihan/tapis.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`page`	`integer`	Tidak	`1`	Nombor halaman, bermula pada 1.
`limit`	`integer`	Tidak	`24`	Item setiap halaman.
`sort`	`string`	Tidak	`recent`	Susun urutan.
`search`	`string`	Tidak	`—`	Pertanyaan teks percuma.
`tag`	`string`	Tidak	`—`	Tapis mengikut teg.
`owner`	`string`	Tidak	`—`	Penapis nama pengguna pemilik.

Contoh respons

JSON

{
  "success": true,
  "data": {
    "capes": [
      {
        "id": "De-jbTlj_PTnJJ5N",
        "slug": "royal-red",
        "name": "Royal Red",
        "tags": [
          "red",
          "royal"
        ],
        "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
        "viewCount": 210,
        "likeCount": 18,
        "favoriteCount": 6,
        "downloadCount": 44,
        "isFeatured": false,
        "createdAt": "2026-05-02T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/capes/{slug}

Butiran cape

Metadata cape penuh serta status suka/kegemaran penonton.

Contoh permintaan

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes/hypixel-net"

Parameter Pertanyaan

Nama	taip	diperlukan	lalai	Penerangan
`slug`	`string`	ya	`—`	Slug pelayan (dari / senarai pelayan).

Contoh respons

JSON

{
  "success": true,
  "data": {
    "cape": {
      "id": "De-jbTlj_PTnJJ5N",
      "slug": "royal-red",
      "name": "Royal Red",
      "description": "Deep red royal cape",
      "tags": [
        "red",
        "royal"
      ],
      "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
      "viewCount": 210,
      "likeCount": 18,
      "favoriteCount": 6,
      "downloadCount": 44,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
          "tierOverall": "MCStat Mythic"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}