REST API

Uxwebhu lwe-API

Dibanisa iseva yeMinecraft ephilayo, umdlali, ulusu kunye nedatha yoluntu evela kwi-mcstat.org kwii-apps zakho, ii-bots kunye needeshibhodi.

Isiseko se-URL

Zonke izicelo ze-API ziqala ngesi siseko se-URL

https://mcstat.org/api/v1

Jonga njenge-Markdown

Amaxwebhu e-Markdown akrwada e-AI, ii-bhulukhwe kunye nezixhobo

Izitshixo ze-API

Lawula kwaye ujonge izitshixo zakho ze-API

Yenza, jikelezisa, kwaye ujonge uhlalutyo lwezitshixo ze-API kwideshibhodi.

Vula i-API Key Dashboard

Ibala lokudlala le-API

Iisiphelo zovavanyo ngokuthe ngqo kwisikhangeli

Uvavanyo lweBot

Le ndawo yokudlala ayifuni isitshixo seAPI; ukuqinisekiswa kwabantu kufuneka ukunciphisa ukusetyenziswa ngokungafanelekanga.

Isiphelo

GET

/api/v1/servers

Iiparamitha zoMbuzo

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

Cela i-URL

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

Yenza isicelo ukuze ubone impendulo

Uqinisekiso

Zonke iisiphelo ze-API zoluntu ezibhaliweyo zifuna isitshixo se-API. Thumela isitshixo sakho kwi-X-API-Intloko yeSitshixo.

Cela isihloko

Yongeza le header ukungqinisisa

X-API-Key: mcs_your_key_here

Okanye njengombuzo parameter

Okanye dlula njengombuzo parameter

?api_key=mcs_your_key_here

Imilinganiselo yemilinganiselo

Izicelo ziqinisekiswa ngesitshixo se-API. Isitshixo esilahlekileyo okanye esingasebenziyo sibuyisela i-HTTP 401, isitshixo esikhubazekileyo sibuyisela i-HTTP 403, kwaye umda ogqithisiweyo ubuyisela i-HTTP 429.

Ngaphandle kwesitshixo se-API

Ayivumelekanga

Ngeqhosha le-API

izicelo ezingama-60 ngomzuzu, 1,000 ngosuku kunye nama-30,000 ngenyanga ngokungasileleli. Ukugqithisa umda ubuyisela i-HTTP 429 ene-X-RateLimit-* iiheader ezibonisa imida yakho kunye neZama kwakhona-Emva kokukuxelela xa ifestile iphinda icwangcisa. Imida ephezulu inokunikwa iqhosha ngalinye xa liceliwe.

Izihloko zoMda womlinganiselo:Impendulo ye-429 ithwala i-X-RateLimit-Limit-Minute, i-X-RateLimit-Limit-Day, i-X-RateLimit-Remaing-Day, i-X-RateLimit-Limit-Month, i-X-RateLimit-eseleyo-inyanga kunye nokuzama-Emva koko. Iimpendulo eziphumeleleyo ziphethe i-Cache-Control header ukuze ukwazi ukufihla iziphumo ezikhuselekileyo kwicala lomxhasi.

Indlela yokuphendula

Yonke impendulo eyimpumelelo yi-JSON nge boolean kunye ne into. Iimpazamo zisebenzisa imvulophu enye ene-: bubuxoki.

Impendulo eyimpumelelo

JSON

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

Impendulo yemposiso

JSON

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

Iimpazamo

Iikhowudi zesimo se-HTTP ezisemgangathweni zisetyenziswa. Iimeko eziqhelekileyo:

Ikhowudi	Intsingiselo
`400`	Isicelo esibi — iiparamitha ezingasebenziyo
`401`	Ukungagunyaziswanga — iqhosha elilahlekileyo okanye elingasebenziyo le-API
`403`	Akuvumelekanga - iqhosha le-API livaliwe
`404`	Ayifunyenwanga - uvimba abukho
`429`	Izicelo ezininzi kakhulu — kugqithiwe kumda womlinganiselo
`500`	Impazamo yeseva yangaphakathi — zama kwakhona kamva

Iziphelo zeseva

Khangela, hluza kwaye ujonge iiseva zeMinecraft ezilandelwa ngu mcstat.org.

GET

/api/v1/servers

Dwelisa abancedisi

Uluhlu olunamaphepha eeseva zikawonke-wonke ezinezihluzo ezityebileyo.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`20`	Izinto ngephepha ngalinye.
`sort`	`string`	Hayi	`recent`	Hlela ulandelelwano.
`search`	`string`	Hayi	`-`	Umbuzo wombhalo wasimahla.
`country`	`string`	Hayi	`-`	Isihluzi segama lelizwe le-ISO.
`version`	`string`	Hayi	`-`	Isihluzi senguqulelo yeMinecraft.
`tag`	`string`	Hayi	`-`	Hluza ngethegi.
`mode`	`string`	Hayi	`-`	Isihluzi sendlela yomdlalo.
`minPlayers`	`integer`	Hayi	`-`	Ubuncinci ubalo lwabadlali bangoku.
`maxPlayers`	`integer`	Hayi	`-`	Elona nani liphezulu labadlali langoku.
`minUptime`	`number`	Hayi	`-`	Ubuncinci bepesenti yokuphumla.
`minVotes`	`integer`	Hayi	`-`	Ubuncinci bamanani evoti iyonke.
`minRating`	`number`	Hayi	`-`	Ubuncinci bomlinganiselo (1–5).
`onlineOnly`	`boolean`	Hayi	`-`	Bandakanya kuphela iiseva ezinika ingxelo kwi-intanethi.

Umzekelo impendulo

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}

Iinkcukacha zeseva

Iprofayile yeseva epheleleyo: imbali yezibalo, ixesha lokuphumla, itshathi yevoti, amanqanaba.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`slug`	`string`	Ewe	`-`	Umncedisi we-slug (ukusuka kuluhlu lwabancedisi).
`period`	`string`	Hayi	`24h`	Ixesha lefestile: 24h, 7d, 30d, 90d, all-time.

Umzekelo impendulo

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

Abavoti beseva

Abavoti bakutsha nje (abaqinisekisiweyo nabangaziwa) kumncedisi onikiweyo.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`slug`	`string`	Ewe	`-`	Umncedisi we-slug (ukusuka kuluhlu lwabancedisi).
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`7`	Izinto ngephepha ngalinye.

Umzekelo impendulo

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

Uphononongo lweseva

Uphononongo lwabadlali olunamaphepha kunye nezikali zeseva.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`slug`	`string`	Ewe	`-`	Umncedisi we-slug (ukusuka kuluhlu lwabancedisi).
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`5`	Izinto ngephepha ngalinye.

Umzekelo impendulo

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

Uhlaziyo lweseva

Iiposti zeendaba nolwazi eziphunyeziweyo zeseva.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`slug`	`string`	Ewe	`-`	Umncedisi we-slug (ukusuka kuluhlu lwabancedisi).
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`3`	Izinto ngephepha ngalinye.

Umzekelo impendulo

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

Abancedisi abaphezulu

Uluhlu oluhamba phambili olulungiselelwe iphepha lasekhaya/usetyenziso lwewijethi.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`sort`	`string`	Hayi	`votes`	Hlela ulandelelwano.
`limit`	`integer`	Hayi	`10`	Izinto ngephepha ngalinye.
`country`	`string`	Hayi	`-`	Isihluzi segama lelizwe le-ISO.
`gameMode`	`string`	Hayi	`-`	Isihluzi sendlela yomdlalo.

Umzekelo impendulo

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

Amazwe omncedisi

Ubalo oludityanisiweyo lweeseva ezidityaniswe ngokwelizwe.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Akukho mida

Umzekelo impendulo

JSON

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

GET

/api/v1/servers/versions

Iinguqulelo zeseva

Ubalo oludityanisiweyo lweeseva ezidityaniswe ngoguqulelo lweMinecraft.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Akukho mida

Umzekelo impendulo

JSON

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

Amanqaku okugqibela omdlali

Jonga iiprofayili zomdlali, iiseshini, amanqanaba kunye nembali.

GET

/api/v1/players

Dwelisa abadlali

Uluhlu lwamaphepha omdlali kawonke wonke.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`-`	Izinto ngephepha ngalinye.
`sort`	`string`	Hayi	`recent`	Hlela ulandelelwano.
`search`	`string`	Hayi	`-`	Umbuzo wombhalo wasimahla.

Umzekelo impendulo

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}

Iinkcukacha zomdlali

Iprofayili, iiseshini zamva nje, iiseva ezidlalwayo, i-K/D, impumelelo.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`id`	`string`	Ewe	`-`	Id yomdlali, UUID okanye isiqhulo.

Umzekelo impendulo

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

Khangela

Ukhangelo olumanyeneyo kwiiseva nabadlali.

GET

/api/v1/search

Uphendlo lwehlabathi

Khangela iiseva nabadlali kwikholi enye.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`q`	`string`	Ewe	`-`	Umbuzo wokukhangela (2–100 chars).
`type`	`string`	Hayi	`all`	Uhlobo lwesiphumo: all, servers, players.
`limit`	`integer`	Hayi	`10`	Izinto ngephepha ngalinye.

Umzekelo impendulo

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

Live & Global izibalo

Ixesha lokwenyani lomsebenzi wehlabathi, uqhekeko lwengingqi kunye nelizwe.

GET

/api/v1/live

Amanani akhoyo

Iitotali ze-intanethi zehlabathi, iiseva eziphezulu, umsebenzi wamva nje, ummandla kunye nokwahlulwa kwelizwe.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Akukho mida

Umzekelo impendulo

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

Phila imbali

Iibhakethi zeyure zabadlali be-intanethi bebonke kwiintsuku ezisi-7 ezidlulileyo.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Akukho mida

Umzekelo impendulo

JSON

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

Iibhodi zabakhokelayo

Abadlali abaphezulu babekwe ngokweeseshoni, iiseva okanye amanqaku enqanaba.

GET

/api/v1/leaderboards

Iibhodi zabakhokelayo

Abadlali abaphezulu bemetric ekhethiweyo, ixesha, inqanaba kunye nezihluzo zempumelelo.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`metric`	`string`	Hayi	`best`	Uluhlu lwemetriki: best, sessions, servers.
`period`	`string`	Hayi	`all-time`	Ixesha lefestile: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`20`	Izinto ngephepha ngalinye.
`tier`	`string`	Hayi	`-`	Isihluzi senqanaba.
`achievement`	`string`	Hayi	`-`	Isihluzi sempumelelo.
`search`	`string`	Hayi	`-`	Umbuzo wombhalo wasimahla.

Umzekelo impendulo

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

Izikhumba kunye neeKapa

Khangela izikhumba ezilayishwe ekuhlaleni kunye neekepisi.

GET

/api/v1/skins

Dwelisa izikhumba

Bhrawuza ukulayisha ulusu loluntu ngokuhlela/ukucoca.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`24`	Izinto ngephepha ngalinye.
`sort`	`string`	Hayi	`recent`	Hlela ulandelelwano.
`model`	`string`	Hayi	`-`	Imodeli yesikhumba: i-classic okanye i-slim.
`search`	`string`	Hayi	`-`	Umbuzo wombhalo wasimahla.
`tag`	`string`	Hayi	`-`	Hluza ngethegi.
`owner`	`string`	Hayi	`-`	Isihluzi somsebenzisi womnini.

Umzekelo impendulo

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}

Iinkcukacha zolusu

Imethadatha yolusu olupheleleyo kunye nemeko yombukeli efana/ethandwayo.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`slug`	`string`	Ewe	`-`	Umncedisi we-slug (ukusuka kuluhlu lwabancedisi).

Umzekelo impendulo

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

Dwelisa iikhephu

Bhrawuza ulayisho lwe-cape yoluntu ngohlobo/ukucoca.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`page`	`integer`	Hayi	`1`	Inombolo yephepha, iqala ku-1.
`limit`	`integer`	Hayi	`24`	Izinto ngephepha ngalinye.
`sort`	`string`	Hayi	`recent`	Hlela ulandelelwano.
`search`	`string`	Hayi	`-`	Umbuzo wombhalo wasimahla.
`tag`	`string`	Hayi	`-`	Hluza ngethegi.
`owner`	`string`	Hayi	`-`	Isihluzi somsebenzisi womnini.

Umzekelo impendulo

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}

Iinkcukacha zekepusi

Idatha epheleleyo yekepusi kunye nemeko ethandwayo/ekhethwayo yombukeli.

Isicelo somzekelo

cURL

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

Iiparamitha zoMbuzo

Igama	Uhlobo	efunekayo	ukungagqibeki	Inkcazo
`slug`	`string`	Ewe	`-`	Umncedisi we-slug (ukusuka kuluhlu lwabancedisi).

Umzekelo impendulo

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