REST API

API文件

將來自 mcstat.org 的即時 Minecraft 伺服器、玩家、皮膚和社群數據整合到您自己的應用程式、機器人和儀表板中。

基本網址

所有 API 請求都以此基本 URL 開頭

https://mcstat.org/api/v1

以 Markdown 檢視

供 AI、機器人與工具使用的原始 Markdown 文件

API 金鑰

管理和監控您的 API 金鑰

在儀表板中建立、輪換和查看 API 金鑰的分析。

開啟 API 金鑰儀表板

API 遊樂場

直接在瀏覽器中測試端點

機器人驗證

此測試環境無需 API 金鑰；需要人工驗證以減少濫用。

端點

GET

/api/v1/servers

查詢參數

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

請求網址

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

運行請求以查看回應

認證

所有記錄的公共 API 端點都需要 API 金鑰。在 X-API-Key 標頭中傳送您的金鑰。

請求頭

新增此標頭以進行身份驗證

X-API-Key: mcs_your_key_here

或作為查詢參數

或作為查詢參數傳遞

?api_key=mcs_your_key_here

速率限制

請求透過 API 金鑰進行身份驗證。金鑰缺失或無效傳回 HTTP 401；超出限制回傳 HTTP 429。

沒有 API 金鑰

不允許

帶有 API 金鑰

今天同樣是中等級別，具有歸因和優先隊列。付費方案將提供更高級別的服務。

速率限制標頭：每個回應都包含一個 Cache-Control 標頭，以便您可以安全地在用戶端快取結果。

回應格式

每個成功的回應都是帶有布林值和物件的 JSON。錯誤與使用相同的信封： false。

成功回應

JSON

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

錯誤回應

JSON

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

錯誤

使用標準 HTTP 狀態碼。常見案例：

程式碼	意義
`400`	錯誤的請求－無效的參數
`401`	未經授權 - API 金鑰遺失或無效
`404`	未找到 — 資源不存在
`429`	請求過多 — 超出速率限制
`500`	內部伺服器錯誤 — 稍後重試

伺服器端點

瀏覽、過濾和檢查 mcstat.org 追蹤的 Minecraft 伺服器。

GET

/api/v1/servers

列出伺服器

具有豐富過濾器的公共伺服器的分頁清單。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`20`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`search`	`string`	否	`—`	自由文字查詢。
`country`	`string`	否	`—`	ISO 國家/地區名稱過濾器。
`version`	`string`	否	`—`	我的世界版本過濾器。
`tag`	`string`	否	`—`	按標籤過濾。
`mode`	`string`	否	`—`	遊戲模式過濾器。
`minPlayers`	`integer`	否	`—`	最小當前玩家數量。
`maxPlayers`	`integer`	否	`—`	當前最大玩家數量。
`minUptime`	`number`	否	`—`	最小正常運轉時間百分比。
`minVotes`	`integer`	否	`—`	最低總票數。
`minRating`	`number`	否	`—`	最低評級 (1–5)。
`onlineOnly`	`boolean`	否	`—`	僅包括在線報告的伺服器。

回應範例

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}

伺服器詳細信息

完整的伺服器設定檔：統計歷史記錄、正常運作時間、投票圖表、排名。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`period`	`string`	否	`24h`	時間窗口：24h, 7d, 30d, 90d, all-time.

回應範例

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

伺服器投票者

給定伺服器的最近投票者（經過身份驗證的和匿名的）。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`7`	每頁的項目。

回應範例

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

伺服器評價

伺服器的分頁玩家評價與評分。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`5`	每頁的項目。

回應範例

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

伺服器動態

伺服器已核准的新聞與更新貼文。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`3`	每頁的項目。

回應範例

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

頂級伺服器

針對主頁/小部件使用進行了最佳化的趨勢清單。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`sort`	`string`	否	`votes`	排序順序。
`limit`	`integer`	否	`10`	每頁的項目。
`country`	`string`	否	`—`	ISO 國家/地區名稱過濾器。
`gameMode`	`string`	否	`—`	遊戲模式過濾器。

回應範例

JSON

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

伺服器國家

按國家/地區分組的伺服器總數。

請求範例

cURL

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

查詢參數

無參數

回應範例

JSON

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

GET

/api/v1/servers/versions

伺服器版本

按 Minecraft 版本分組的伺服器總數。

請求範例

cURL

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

查詢參數

無參數

回應範例

JSON

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

玩家端點

尋找玩家檔案、會話、等級和歷史記錄。

GET

/api/v1/players

列出球員

分頁的公開玩家目錄。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`—`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`search`	`string`	否	`—`	自由文字查詢。

回應範例

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}

球員詳情

個人資料、最近的會話、所玩的伺服器、K/D、成就。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`id`	`string`	是的	`—`	玩家 ID、UUID 或暱稱。

回應範例

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

搜尋

跨伺服器與玩家的統一搜尋。

GET

/api/v1/search

全球搜尋

一次呼叫即可搜尋伺服器與玩家。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`q`	`string`	是的	`—`	搜尋查詢（2–100 個字元）。
`type`	`string`	否	`all`	結果類型：all, servers, players.
`limit`	`integer`	否	`10`	每頁的項目。

回應範例

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

即時和全球統計數據

即時全球活動、地區和國家詳細資訊。

GET

/api/v1/live

即時統計

全球線上總數、頂級伺服器、近期活動、地區和國家細分。

請求範例

cURL

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

查詢參數

無參數

回應範例

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

活生生的歷史

過去 7 天內每小時的線上玩家總數。

請求範例

cURL

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

查詢參數

無參數

回應範例

JSON

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

排行榜

按會話、伺服器或等級積分排名的頂級玩家。

GET

/api/v1/leaderboards

排行榜

選定指標、期間、等級和成就濾鏡的頂級玩家。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`metric`	`string`	否	`best`	排名指標：best, sessions, servers.
`period`	`string`	否	`all-time`	時間窗口：24h, 7d, 30d, 90d, all-time.
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`20`	每頁的項目。
`tier`	`string`	否	`—`	層過濾器。
`achievement`	`string`	否	`—`	成就過濾器。
`search`	`string`	否	`—`	自由文字查詢。

回應範例

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

皮膚和斗篷

搜尋社群上傳的皮膚和斗篷。

GET

/api/v1/skins

列出皮膚

使用排序/過濾器瀏覽社群上傳的皮膚。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`24`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`model`	`string`	否	`—`	皮膚模型：經典或苗條。
`search`	`string`	否	`—`	自由文字查詢。
`tag`	`string`	否	`—`	按標籤過濾。
`owner`	`string`	否	`—`	所有者用戶名過濾器。

回應範例

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}

皮膚細節

完整的皮膚元資料加上觀看者的喜歡/最喜歡的狀態。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。

回應範例

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

列出斗篷

使用排序/過濾器瀏覽社群海角上傳的內容。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`24`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`search`	`string`	否	`—`	自由文字查詢。
`tag`	`string`	否	`—`	按標籤過濾。
`owner`	`string`	否	`—`	所有者用戶名過濾器。

回應範例

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}

披風詳情

完整的披風中繼資料以及檢視者的讚/收藏狀態。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。

回應範例

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,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

MCSTAT我的世界伺服器列表

REST API

API文件

將來自 mcstat.org 的即時 Minecraft 伺服器、玩家、皮膚和社群數據整合到您自己的應用程式、機器人和儀表板中。

基本網址

所有 API 請求都以此基本 URL 開頭

https://mcstat.org/api/v1

以 Markdown 檢視

供 AI、機器人與工具使用的原始 Markdown 文件

API 金鑰

管理和監控您的 API 金鑰

在儀表板中建立、輪換和查看 API 金鑰的分析。

開啟 API 金鑰儀表板

API 遊樂場

直接在瀏覽器中測試端點

機器人驗證

此測試環境無需 API 金鑰；需要人工驗證以減少濫用。

端點

GET

/api/v1/servers

查詢參數

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

請求網址

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

運行請求以查看回應

認證

所有記錄的公共 API 端點都需要 API 金鑰。在 X-API-Key 標頭中傳送您的金鑰。

請求頭

新增此標頭以進行身份驗證

X-API-Key: mcs_your_key_here

或作為查詢參數

或作為查詢參數傳遞

?api_key=mcs_your_key_here

速率限制

請求透過 API 金鑰進行身份驗證。金鑰缺失或無效傳回 HTTP 401；超出限制回傳 HTTP 429。

沒有 API 金鑰

不允許

帶有 API 金鑰

今天同樣是中等級別，具有歸因和優先隊列。付費方案將提供更高級別的服務。

速率限制標頭：每個回應都包含一個 Cache-Control 標頭，以便您可以安全地在用戶端快取結果。

回應格式

每個成功的回應都是帶有布林值和物件的 JSON。錯誤與使用相同的信封： false。

成功回應

JSON

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

錯誤回應

JSON

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

錯誤

使用標準 HTTP 狀態碼。常見案例：

程式碼	意義
`400`	錯誤的請求－無效的參數
`401`	未經授權 - API 金鑰遺失或無效
`404`	未找到 — 資源不存在
`429`	請求過多 — 超出速率限制
`500`	內部伺服器錯誤 — 稍後重試

伺服器端點

瀏覽、過濾和檢查 mcstat.org 追蹤的 Minecraft 伺服器。

GET

/api/v1/servers

列出伺服器

具有豐富過濾器的公共伺服器的分頁清單。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`20`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`search`	`string`	否	`—`	自由文字查詢。
`country`	`string`	否	`—`	ISO 國家/地區名稱過濾器。
`version`	`string`	否	`—`	我的世界版本過濾器。
`tag`	`string`	否	`—`	按標籤過濾。
`mode`	`string`	否	`—`	遊戲模式過濾器。
`minPlayers`	`integer`	否	`—`	最小當前玩家數量。
`maxPlayers`	`integer`	否	`—`	當前最大玩家數量。
`minUptime`	`number`	否	`—`	最小正常運轉時間百分比。
`minVotes`	`integer`	否	`—`	最低總票數。
`minRating`	`number`	否	`—`	最低評級 (1–5)。
`onlineOnly`	`boolean`	否	`—`	僅包括在線報告的伺服器。

回應範例

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}

伺服器詳細信息

完整的伺服器設定檔：統計歷史記錄、正常運作時間、投票圖表、排名。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`period`	`string`	否	`24h`	時間窗口：24h, 7d, 30d, 90d, all-time.

回應範例

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

伺服器投票者

給定伺服器的最近投票者（經過身份驗證的和匿名的）。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`7`	每頁的項目。

回應範例

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

伺服器評價

伺服器的分頁玩家評價與評分。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`5`	每頁的項目。

回應範例

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

伺服器動態

伺服器已核准的新聞與更新貼文。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`3`	每頁的項目。

回應範例

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

頂級伺服器

針對主頁/小部件使用進行了最佳化的趨勢清單。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`sort`	`string`	否	`votes`	排序順序。
`limit`	`integer`	否	`10`	每頁的項目。
`country`	`string`	否	`—`	ISO 國家/地區名稱過濾器。
`gameMode`	`string`	否	`—`	遊戲模式過濾器。

回應範例

JSON

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

伺服器國家

按國家/地區分組的伺服器總數。

請求範例

cURL

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

查詢參數

無參數

回應範例

JSON

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

GET

/api/v1/servers/versions

伺服器版本

按 Minecraft 版本分組的伺服器總數。

請求範例

cURL

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

查詢參數

無參數

回應範例

JSON

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

玩家端點

尋找玩家檔案、會話、等級和歷史記錄。

GET

/api/v1/players

列出球員

分頁的公開玩家目錄。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`—`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`search`	`string`	否	`—`	自由文字查詢。

回應範例

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}

球員詳情

個人資料、最近的會話、所玩的伺服器、K/D、成就。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`id`	`string`	是的	`—`	玩家 ID、UUID 或暱稱。

回應範例

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

搜尋

跨伺服器與玩家的統一搜尋。

GET

/api/v1/search

全球搜尋

一次呼叫即可搜尋伺服器與玩家。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`q`	`string`	是的	`—`	搜尋查詢（2–100 個字元）。
`type`	`string`	否	`all`	結果類型：all, servers, players.
`limit`	`integer`	否	`10`	每頁的項目。

回應範例

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

即時和全球統計數據

即時全球活動、地區和國家詳細資訊。

GET

/api/v1/live

即時統計

全球線上總數、頂級伺服器、近期活動、地區和國家細分。

請求範例

cURL

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

查詢參數

無參數

回應範例

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

活生生的歷史

過去 7 天內每小時的線上玩家總數。

請求範例

cURL

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

查詢參數

無參數

回應範例

JSON

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

排行榜

按會話、伺服器或等級積分排名的頂級玩家。

GET

/api/v1/leaderboards

排行榜

選定指標、期間、等級和成就濾鏡的頂級玩家。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`metric`	`string`	否	`best`	排名指標：best, sessions, servers.
`period`	`string`	否	`all-time`	時間窗口：24h, 7d, 30d, 90d, all-time.
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`20`	每頁的項目。
`tier`	`string`	否	`—`	層過濾器。
`achievement`	`string`	否	`—`	成就過濾器。
`search`	`string`	否	`—`	自由文字查詢。

回應範例

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

皮膚和斗篷

搜尋社群上傳的皮膚和斗篷。

GET

/api/v1/skins

列出皮膚

使用排序/過濾器瀏覽社群上傳的皮膚。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`24`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`model`	`string`	否	`—`	皮膚模型：經典或苗條。
`search`	`string`	否	`—`	自由文字查詢。
`tag`	`string`	否	`—`	按標籤過濾。
`owner`	`string`	否	`—`	所有者用戶名過濾器。

回應範例

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}

皮膚細節

完整的皮膚元資料加上觀看者的喜歡/最喜歡的狀態。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。

回應範例

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

列出斗篷

使用排序/過濾器瀏覽社群海角上傳的內容。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`page`	`integer`	否	`1`	頁碼，從 1 開始。
`limit`	`integer`	否	`24`	每頁的項目。
`sort`	`string`	否	`recent`	排序順序。
`search`	`string`	否	`—`	自由文字查詢。
`tag`	`string`	否	`—`	按標籤過濾。
`owner`	`string`	否	`—`	所有者用戶名過濾器。

回應範例

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}

披風詳情

完整的披風中繼資料以及檢視者的讚/收藏狀態。

請求範例

cURL

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

查詢參數

名稱	類型	必填	預設	描述
`slug`	`string`	是的	`—`	伺服器 slug（來自 /servers 清單）。

回應範例

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,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}