REST API

Documentazione dell'API

Integra i dati live del server, del giocatore, della skin e della community di Minecraft da mcstat.org nelle tue app, bot e dashboard.

URL di base

Tutte le richieste API iniziano con questo URL di base

https://mcstat.org/api/v1

Visualizza come Markdown

Documentazione Markdown grezza per IA, bot e strumenti

Chiavi API

Gestisci e monitora le tue chiavi API

Crea, ruota e visualizza analisi per le tue chiavi API nella dashboard.

Apri la dashboard della chiave API

Parco giochi API

Testa gli endpoint direttamente nel browser

Verifica bot

Questo ambiente di test non richiede una chiave API; è richiesta la verifica umana per ridurre gli abusi.

Punto finale

GET

/api/v1/servers

Parametri della query

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

Richiedi URL

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

Esegui una richiesta per vedere la risposta

Autenticazione

Tutti gli endpoint API pubblici documentati richiedono una chiave API. Invia la tua chiave nell'intestazione X-API-Key.

Intestazione della richiesta

Aggiungi questa intestazione per autenticarti

X-API-Key: mcs_your_key_here

O come parametro di query

Oppure passa come parametro di query

?api_key=mcs_your_key_here

Limiti di tariffa

Le richieste vengono autenticate tramite chiave API. Una chiave mancante o non valida restituisce HTTP 401, una chiave disabilitata restituisce HTTP 403 e un limite superato restituisce HTTP 429.

Senza chiave API

Non consentito

Con chiave API

Per impostazione predefinita, 60 richieste al minuto, 1.000 al giorno e 30.000 al mese. Il superamento di un limite restituisce HTTP 429 con intestazioni X-RateLimit-* che mostrano i tuoi limiti e un Retry-After che ti informa quando la finestra si reimposta. Su richiesta possono essere concessi limiti più elevati per chiave.

Intestazioni del limite di velocità:Una risposta 429 trasporta X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month e Retry-After. Le risposte riuscite portano un'intestazione Cache-Control in modo da poter memorizzare nella cache i risultati in modo sicuro sul lato client.

Formato della risposta

Ogni risposta riuscita è JSON con un booleano e un oggetto . Gli errori utilizzano la stessa busta con : false.

Risposta di successo

JSON

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

Risposta all'errore

JSON

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

Errori

Vengono utilizzati codici di stato HTTP standard. Casi comuni:

Codice	Significato
`400`	Richiesta errata: parametri non validi
`401`	Non autorizzato: chiave API mancante o non valida
`403`	Vietato: chiave API disabilitata
`404`	Non trovato: la risorsa non esiste
`429`	Troppe richieste: limite di tariffa superato
`500`	Errore interno del server: riprova più tardi

Endpoint del server

Sfoglia, filtra e controlla i server Minecraft monitorati da mcstat.org.

GET

/api/v1/servers

Elenca i server

Elenco impaginato di server pubblici con filtri avanzati.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`20`	Articoli per pagina.
`sort`	`string`	No	`recent`	Ordinamento.
`search`	`string`	No	`—`	Interrogazione a testo libero.
`country`	`string`	No	`—`	Filtro nome paese ISO.
`version`	`string`	No	`—`	Filtro della versione di Minecraft.
`tag`	`string`	No	`—`	Filtra per tag.
`mode`	`string`	No	`—`	Filtro in modalità gioco.
`minPlayers`	`integer`	No	`—`	Conteggio minimo dei giocatori attuali.
`maxPlayers`	`integer`	No	`—`	Conteggio massimo dei giocatori attuali.
`minUptime`	`number`	No	`—`	Percentuale minima di uptime.
`minVotes`	`integer`	No	`—`	Conteggio totale minimo dei voti.
`minRating`	`number`	No	`—`	Valutazione minima (1–5).
`onlineOnly`	`boolean`	No	`—`	Includere solo i server che segnalano online.

Risposta di esempio

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}

Particolare del server

Profilo completo del server: cronologia delle statistiche, tempo di attività, grafico dei voti, classifiche.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`slug`	`string`	Sì	`—`	Slug del server (dall'elenco /servers).
`period`	`string`	No	`24h`	Finestra temporale: 24h, 7d, 30d, 90d, all-time.

Risposta di esempio

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

Elettori del server

Elettori recenti (autenticati e anonimi) per il server specificato.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`slug`	`string`	Sì	`—`	Slug del server (dall'elenco /servers).
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`7`	Articoli per pagina.

Risposta di esempio

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

Recensioni server

Recensioni e valutazioni dei giocatori paginate per un server.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`slug`	`string`	Sì	`—`	Slug del server (dall'elenco /servers).
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`5`	Articoli per pagina.

Risposta di esempio

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

Aggiornamenti server

Post di notizie e aggiornamenti approvati per un server.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`slug`	`string`	Sì	`—`	Slug del server (dall'elenco /servers).
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`3`	Articoli per pagina.

Risposta di esempio

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

I migliori server

Elenco dei trend ottimizzato per l'utilizzo della home page/widget.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`sort`	`string`	No	`votes`	Ordinamento.
`limit`	`integer`	No	`10`	Articoli per pagina.
`country`	`string`	No	`—`	Filtro nome paese ISO.
`gameMode`	`string`	No	`—`	Filtro in modalità gioco.

Risposta di esempio

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

Paesi server

Conteggio aggregato di server raggruppati per paese.

Richiesta di esempio

cURL

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

Parametri della query

Nessun parametro

Risposta di esempio

JSON

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

GET

/api/v1/servers/versions

Versioni del server

Conteggio aggregato di server raggruppati per versione di Minecraft.

Richiesta di esempio

cURL

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

Parametri della query

Nessun parametro

Risposta di esempio

JSON

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

Endpoint del giocatore

Cerca i profili dei giocatori, le sessioni, i livelli e la cronologia.

GET

/api/v1/players

Elenca i giocatori

Directory dei giocatori pubblici impaginati.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`—`	Articoli per pagina.
`sort`	`string`	No	`recent`	Ordinamento.
`search`	`string`	No	`—`	Interrogazione a testo libero.

Risposta di esempio

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}

Particolare del giocatore

Profilo, sessioni recenti, server giocati, K/D, risultati.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`id`	`string`	Sì	`—`	ID giocatore, UUID o nickname.

Risposta di esempio

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

Cerca

Ricerca unificata tra server e giocatori.

GET

/api/v1/search

Ricerca globale

Cerca server e giocatori in una sola chiamata.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`q`	`string`	Sì	`—`	Query di ricerca (2-100 caratteri).
`type`	`string`	No	`all`	Tipo di risultato: all, servers, players.
`limit`	`integer`	No	`10`	Articoli per pagina.

Risposta di esempio

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

Statistiche live e globali

Attività globale in tempo reale, suddivisione per regione e paese.

GET

/api/v1/live

Statistiche in tempo reale

Totali online globali, server principali, attività recente, suddivisione per regione e paese.

Richiesta di esempio

cURL

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

Parametri della query

Nessun parametro

Risposta di esempio

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

Storia dal vivo

Contenitori orari di giocatori online totali negli ultimi 7 giorni.

Richiesta di esempio

cURL

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

Parametri della query

Nessun parametro

Risposta di esempio

JSON

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

Classifiche

I migliori giocatori classificati per sessioni, server o punti livello.

GET

/api/v1/leaderboards

Classifiche

Migliori giocatori per i filtri di metrica, periodo, livello e risultati selezionati.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`metric`	`string`	No	`best`	Metrica di ranking: best, sessions, servers.
`period`	`string`	No	`all-time`	Finestra temporale: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`20`	Articoli per pagina.
`tier`	`string`	No	`—`	Filtro per livelli.
`achievement`	`string`	No	`—`	Filtro obiettivi.
`search`	`string`	No	`—`	Interrogazione a testo libero.

Risposta di esempio

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

Pelli e mantelli

Cerca skin e mantelli caricati dalla community.

GET

/api/v1/skins

Elenca le skin

Sfoglia i caricamenti di skin della community con l'ordinamento/filtro.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`24`	Articoli per pagina.
`sort`	`string`	No	`recent`	Ordinamento.
`model`	`string`	No	`—`	Modello di pelle: classico o slim.
`search`	`string`	No	`—`	Interrogazione a testo libero.
`tag`	`string`	No	`—`	Filtra per tag.
`owner`	`string`	No	`—`	Filtro nome utente proprietario.

Risposta di esempio

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}

Dettaglio della pelle

Metadati completi della skin più lo stato Mi piace/preferito dello spettatore.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`slug`	`string`	Sì	`—`	Slug del server (dall'elenco /servers).

Risposta di esempio

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

Elenca i mantelli

Sfoglia i caricamenti dei mantelli della community con l'ordinamento/filtro.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`page`	`integer`	No	`1`	Numero di pagina, a partire da 1.
`limit`	`integer`	No	`24`	Articoli per pagina.
`sort`	`string`	No	`recent`	Ordinamento.
`search`	`string`	No	`—`	Interrogazione a testo libero.
`tag`	`string`	No	`—`	Filtra per tag.
`owner`	`string`	No	`—`	Filtro nome utente proprietario.

Risposta di esempio

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}

Dettaglio mantello

Metadati completi del mantello più lo stato mi piace/preferito dello spettatore.

Richiesta di esempio

cURL

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

Parametri della query

Nome	Digitare	richiesto	predefinito	Descrizione
`slug`	`string`	Sì	`—`	Slug del server (dall'elenco /servers).

Risposta di esempio

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