REST API

Документація API

Інтегруйте живі дані сервера Minecraft, гравця, скіни та дані спільноти з mcstat.org у власні програми, ботів і інформаційні панелі.

Базовий URL

Усі запити API починаються з цієї базової URL-адреси

https://mcstat.org/api/v1

Відкрити як Markdown

Вихідна 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

URL запиту

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 403, а перевищений ліміт повертає HTTP 429.

Без ключа API

Не допускається

З ключем API

За замовчуванням 60 запитів на хвилину, 1000 на день і 30 000 на місяць. Перевищення ліміту повертає HTTP 429 із заголовками X-RateLimit-*, що показують ваші ліміти, і Retry-After повідомляє, коли вікно скидається. Вищі обмеження можуть бути надані для кожного ключа за запитом.

Заголовки обмеження швидкості:Відповідь 429 містить X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month і Retry-After. Успішні відповіді містять заголовок Cache-Control, щоб ви могли безпечно кешувати результати на стороні клієнта.

Формат відповіді

Кожна успішна відповідь – це JSON із логічним значенням і об’єктом . Помилки використовують той самий конверт із : false.

Успішна відповідь

JSON

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

Відповідь на помилку

JSON

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

Помилки

Використовуються стандартні коди стану HTTP. Поширені випадки:

Код	Значення
`400`	Поганий запит — неправильні параметри
`401`	Неавторизований — відсутній або недійсний ключ API
`403`	Заборонено — ключ API вимкнено
`404`	Не знайдено — ресурс не існує
`429`	Забагато запитів — перевищено ліміт кількості
`500`	Внутрішня помилка сервера — спробуйте пізніше

Кінцеві точки сервера

Переглядайте, фільтруйте та перевіряйте сервери Minecraft, які відстежує mcstat.org.

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`	так	`—`	Слаг сервера (зі списку /серверів).
`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`	так	`—`	Слаг сервера (зі списку /серверів).
`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`	так	`—`	Слаг сервера (зі списку /серверів).
`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`	так	`—`	Слаг сервера (зі списку /серверів).
`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

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

Країни серверів

Сукупна кількість серверів, згрупованих за країнами.

Приклад запиту

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`	так	`—`	Слаг сервера (зі списку /серверів).

Приклад відповіді

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`	так	`—`	Слаг сервера (зі списку /серверів).

Приклад відповіді

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