REST API

API-Dokumentation

Integrieren Sie Live-Minecraft-Server-, Spieler-, Skin- und Community-Daten von mcstat.org in Ihre eigenen Apps, Bots und Dashboards.

Basis-URL

Alle API-Anfragen beginnen mit dieser Basis-URL

https://mcstat.org/api/v1

Als Markdown anzeigen

Rohe Markdown-Doku für KIs, Bots und Tools

API-Schlüssel

Verwalten und überwachen Sie Ihre API-Schlüssel

Erstellen, rotieren und zeigen Sie Analysen für Ihre API-Schlüssel im Dashboard an.

Öffnen Sie das API-Schlüssel-Dashboard

API-Spielplatz

Testen Sie Endpunkte direkt im Browser

Bot-Check

Für diesen Spielplatz ist kein API-Schlüssel erforderlich. Um Missbrauch zu reduzieren, ist eine menschliche Überprüfung erforderlich.

Endpunkt

GET

/api/v1/servers

Abfrageparameter

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 anfordern

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

Führen Sie eine Anfrage aus, um die Antwort anzuzeigen

Authentifizierung

Alle dokumentierten öffentlichen API-Endpunkte erfordern einen API-Schlüssel. Senden Sie Ihren Schlüssel im X-API-Key-Header.

Anforderungsheader

Fügen Sie diesen Header zur Authentifizierung hinzu

X-API-Key: mcs_your_key_here

Oder als Abfrageparameter

Oder als Abfrageparameter übergeben

?api_key=mcs_your_key_here

Tarifbegrenzungen

Anfragen werden durch den API-Schlüssel authentifiziert. Ein fehlender oder ungültiger Schlüssel gibt HTTP 401 zurück, ein deaktivierter Schlüssel gibt HTTP 403 zurück und eine überschrittene Grenze gibt HTTP 429 zurück.

Ohne API-Schlüssel

Nicht erlaubt

Mit API-Schlüssel

Standardmäßig 60 Anfragen pro Minute, 1.000 pro Tag und 30.000 pro Monat. Beim Überschreiten eines Grenzwerts wird HTTP 429 mit X-RateLimit-*-Headern zurückgegeben, die Ihre Grenzwerte anzeigen, und ein Retry-After, das Ihnen mitteilt, wann das Fenster zurückgesetzt wird. Auf Anfrage können pro Schlüssel höhere Limits gewährt werden.

Rate-Limit-Header:Eine 429-Antwort enthält X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month und Retry-After. Erfolgreiche Antworten tragen einen Cache-Control-Header, sodass Sie Ergebnisse sicher clientseitig zwischenspeichern können.

Antwortformat

Jede erfolgreiche Antwort ist JSON mit einem booleschen Wert und einem Objekt . Fehler verwenden denselben Umschlag mit : false.

Erfolgsantwort

JSON

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

Fehlerreaktion

JSON

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

Fehler

Es werden Standard-HTTP-Statuscodes verwendet. Häufige Fälle:

Code	Bedeutung
`400`	Ungültige Anfrage – ungültige Parameter
`401`	Nicht autorisiert – fehlender oder ungültiger API-Schlüssel
`403`	Verboten – API-Schlüssel deaktiviert
`404`	Nicht gefunden – Ressource existiert nicht
`429`	Zu viele Anfragen – Ratenlimit überschritten
`500`	Interner Serverfehler – versuchen Sie es später erneut

Serverendpunkte

Durchsuchen, filtern und inspizieren Sie die von mcstat.org verfolgten Minecraft-Server.

GET

/api/v1/servers

Server auflisten

Paginierte Liste öffentlicher Server mit umfangreichen Filtern.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`20`	Artikel pro Seite.
`sort`	`string`	Nein	`recent`	Sortierreihenfolge.
`search`	`string`	Nein	`—`	Freitextabfrage.
`country`	`string`	Nein	`—`	ISO-Ländernamenfilter.
`version`	`string`	Nein	`—`	Minecraft-Versionsfilter.
`tag`	`string`	Nein	`—`	Nach Tag filtern.
`mode`	`string`	Nein	`—`	Spielmodusfilter.
`minPlayers`	`integer`	Nein	`—`	Mindestanzahl aktueller Spieler.
`maxPlayers`	`integer`	Nein	`—`	Maximale aktuelle Spieleranzahl.
`minUptime`	`number`	Nein	`—`	Mindestverfügbarkeitsprozentsatz.
`minVotes`	`integer`	Nein	`—`	Mindestgesamtzahl der Stimmen.
`minRating`	`number`	Nein	`—`	Mindestbewertung (1–5).
`onlineOnly`	`boolean`	Nein	`—`	Berücksichtigen Sie nur Server, die online Bericht erstatten.

Beispielantwort

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}

Serverdetails

Vollständiges Serverprofil: Statistikverlauf, Betriebszeit, Abstimmungstabelle, Ränge.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`slug`	`string`	Ja	`—`	Server-Slug (aus der /servers-Liste).
`period`	`string`	Nein	`24h`	Zeitfenster: 24h, 7d, 30d, 90d, all-time.

Beispielantwort

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

Serverwähler

Aktuelle Wähler (authentifiziert und anonym) für den angegebenen Server.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`slug`	`string`	Ja	`—`	Server-Slug (aus der /servers-Liste).
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`7`	Artikel pro Seite.

Beispielantwort

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

Server-Bewertungen

Paginierte Spielerbewertungen und Wertungen für einen Server.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`slug`	`string`	Ja	`—`	Server-Slug (aus der /servers-Liste).
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`5`	Artikel pro Seite.

Beispielantwort

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

Freigegebene News- und Update-Beiträge für einen Server.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`slug`	`string`	Ja	`—`	Server-Slug (aus der /servers-Liste).
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`3`	Artikel pro Seite.

Beispielantwort

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

Top-Server

Trendliste, optimiert für die Verwendung auf Homepages/Widgets.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`sort`	`string`	Nein	`votes`	Sortierreihenfolge.
`limit`	`integer`	Nein	`10`	Artikel pro Seite.
`country`	`string`	Nein	`—`	ISO-Ländernamenfilter.
`gameMode`	`string`	Nein	`—`	Spielmodusfilter.

Beispielantwort

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

Serverländer

Gesamtanzahl der Server, gruppiert nach Land.

Beispielanfrage

cURL

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

Abfrageparameter

Keine Parameter

Beispielantwort

JSON

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

GET

/api/v1/servers/versions

Serverversionen

Gesamtanzahl der Server, gruppiert nach Minecraft-Version.

Beispielanfrage

cURL

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

Abfrageparameter

Keine Parameter

Beispielantwort

JSON

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

Spielerendpunkte

Suchen Sie nach Spielerprofilen, Sitzungen, Stufen und Verlauf.

GET

/api/v1/players

Spieler auflisten

Paginiertes öffentliches Player-Verzeichnis.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`—`	Artikel pro Seite.
`sort`	`string`	Nein	`recent`	Sortierreihenfolge.
`search`	`string`	Nein	`—`	Freitextabfrage.

Beispielantwort

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}

Spielerdetails

Profil, letzte Sitzungen, gespielte Server, K/D, Erfolge.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`id`	`string`	Ja	`—`	Spieler-ID, UUID oder Spitzname.

Beispielantwort

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

Suchen

Einheitliche Suche über Server und Spieler hinweg.

GET

/api/v1/search

Globale Suche

Durchsuchen Sie Server und Spieler in einem Aufruf.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`q`	`string`	Ja	`—`	Suchanfrage (2–100 Zeichen).
`type`	`string`	Nein	`all`	Ergebnistyp: all, servers, players.
`limit`	`integer`	Nein	`10`	Artikel pro Seite.

Beispielantwort

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- und globale Statistiken

Globale Aktivität in Echtzeit sowie Aufschlüsselung nach Regionen und Ländern.

GET

/api/v1/live

Live-Statistiken

Globale Online-Gesamtzahlen, Top-Server, aktuelle Aktivitäten, Aufschlüsselung nach Regionen und Ländern.

Beispielanfrage

cURL

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

Abfrageparameter

Keine Parameter

Beispielantwort

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

Live-Geschichte

Stündliche Buckets der gesamten Online-Spieler in den letzten 7 Tagen.

Beispielanfrage

cURL

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

Abfrageparameter

Keine Parameter

Beispielantwort

JSON

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

Bestenlisten

Top-Spieler sortiert nach Sitzungen, Servern oder Stufenpunkten.

GET

/api/v1/leaderboards

Bestenlisten

Top-Spieler für die ausgewählten Filter für Metrik, Zeitraum, Stufe und Erfolg.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`metric`	`string`	Nein	`best`	Ranking-Metrik: best, sessions, servers.
`period`	`string`	Nein	`all-time`	Zeitfenster: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`20`	Artikel pro Seite.
`tier`	`string`	Nein	`—`	Stufenfilter.
`achievement`	`string`	Nein	`—`	Leistungsfilter.
`search`	`string`	Nein	`—`	Freitextabfrage.

Beispielantwort

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

Felle und Umhänge

Durchsuchen Sie von der Community hochgeladene Skins und Umhänge.

GET

/api/v1/skins

Skins auflisten

Durchsuchen Sie Community-Skin-Uploads mit Sortierung/Filter.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`24`	Artikel pro Seite.
`sort`	`string`	Nein	`recent`	Sortierreihenfolge.
`model`	`string`	Nein	`—`	Hautmodell: klassisch oder schlank.
`search`	`string`	Nein	`—`	Freitextabfrage.
`tag`	`string`	Nein	`—`	Nach Tag filtern.
`owner`	`string`	Nein	`—`	Benutzernamenfilter des Besitzers.

Beispielantwort

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}

Hautdetail

Vollständige Skin-Metadaten sowie der Status „Gefällt mir“/Favorit des Betrachters.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`slug`	`string`	Ja	`—`	Server-Slug (aus der /servers-Liste).

Beispielantwort

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

Umhänge auflisten

Durchsuchen Sie Community-Cape-Uploads mit Sortierung/Filter.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`page`	`integer`	Nein	`1`	Seitenzahl, beginnend bei 1.
`limit`	`integer`	Nein	`24`	Artikel pro Seite.
`sort`	`string`	Nein	`recent`	Sortierreihenfolge.
`search`	`string`	Nein	`—`	Freitextabfrage.
`tag`	`string`	Nein	`—`	Nach Tag filtern.
`owner`	`string`	Nein	`—`	Benutzernamenfilter des Besitzers.

Beispielantwort

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}

Umhang-Details

Vollständige Umhang-Metadaten sowie der Gefällt-mir-/Favoriten-Status des Betrachters.

Beispielanfrage

cURL

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

Abfrageparameter

Name	Typ	erforderlich	Standard	Beschreibung
`slug`	`string`	Ja	`—`	Server-Slug (aus der /servers-Liste).

Beispielantwort

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