# API Minecraft — Máy chủ, Người chơi & Dữ liệu | MCStat.org

Dùng API miễn phí để truy cập danh sách máy chủ Minecraft, hồ sơ người chơi, hoạt động trực tiếp, xếp hạng và dữ liệu cộng đồng cho ứng dụng và bot.

Canonical HTML: https://mcstat.org/vi/api-docs
Markdown URL: https://mcstat.org/vi/api-docs.md
Base URL: https://mcstat.org/api/v1

## Xác thực

Tất cả các điểm cuối API công khai được ghi lại đều yêu cầu khóa API. Gửi khóa của bạn trong tiêu đề X-API-Key.

- **Tiêu đề yêu cầu** — Thêm tiêu đề này để xác thực
  `X-API-Key: mcs_your_key_here`
- **Hoặc dưới dạng tham số truy vấn** — Hoặc chuyển dưới dạng tham số truy vấn
  `?api_key=mcs_your_key_here`

## Giới hạn tỷ lệ

Yêu cầu được xác thực bằng khóa API. Khóa bị thiếu hoặc không hợp lệ trả về HTTP 401, khóa bị tắt trả về HTTP 403 và vượt quá giới hạn trả về HTTP 429.

- **Không có khóa API** — Không được phép
- **Với khóa API** — Theo mặc định, 60 yêu cầu mỗi phút, 1.000 mỗi ngày và 30.000 mỗi tháng. Vượt quá giới hạn sẽ trả về HTTP 429 với tiêu đề X-RateLimit-* hiển thị giới hạn của bạn và Retry-After cho bạn biết khi nào cửa sổ đặt lại. Giới hạn cao hơn có thể được cấp cho mỗi khóa theo yêu cầu.

Tiêu đề giới hạn tỷ lệ: Phản hồi 429 mang theo X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month và Retry-After. Phản hồi thành công mang tiêu đề Kiểm soát bộ đệm để bạn có thể lưu kết quả vào bộ đệm phía máy khách một cách an toàn.

## Định dạng phản hồi

Mọi phản hồi thành công đều là JSON với một đối tượng boolean {success} và một đối tượng {data}. Lỗi sử dụng cùng một phong bì với {success}: false.

Phản hồi thành công:

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

Phản hồi lỗi:

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

## Lỗi

Mã trạng thái HTTP tiêu chuẩn được sử dụng. Các trường hợp phổ biến:

| Mã | Ý nghĩa |
| --- | --- |
| 400 | Yêu cầu không hợp lệ - tham số không hợp lệ |
| 401 | Không được phép — khóa API bị thiếu hoặc không hợp lệ |
| 403 | Bị cấm - Khóa API bị vô hiệu hóa |
| 404 | Không tìm thấy - tài nguyên không tồn tại |
| 429 | Quá nhiều yêu cầu - vượt quá giới hạn tốc độ |
| 500 | Lỗi máy chủ nội bộ - thử lại sau |

## Hãy thử nó

The browser playground proxies requests through `/api/v1/api-docs/test`, validates Cloudflare Turnstile, allows only documented GET endpoints, and applies IP-based rate limiting.

## Endpoint Catalog

### Điểm cuối máy chủ

Duyệt, lọc và kiểm tra các máy chủ Minecraft được theo dõi bởi mcstat.org.

#### GET /api/v1/servers

Title: Liệt kê máy chủ
Description: Danh sách các máy chủ công cộng được phân trang với các bộ lọc phong phú.

Parameters:
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `20`.
- `sort` (string, optional): Sắp xếp thứ tự. Default: `recent`.
- `search` (string, optional): Truy vấn văn bản tự do.
- `country` (string, optional): Bộ lọc tên quốc gia ISO.
- `version` (string, optional): Bộ lọc phiên bản Minecraft.
- `tag` (string, optional): Lọc theo thẻ.
- `mode` (string, optional): Bộ lọc chế độ trò chơi.
- `minPlayers` (integer, optional): Số lượng người chơi hiện tại tối thiểu.
- `maxPlayers` (integer, optional): Số lượng người chơi hiện tại tối đa.
- `minUptime` (number, optional): Tỷ lệ phần trăm thời gian hoạt động tối thiểu.
- `minVotes` (integer, optional): Tổng số phiếu bầu tối thiểu.
- `minRating` (number, optional): Xếp hạng tối thiểu (1–5).
- `onlineOnly` (boolean, optional): Chỉ bao gồm các máy chủ báo cáo trực tuyến.

Example response:

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

Title: Chi tiết máy chủ
Description: Hồ sơ máy chủ đầy đủ: lịch sử thống kê, thời gian hoạt động, biểu đồ bình chọn, xếp hạng.

Parameters:
- `slug` (string, required): Sên máy chủ (từ danh sách/máy chủ).
- `period` (string, optional): Cửa sổ thời gian: 24h, 7d, 30d, 90d, all-time. Default: `24h`.

Example response:

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

Title: Máy chủ cử tri
Description: Những người bỏ phiếu gần đây (được xác thực và ẩn danh) cho máy chủ nhất định.

Parameters:
- `slug` (string, required): Sên máy chủ (từ danh sách/máy chủ).
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `7`.

Example response:

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

Title: Đánh giá máy chủ
Description: Đánh giá và xếp hạng của người chơi được phân trang cho một máy chủ.

Parameters:
- `slug` (string, required): Sên máy chủ (từ danh sách/máy chủ).
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `5`.

Example response:

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

Title: Cập nhật máy chủ
Description: Bài đăng tin tức và cập nhật đã duyệt cho một máy chủ.

Parameters:
- `slug` (string, required): Sên máy chủ (từ danh sách/máy chủ).
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `3`.

Example response:

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

Title: Máy chủ hàng đầu
Description: Danh sách xu hướng được tối ưu hóa cho việc sử dụng trang chủ/widget.

Parameters:
- `sort` (string, optional): Sắp xếp thứ tự. Default: `votes`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `10`.
- `country` (string, optional): Bộ lọc tên quốc gia ISO.
- `gameMode` (string, optional): Bộ lọc chế độ trò chơi.

Example response:

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

Title: Quốc gia máy chủ
Description: Tổng số máy chủ được nhóm theo quốc gia.

Example response:

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

#### GET /api/v1/servers/versions

Title: Phiên bản máy chủ
Description: Tổng số máy chủ được nhóm theo phiên bản Minecraft.

Example response:

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

### Điểm cuối của người chơi

Tra cứu hồ sơ người chơi, phiên, cấp độ và lịch sử.

#### GET /api/v1/players

Title: Danh sách người chơi
Description: Thư mục trình phát công cộng được phân trang.

Parameters:
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang.
- `sort` (string, optional): Sắp xếp thứ tự. Default: `recent`.
- `search` (string, optional): Truy vấn văn bản tự do.

Example response:

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

Title: Chi tiết người chơi
Description: Hồ sơ, các phiên gần đây, máy chủ đã chơi, K/D, thành tích.

Parameters:
- `id` (string, required): Id người chơi, UUID hoặc biệt hiệu.

Example response:

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

### Tìm kiếm

Tìm kiếm hợp nhất trên máy chủ và người chơi.

#### GET /api/v1/search

Title: Tìm kiếm toàn cầu
Description: Tìm kiếm máy chủ và người chơi trong một lệnh gọi.

Parameters:
- `q` (string, required): Truy vấn tìm kiếm (2–100 ký tự).
- `type` (string, optional): Loại kết quả: all, servers, players. Default: `all`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `10`.

Example response:

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

### Số liệu thống kê trực tiếp và toàn cầu

Hoạt động toàn cầu theo thời gian thực, phân tích khu vực và quốc gia.

#### GET /api/v1/live

Title: Số liệu thống kê trực tiếp
Description: Tổng số trực tuyến toàn cầu, máy chủ hàng đầu, hoạt động gần đây, phân tích khu vực và quốc gia.

Example response:

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

Title: Lịch sử trực tiếp
Description: Tổng số người chơi trực tuyến hàng giờ trong 7 ngày qua.

Example response:

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

### Bảng xếp hạng

Những người chơi hàng đầu được xếp hạng theo phiên, máy chủ hoặc điểm cấp bậc.

#### GET /api/v1/leaderboards

Title: Bảng xếp hạng
Description: Những người chơi hàng đầu cho các bộ lọc chỉ số, giai đoạn, cấp độ và thành tích đã chọn.

Parameters:
- `metric` (string, optional): Số liệu xếp hạng: best, sessions, servers. Default: `best`.
- `period` (string, optional): Cửa sổ thời gian: 24h, 7d, 30d, 90d, all-time. Default: `all-time`.
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `20`.
- `tier` (string, optional): Bộ lọc cấp.
- `achievement` (string, optional): Bộ lọc thành tích
- `search` (string, optional): Truy vấn văn bản tự do.

Example response:

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

### Da & Áo choàng

Tìm kiếm giao diện và áo choàng do cộng đồng tải lên.

#### GET /api/v1/skins

Title: Danh sách giao diện
Description: Duyệt tải lên giao diện cộng đồng bằng cách sắp xếp/bộ lọc.

Parameters:
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `24`.
- `sort` (string, optional): Sắp xếp thứ tự. Default: `recent`.
- `model` (string, optional): Mẫu da: cổ điển hoặc thon gọn.
- `search` (string, optional): Truy vấn văn bản tự do.
- `tag` (string, optional): Lọc theo thẻ.
- `owner` (string, optional): Bộ lọc tên người dùng của chủ sở hữu.

Example response:

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

Title: Chi tiết da
Description: Siêu dữ liệu đầy đủ về giao diện cộng với trạng thái thích/yêu thích của người xem.

Parameters:
- `slug` (string, required): Sên máy chủ (từ danh sách/máy chủ).

Example response:

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

Title: Danh sách áo choàng
Description: Duyệt các bản tải lên của cộng đồng bằng tính năng sắp xếp/bộ lọc.

Parameters:
- `page` (integer, optional): Số trang, bắt đầu từ 1. Default: `1`.
- `limit` (integer, optional): Các mục trên mỗi trang. Default: `24`.
- `sort` (string, optional): Sắp xếp thứ tự. Default: `recent`.
- `search` (string, optional): Truy vấn văn bản tự do.
- `tag` (string, optional): Lọc theo thẻ.
- `owner` (string, optional): Bộ lọc tên người dùng của chủ sở hữu.

Example response:

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

Title: Chi tiết áo choàng
Description: Siêu dữ liệu áo choàng đầy đủ cùng trạng thái thích/yêu thích của người xem.

Parameters:
- `slug` (string, required): Sên máy chủ (từ danh sách/máy chủ).

Example response:

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