REST API

API-documentatie

Integreer live Minecraft-server-, speler-, skin- en communitygegevens van mcstat.org in uw eigen apps, bots en dashboards.

Basis-URL

Alle API-verzoeken beginnen met deze basis-URL

https://mcstat.org/api/v1

Bekijk als Markdown

Ruwe Markdown-documentatie voor AI's, bots en tools

API-sleutels

Beheer en monitor uw API-sleutels

Creëer, roteer en bekijk analyses voor uw API-sleutels in het dashboard.

Open het API-sleuteldashboard

API-speeltuin

Test eindpunten rechtstreeks in de browser

Bot-controle

Deze speeltuin vereist geen API-sleutel; menselijke verificatie is vereist om misbruik te verminderen.

Eindpunt

GET

/api/v1/servers

Queryparameters

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

Verzoek-URL

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

Voer een verzoek uit om het antwoord te zien

Authenticatie

Alle gedocumenteerde openbare API-eindpunten vereisen een API-sleutel. Stuur uw sleutel in de X-API-Key-header.

Verzoekkoptekst

Voeg deze header toe om te verifiëren

X-API-Key: mcs_your_key_here

Of als queryparameter

Of geef het door als queryparameter

?api_key=mcs_your_key_here

Tarieflimieten

Aanvragen worden geverifieerd door middel van een API-sleutel. Een ontbrekende of ongeldige sleutel retourneert HTTP 401, een uitgeschakelde sleutel retourneert HTTP 403 en een overschreden limiet retourneert HTTP 429.

Zonder API-sleutel

Niet toegestaan

Met API-sleutel

Standaard 60 verzoeken per minuut, 1.000 per dag en 30.000 per maand. Als u een limiet overschrijdt, retourneert HTTP 429 met X-RateLimit-* headers die uw limieten tonen en een Retry-After die u vertelt wanneer het venster opnieuw wordt ingesteld. Op aanvraag kunnen per sleutel hogere limieten worden toegestaan.

Kopteksten voor tarieflimieten:Een 429-reactie bevat X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month en Retry-After. Succesvolle reacties zijn voorzien van een Cache-Control-header, zodat u de resultaten veilig aan de clientzijde kunt cachen.

Antwoordformaat

Elke succesvolle reactie is JSON met een boolean en een object. Fouten gebruiken dezelfde envelop met : false.

Succes reactie

JSON

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

Foutreactie

JSON

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

Fouten

Er worden standaard HTTP-statuscodes gebruikt. Veelvoorkomende gevallen:

Codeer	Betekenis
`400`	Slecht verzoek — ongeldige parameters
`401`	Ongeautoriseerd: ontbrekende of ongeldige API-sleutel
`403`	Verboden: API-sleutel uitgeschakeld
`404`	Niet gevonden: de bron bestaat niet
`429`	Te veel verzoeken: tarieflimiet overschreden
`500`	Interne serverfout. Probeer het later opnieuw

Servereindpunten

Blader, filter en inspecteer Minecraft-servers die worden gevolgd door mcstat.org.

GET

/api/v1/servers

Lijstservers

Gepagineerde lijst met openbare servers met uitgebreide filters.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`20`	Artikelen per pagina.
`sort`	`string`	Nee	`recent`	Sorteervolgorde.
`search`	`string`	Nee	`—`	Vraag in vrije tekst.
`country`	`string`	Nee	`—`	ISO-landnaamfilter.
`version`	`string`	Nee	`—`	Minecraft-versiefilter.
`tag`	`string`	Nee	`—`	Filter op tag.
`mode`	`string`	Nee	`—`	Spelmodusfilter.
`minPlayers`	`integer`	Nee	`—`	Minimum aantal huidige spelers.
`maxPlayers`	`integer`	Nee	`—`	Maximaal aantal huidige spelers.
`minUptime`	`number`	Nee	`—`	Minimaal uptimepercentage.
`minVotes`	`integer`	Nee	`—`	Minimaal totaal aantal stemmen.
`minRating`	`number`	Nee	`—`	Minimale beoordeling (1–5).
`onlineOnly`	`boolean`	Nee	`—`	Neem alleen servers op die online rapporteren.

Voorbeeld reactie

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}

Serverdetail

Volledig serverprofiel: statistiekengeschiedenis, uptime, stemgrafiek, rangen.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`slug`	`string`	Ja	`—`	Serverslug (uit de lijst /servers).
`period`	`string`	Nee	`24h`	Tijdvenster: 24h, 7d, 30d, 90d, all-time.

Voorbeeld reactie

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

Serveer kiezers

Recente kiezers (geverifieerd en anoniem) voor de gegeven server.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`slug`	`string`	Ja	`—`	Serverslug (uit de lijst /servers).
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`7`	Artikelen per pagina.

Voorbeeld reactie

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

Serverbeoordelingen

Gepagineerde spelersbeoordelingen en waarderingen voor een server.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`slug`	`string`	Ja	`—`	Serverslug (uit de lijst /servers).
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`5`	Artikelen per pagina.

Voorbeeld reactie

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

Server-updates

Goedgekeurde nieuws- en updateberichten voor een server.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`slug`	`string`	Ja	`—`	Serverslug (uit de lijst /servers).
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`3`	Artikelen per pagina.

Voorbeeld reactie

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

Topservers

Trendinglijst geoptimaliseerd voor gebruik op de homepage/widget.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`sort`	`string`	Nee	`votes`	Sorteervolgorde.
`limit`	`integer`	Nee	`10`	Artikelen per pagina.
`country`	`string`	Nee	`—`	ISO-landnaamfilter.
`gameMode`	`string`	Nee	`—`	Spelmodusfilter.

Voorbeeld reactie

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

Serverlanden

Geaggregeerde telling van servers gegroepeerd op land.

Voorbeeld verzoek

cURL

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

Queryparameters

Geen parameters

Voorbeeld reactie

JSON

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

GET

/api/v1/servers/versions

Serverversies

Totaalaantal servers gegroepeerd op Minecraft-versie.

Voorbeeld verzoek

cURL

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

Queryparameters

Geen parameters

Voorbeeld reactie

JSON

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

Eindpunten van spelers

Zoek spelersprofielen, sessies, niveaus en geschiedenis op.

GET

/api/v1/players

Lijst spelers

Gepagineerde openbare spelersmap.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`—`	Artikelen per pagina.
`sort`	`string`	Nee	`recent`	Sorteervolgorde.
`search`	`string`	Nee	`—`	Vraag in vrije tekst.

Voorbeeld reactie

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}

Spelerdetail

Profiel, recente sessies, gespeelde servers, K/D, prestaties.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`id`	`string`	Ja	`—`	Speler-ID, UUID of bijnaam.

Voorbeeld reactie

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

Zoeken

Gecombineerd zoeken over servers en spelers.

GET

/api/v1/search

Globaal zoeken

Zoek servers en spelers in één aanroep.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`q`	`string`	Ja	`—`	Zoekopdracht (2–100 tekens).
`type`	`string`	Nee	`all`	Resultaattype: all, servers, players.
`limit`	`integer`	Nee	`10`	Artikelen per pagina.

Voorbeeld reactie

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 en wereldwijde statistieken

Realtime uitsplitsingen van wereldwijde activiteiten, regio's en landen.

GET

/api/v1/live

Live statistieken

Wereldwijde online totalen, topservers, recente activiteit, uitsplitsing naar regio en land.

Voorbeeld verzoek

cURL

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

Queryparameters

Geen parameters

Voorbeeld reactie

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

Leef geschiedenis

Uurlijkse buckets van het totale aantal online spelers gedurende de afgelopen zeven dagen.

Voorbeeld verzoek

cURL

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

Queryparameters

Geen parameters

Voorbeeld reactie

JSON

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

Ranglijsten

Topspelers gerangschikt op sessies, servers of niveaupunten.

GET

/api/v1/leaderboards

Ranglijsten

Topspelers voor de geselecteerde statistiek-, periode-, niveau- en prestatiefilters.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`metric`	`string`	Nee	`best`	Rangschikkingsstatistiek: best, sessions, servers.
`period`	`string`	Nee	`all-time`	Tijdvenster: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`20`	Artikelen per pagina.
`tier`	`string`	Nee	`—`	Niveaufilter.
`achievement`	`string`	Nee	`—`	Prestatiefilter.
`search`	`string`	Nee	`—`	Vraag in vrije tekst.

Voorbeeld reactie

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

Huiden en capes

Zoek door de community geüploade skins en capes.

GET

/api/v1/skins

Maak een lijst van skins

Blader door community-skin-uploads met sorteren/filteren.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`24`	Artikelen per pagina.
`sort`	`string`	Nee	`recent`	Sorteervolgorde.
`model`	`string`	Nee	`—`	Huidmodel: klassiek of slank.
`search`	`string`	Nee	`—`	Vraag in vrije tekst.
`tag`	`string`	Nee	`—`	Filter op tag.
`owner`	`string`	Nee	`—`	Eigenaar-gebruikersnaamfilter.

Voorbeeld reactie

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}

Huiddetail

Metagegevens over de volledige skin plus de vind-ik-leuk/favoriet-status van de kijker.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`slug`	`string`	Ja	`—`	Serverslug (uit de lijst /servers).

Voorbeeld reactie

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

Lijst capes

Blader door communitycape-uploads met sorteren/filteren.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`page`	`integer`	Nee	`1`	Paginanummer, beginnend bij 1.
`limit`	`integer`	Nee	`24`	Artikelen per pagina.
`sort`	`string`	Nee	`recent`	Sorteervolgorde.
`search`	`string`	Nee	`—`	Vraag in vrije tekst.
`tag`	`string`	Nee	`—`	Filter op tag.
`owner`	`string`	Nee	`—`	Eigenaar-gebruikersnaamfilter.

Voorbeeld reactie

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}

Cape-details

Volledige cape-metadata plus de like-/favorietstatus van de kijker.

Voorbeeld verzoek

cURL

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

Queryparameters

Naam	Typ	vereist	standaard	Beschrijving
`slug`	`string`	Ja	`—`	Serverslug (uit de lijst /servers).

Voorbeeld reactie

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