# Minecraft API — சர்வர்கள், வீரர்கள் & சமூக தரவு | MCStat.org

ஆப்ஸ் மற்றும் பாட்களுக்கு Minecraft சர்வர் லிஸ்டிங், வீரர் சுயவிவரங்கள், லைவ் செயல்பாடு, ரேங்கிங் மற்றும் சமூக தரவை இலவச API மூலம் அணுகுங்கள்.

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

## அங்கீகாரம்

அனைத்து ஆவணப்படுத்தப்பட்ட பொது API இறுதிப்புள்ளிகளுக்கும் API விசை தேவைப்படுகிறது. உங்கள் விசையை X-API-Key தலைப்பில் அனுப்பவும்.

- **கோரிக்கை தலைப்பு** — அங்கீகரிக்க இந்தத் தலைப்பைச் சேர்க்கவும்
  `X-API-Key: mcs_your_key_here`
- **அல்லது வினவல் அளவுருவாக** — அல்லது வினவல் அளவுருவாக அனுப்பவும்
  `?api_key=mcs_your_key_here`

## விகித வரம்புகள்

கோரிக்கைகள் API விசையால் அங்கீகரிக்கப்படுகின்றன. விடுபட்ட அல்லது செல்லாத விசை HTTP 401ஐ வழங்கும், முடக்கப்பட்ட விசை HTTP 403ஐ வழங்கும், மேலும் வரம்பு மீறினால் HTTP 429ஐ வழங்கும்.

- **API விசை இல்லாமல்** — அனுமதிக்கப்படவில்லை
- **API விசையுடன்** — ஒரு நிமிடத்திற்கு 60 கோரிக்கைகள், ஒரு நாளைக்கு 1,000 மற்றும் மாதத்திற்கு 30,000 இயல்புநிலையாக. வரம்பை மீறினால், உங்கள் வரம்புகளைக் காட்டும் X-RateLimit-* தலைப்புகளுடன் HTTP 429 கிடைக்கும் மற்றும் சாளரத்தை மீட்டமைக்கும் போது மீண்டும் முயற்சிக்கவும். கோரிக்கையின் பேரில் ஒரு விசைக்கு அதிக வரம்புகள் வழங்கப்படலாம்.

விகித வரம்பு தலைப்புகள்: 429 பதில் X-RateLimit-Limit-minute, X-RateLimit-limit-Day, X-RateLimit-மீதமுள்ள-நாள், X-RateLimit-Limit-Month, X-RateLimit-மீதமுள்ள-மாதம் மற்றும் மறுமுயற்சி-பிறகு ஆகியவற்றைக் கொண்டுள்ளது. வெற்றிகரமான பதில்கள் கேச்-கண்ட்ரோல் ஹெடரைக் கொண்டிருக்கும், எனவே நீங்கள் கிளையன்ட் பக்கமாக முடிவுகளைப் பாதுகாப்பாகத் தேக்கிக்கொள்ளலாம்.

## பதில் வடிவம்

ஒவ்வொரு வெற்றிகரமான பதிலும் ஒரு {success} boolean மற்றும் {data} பொருளுடன் JSON ஆகும். பிழைகள் {success} உடன் அதே உறையைப் பயன்படுத்துகின்றன: தவறு.

வெற்றி பதில்:

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

பிழை பதில்:

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

## பிழைகள்

நிலையான HTTP நிலைக் குறியீடுகள் பயன்படுத்தப்படுகின்றன. பொதுவான வழக்குகள்:

| குறியீடு | பொருள் |
| --- | --- |
| 400 | தவறான கோரிக்கை - தவறான அளவுருக்கள் |
| 401 | அங்கீகரிக்கப்படாத — காணவில்லை அல்லது தவறான API விசை |
| 403 | தடைசெய்யப்பட்டது - API விசை முடக்கப்பட்டது |
| 404 | கிடைக்கவில்லை - வளம் இல்லை |
| 429 | பல கோரிக்கைகள் - கட்டண வரம்பை மீறியது |
| 500 | உள் சேவையகப் பிழை — பிறகு முயற்சிக்கவும் |

## முயற்சிக்கவும்

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

### சேவையக இறுதிப்புள்ளிகள்

mcstat.org மூலம் கண்காணிக்கப்படும் Minecraft சேவையகங்களை உலாவவும், வடிகட்டவும் மற்றும் ஆய்வு செய்யவும்.

#### GET /api/v1/servers

Title: பட்டியல் சேவையகங்கள்
Description: பணக்கார வடிப்பான்களைக் கொண்ட பொது சேவையகங்களின் பக்கப் பட்டியல்.

Parameters:
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். Default: `20`.
- `sort` (string, optional): வரிசை வரிசை. Default: `recent`.
- `search` (string, optional): இலவச உரை வினவல்.
- `country` (string, optional): ISO நாட்டின் பெயர் வடிகட்டி.
- `version` (string, optional): Minecraft பதிப்பு வடிகட்டி.
- `tag` (string, optional): குறிச்சொல் மூலம் வடிகட்டவும்.
- `mode` (string, optional): விளையாட்டு முறை வடிகட்டி.
- `minPlayers` (integer, optional): குறைந்தபட்ச தற்போதைய வீரர் எண்ணிக்கை.
- `maxPlayers` (integer, optional): அதிகபட்ச தற்போதைய வீரர் எண்ணிக்கை.
- `minUptime` (number, optional): குறைந்தபட்ச இயக்க நேர சதவீதம்.
- `minVotes` (integer, optional): குறைந்தபட்ச மொத்த வாக்கு எண்ணிக்கை.
- `minRating` (number, optional): குறைந்தபட்ச மதிப்பீடு (1–5).
- `onlineOnly` (boolean, optional): ஆன்லைனில் அறிக்கையிடும் சேவையகங்களை மட்டும் சேர்க்கவும்.

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: சேவையக விவரம்
Description: முழு சர்வர் சுயவிவரம்: புள்ளிவிவர வரலாறு, இயக்க நேரம், வாக்கு விளக்கப்படம், தரவரிசைகள்.

Parameters:
- `slug` (string, required): சர்வர் ஸ்லக் (/சேவையக பட்டியலிலிருந்து).
- `period` (string, optional): நேர சாளரம்: 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: சர்வர் வாக்காளர்கள்
Description: கொடுக்கப்பட்ட சேவையகத்திற்கான சமீபத்திய வாக்காளர்கள் (அங்கீகரிக்கப்பட்ட மற்றும் அநாமதேய).

Parameters:
- `slug` (string, required): சர்வர் ஸ்லக் (/சேவையக பட்டியலிலிருந்து).
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். 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: சர்வர் மதிப்புரைகள்
Description: ஒரு சர்வருக்கான பக்கமிடப்பட்ட வீரர் மதிப்புரைகள் மற்றும் மதிப்பீடுகள்.

Parameters:
- `slug` (string, required): சர்வர் ஸ்லக் (/சேவையக பட்டியலிலிருந்து).
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். 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: சர்வர் புதுப்பிப்புகள்
Description: ஒரு சர்வருக்கான அங்கீகரிக்கப்பட்ட செய்தி மற்றும் புதுப்பிப்பு இடுகைகள்.

Parameters:
- `slug` (string, required): சர்வர் ஸ்லக் (/சேவையக பட்டியலிலிருந்து).
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். 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: சிறந்த சேவையகங்கள்
Description: முகப்புப் பக்கம்/விட்ஜெட் பயன்பாட்டிற்கு உகந்ததாக இருக்கும் பிரபலமான பட்டியல்.

Parameters:
- `sort` (string, optional): வரிசை வரிசை. Default: `votes`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். Default: `10`.
- `country` (string, optional): ISO நாட்டின் பெயர் வடிகட்டி.
- `gameMode` (string, optional): விளையாட்டு முறை வடிகட்டி.

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: சேவையக நாடுகள்
Description: நாடு வாரியாக குழுவாக்கப்பட்ட சேவையகங்களின் மொத்த எண்ணிக்கை.

Example response:

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

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

Title: சேவையக பதிப்புகள்
Description: Minecraft பதிப்பின் மூலம் குழுவாக்கப்பட்ட சேவையகங்களின் மொத்த எண்ணிக்கை.

Example response:

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

### வீரர் இறுதிப்புள்ளிகள்

பிளேயர் சுயவிவரங்கள், அமர்வுகள், அடுக்குகள் மற்றும் வரலாற்றைப் பார்க்கவும்.

#### GET /api/v1/players

Title: பட்டியல் வீரர்கள்
Description: பேஜினேட் செய்யப்பட்ட பொது பிளேயர் கோப்பகம்.

Parameters:
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள்.
- `sort` (string, optional): வரிசை வரிசை. Default: `recent`.
- `search` (string, optional): இலவச உரை வினவல்.

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: வீரர் விவரம்
Description: சுயவிவரம், சமீபத்திய அமர்வுகள், இயக்கப்பட்ட சேவையகங்கள், K/D, சாதனைகள்.

Parameters:
- `id` (string, required): பிளேயர் ஐடி, UUID அல்லது புனைப்பெயர்.

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

### தேடு

சர்வர்கள் மற்றும் வீரர்கள் முழுவதும் ஒருங்கிணைந்த தேடல்.

#### GET /api/v1/search

Title: உலகளாவிய தேடல்
Description: ஒரே அழைப்பில் சர்வர்கள் மற்றும் வீரர்களைத் தேடுங்கள்.

Parameters:
- `q` (string, required): தேடல் வினவல் (2–100 எழுத்துகள்).
- `type` (string, optional): முடிவு வகை: all, servers, players. Default: `all`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். 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"
  }
}
```

### நேரடி & உலகளாவிய புள்ளிவிவரங்கள்

நிகழ்நேர உலகளாவிய செயல்பாடு, பிராந்தியம் மற்றும் நாடு முறிவுகள்.

#### GET /api/v1/live

Title: நேரடி புள்ளிவிவரங்கள்
Description: உலகளாவிய ஆன்லைன் மொத்தங்கள், சிறந்த சேவையகங்கள், சமீபத்திய செயல்பாடு, பிராந்தியம் மற்றும் நாடு முறிவு.

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: நேரடி வரலாறு
Description: கடந்த 7 நாட்களில் மொத்த ஆன்லைன் பிளேயர்களின் மணிநேர பக்கெட்டுகள்.

Example response:

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

### லீடர்போர்டுகள்

அமர்வுகள், சர்வர்கள் அல்லது அடுக்கு புள்ளிகள் மூலம் தரவரிசைப்படுத்தப்பட்ட சிறந்த வீரர்கள்.

#### GET /api/v1/leaderboards

Title: லீடர்போர்டுகள்
Description: தேர்ந்தெடுக்கப்பட்ட மெட்ரிக், காலம், அடுக்கு மற்றும் சாதனை வடிப்பான்களுக்கான சிறந்த வீரர்கள்.

Parameters:
- `metric` (string, optional): தரவரிசை மெட்ரிக்: best, sessions, servers. Default: `best`.
- `period` (string, optional): நேர சாளரம்: 24h, 7d, 30d, 90d, all-time. Default: `all-time`.
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். Default: `20`.
- `tier` (string, optional): அடுக்கு வடிகட்டி.
- `achievement` (string, optional): சாதனை வடிகட்டி.
- `search` (string, optional): இலவச உரை வினவல்.

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

### தோல்கள் & கேப்ஸ்

சமூகம் பதிவேற்றிய தோல்கள் மற்றும் தொப்பிகளைத் தேடுங்கள்.

#### GET /api/v1/skins

Title: தோல்களை பட்டியலிடுங்கள்
Description: சமூக தோல் பதிவேற்றங்களை வரிசைப்படுத்துதல்/வடிகட்டுதல் மூலம் உலாவவும்.

Parameters:
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். Default: `24`.
- `sort` (string, optional): வரிசை வரிசை. Default: `recent`.
- `model` (string, optional): தோல் மாதிரி: கிளாசிக் அல்லது மெலிதான.
- `search` (string, optional): இலவச உரை வினவல்.
- `tag` (string, optional): குறிச்சொல் மூலம் வடிகட்டவும்.
- `owner` (string, optional): உரிமையாளர் பயனர்பெயர் வடிகட்டி.

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: தோல் விவரம்
Description: முழு தோல் மெட்டாடேட்டா மற்றும் பார்வையாளரின் விருப்பம்/பிடித்த நிலை.

Parameters:
- `slug` (string, required): சர்வர் ஸ்லக் (/சேவையக பட்டியலிலிருந்து).

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: பட்டியல் தொப்பிகள்
Description: சமூக கேப் பதிவேற்றங்களை வரிசைப்படுத்துதல்/வடிகட்டுதல் மூலம் உலாவவும்.

Parameters:
- `page` (integer, optional): பக்க எண், 1ல் தொடங்குகிறது. Default: `1`.
- `limit` (integer, optional): ஒரு பக்கத்திற்கு உருப்படிகள். Default: `24`.
- `sort` (string, optional): வரிசை வரிசை. Default: `recent`.
- `search` (string, optional): இலவச உரை வினவல்.
- `tag` (string, optional): குறிச்சொல் மூலம் வடிகட்டவும்.
- `owner` (string, optional): உரிமையாளர் பயனர்பெயர் வடிகட்டி.

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: கேப் விவரம்
Description: முழு கேப் மெட்டாடேட்டா மற்றும் பார்வையாளரின் விருப்பம்/பிடித்தவை நிலை.

Parameters:
- `slug` (string, required): சர்வர் ஸ்லக் (/சேவையக பட்டியலிலிருந்து).

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