REST API

Documentation API

Intégrez les données en direct du serveur Minecraft, du joueur, du skin et de la communauté de mcstat.org dans vos propres applications, robots et tableaux de bord.

URL de base

Toutes les requêtes API commencent par cette URL de base

https://mcstat.org/api/v1

Voir en Markdown

Documentation Markdown brute pour IA, bots et outils

Clés API

Gérez et surveillez vos clés API

Créez, faites pivoter et affichez des analyses pour vos clés API dans le tableau de bord.

Ouvrir le tableau de bord des clés API

Terrain de jeu API

Testez les points de terminaison directement dans le navigateur

Vérification anti-bot

Ce bac à sable ne nécessite pas de clé API ; une vérification humaine est requise pour réduire les abus.

Point de terminaison

GET

/api/v1/servers

Paramètres de requête

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 de la demande

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

Exécutez une requête pour voir la réponse

Authentification

Tous les points de terminaison d'API publics documentés nécessitent une clé API. Envoyez votre clé dans l'en-tête X-API-Key.

En-tête de requête

Ajoutez cet en-tête pour vous authentifier

X-API-Key: mcs_your_key_here

Ou comme paramètre de requête

Ou passer en paramètre de requête

?api_key=mcs_your_key_here

Limites de taux

Les requêtes sont authentifiées par clé API. Une clé manquante ou non valide renvoie HTTP 401, une clé désactivée renvoie HTTP 403 et une limite dépassée renvoie HTTP 429.

Sans clé API

Non autorisé

Avec clé API

60 requêtes par minute, 1 000 par jour et 30 000 par mois par défaut. Le dépassement d'une limite renvoie HTTP 429 avec les en-têtes X-RateLimit-* indiquant vos limites et un Retry-After vous indiquant quand la fenêtre se réinitialise. Des limites plus élevées peuvent être accordées par clé sur demande.

En-têtes de limite de débit :Une réponse 429 contient X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month et Retry-After. Les réponses réussies comportent un en-tête Cache-Control afin que vous puissiez mettre en cache les résultats en toute sécurité côté client.

Format de réponse

Chaque réponse réussie est JSON avec un booléen et un objet . Les erreurs utilisent la même enveloppe avec : false.

Réponse réussie

JSON

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

Réponse à l'erreur

JSON

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

Erreurs

Des codes d'état HTTP standard sont utilisés. Cas courants :

Coder	Signification
`400`	Mauvaise demande – paramètres invalides
`401`	Non autorisé : clé API manquante ou non valide
`403`	Interdit – Clé API désactivée
`404`	Introuvable : la ressource n'existe pas
`429`	Trop de demandes : limite de débit dépassée
`500`	Erreur de serveur interne – réessayez plus tard

Points de terminaison du serveur

Parcourez, filtrez et inspectez les serveurs Minecraft suivis par mcstat.org.

GET

/api/v1/servers

Liste des serveurs

Liste paginée de serveurs publics avec des filtres riches.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`20`	Articles par page.
`sort`	`string`	Non	`recent`	Ordre de tri.
`search`	`string`	Non	`—`	Requête en texte libre.
`country`	`string`	Non	`—`	Filtre de nom de pays ISO.
`version`	`string`	Non	`—`	Filtre de version Minecraft.
`tag`	`string`	Non	`—`	Filtrer par balise.
`mode`	`string`	Non	`—`	Filtre du mode jeu.
`minPlayers`	`integer`	Non	`—`	Nombre minimum de joueurs actuels.
`maxPlayers`	`integer`	Non	`—`	Nombre maximum de joueurs actuels.
`minUptime`	`number`	Non	`—`	Pourcentage de disponibilité minimum.
`minVotes`	`integer`	Non	`—`	Nombre total minimum de votes.
`minRating`	`number`	Non	`—`	Note minimale (1 à 5).
`onlineOnly`	`boolean`	Non	`—`	Incluez uniquement les serveurs qui génèrent des rapports en ligne.

Exemple de réponse

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}

Détail du serveur

Profil de serveur complet : historique des statistiques, disponibilité, tableau des votes, classements.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`slug`	`string`	Oui	`—`	Slug du serveur (de la liste /servers).
`period`	`string`	Non	`24h`	Fenêtre horaire : 24h, 7d, 30d, 90d, all-time.

Exemple de réponse

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

Votants du serveur

Votants récents (authentifiés et anonymes) pour le serveur donné.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`slug`	`string`	Oui	`—`	Slug du serveur (de la liste /servers).
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`7`	Articles par page.

Exemple de réponse

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

Avis du serveur

Avis et notes de joueurs paginés pour un serveur.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`slug`	`string`	Oui	`—`	Slug du serveur (de la liste /servers).
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`5`	Articles par page.

Exemple de réponse

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

Actualités du serveur

Publications de nouvelles et mises à jour approuvées pour un serveur.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`slug`	`string`	Oui	`—`	Slug du serveur (de la liste /servers).
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`3`	Articles par page.

Exemple de réponse

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

Meilleurs serveurs

Liste de tendances optimisée pour l'utilisation de la page d'accueil/du widget.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`sort`	`string`	Non	`votes`	Ordre de tri.
`limit`	`integer`	Non	`10`	Articles par page.
`country`	`string`	Non	`—`	Filtre de nom de pays ISO.
`gameMode`	`string`	Non	`—`	Filtre du mode jeu.

Exemple de réponse

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

Pays du serveur

Nombre total de serveurs regroupés par pays.

Exemple de demande

cURL

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

Paramètres de requête

Aucun paramètre

Exemple de réponse

JSON

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

GET

/api/v1/servers/versions

Versions du serveur

Nombre total de serveurs regroupés par version de Minecraft.

Exemple de demande

cURL

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

Paramètres de requête

Aucun paramètre

Exemple de réponse

JSON

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

Points de terminaison du joueur

Recherchez les profils de joueurs, les sessions, les niveaux et l'historique.

GET

/api/v1/players

Liste des joueurs

Répertoire public paginé des joueurs.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`—`	Articles par page.
`sort`	`string`	Non	`recent`	Ordre de tri.
`search`	`string`	Non	`—`	Requête en texte libre.

Exemple de réponse

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}

Détails du joueur

Profil, sessions récentes, serveurs joués, K/D, réalisations.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`id`	`string`	Oui	`—`	Identifiant du joueur, UUID ou surnom.

Exemple de réponse

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

Rechercher

Recherche unifiée sur les serveurs et les joueurs.

GET

/api/v1/search

Recherche globale

Recherchez serveurs et joueurs en un seul appel.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`q`	`string`	Oui	`—`	Requête de recherche (2 à 100 caractères).
`type`	`string`	Non	`all`	Type de résultat : all, servers, players.
`limit`	`integer`	Non	`10`	Articles par page.

Exemple de réponse

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

Statistiques en direct et mondiales

Activité mondiale en temps réel, répartition par région et par pays.

GET

/api/v1/live

Statistiques en direct

Totaux mondiaux en ligne, principaux serveurs, activité récente, répartition par région et par pays.

Exemple de demande

cURL

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

Paramètres de requête

Aucun paramètre

Exemple de réponse

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

Historique en direct

Tranches horaires du nombre total de joueurs en ligne au cours des 7 derniers jours.

Exemple de demande

cURL

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

Paramètres de requête

Aucun paramètre

Exemple de réponse

JSON

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

Classements

Meilleurs joueurs classés par sessions, serveurs ou points de niveau.

GET

/api/v1/leaderboards

Classements

Meilleurs joueurs pour les filtres de métrique, de période, de niveau et de réussite sélectionnés.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`metric`	`string`	Non	`best`	Métrique de classement : best, sessions, servers.
`period`	`string`	Non	`all-time`	Fenêtre horaire : 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`20`	Articles par page.
`tier`	`string`	Non	`—`	Filtre de niveau.
`achievement`	`string`	Non	`—`	Filtre de réussite.
`search`	`string`	Non	`—`	Requête en texte libre.

Exemple de réponse

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

Peaux et Capes

Recherchez des skins et des capes téléchargés par la communauté.

GET

/api/v1/skins

Liste des skins

Parcourez les téléchargements de skins de la communauté avec tri/filtre.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`24`	Articles par page.
`sort`	`string`	Non	`recent`	Ordre de tri.
`model`	`string`	Non	`—`	Modèle de peau : classique ou slim.
`search`	`string`	Non	`—`	Requête en texte libre.
`tag`	`string`	Non	`—`	Filtrer par balise.
`owner`	`string`	Non	`—`	Filtre de nom d'utilisateur du propriétaire.

Exemple de réponse

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}

Détail de la peau

Métadonnées complètes de l'habillage ainsi que l'état J'aime/favori du spectateur.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`slug`	`string`	Oui	`—`	Slug du serveur (de la liste /servers).

Exemple de réponse

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

Liste des caps

Parcourez les téléchargements de capes communautaires avec tri/filtre.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`page`	`integer`	Non	`1`	Numéro de page, commençant à 1.
`limit`	`integer`	Non	`24`	Articles par page.
`sort`	`string`	Non	`recent`	Ordre de tri.
`search`	`string`	Non	`—`	Requête en texte libre.
`tag`	`string`	Non	`—`	Filtrer par balise.
`owner`	`string`	Non	`—`	Filtre de nom d'utilisateur du propriétaire.

Exemple de réponse

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}

Détail de la cape

Métadonnées complètes de la cape ainsi que l'état j'aime/favori du visiteur.

Exemple de demande

cURL

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

Paramètres de requête

Nom	Tapez	requis	par défaut	Descriptif
`slug`	`string`	Oui	`—`	Slug du serveur (de la liste /servers).

Exemple de réponse

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