REST API

Documentația API

Integrați serverul Minecraft live, jucătorul, skinul și datele comunității de pe mcstat.org în propriile aplicații, roboți și tablouri de bord.

Adresa URL de bază

Toate solicitările API încep cu această adresă URL de bază

https://mcstat.org/api/v1

Vizualizează ca Markdown

Documentație Markdown brută pentru IA, boți și instrumente

Chei API

Gestionați și monitorizați cheile API

Creați, rotiți și vizualizați analitice pentru cheile dvs. API în tabloul de bord.

Deschideți API Key Dashboard

Zonă de testare API

Testați punctele finale direct în browser

Verificare bot

Acest sandbox nu necesită o cheie API; verificarea umană este necesară pentru a reduce abuzurile.

Punct final

GET

/api/v1/servers

Parametrii de interogare

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

Solicitare URL

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

Rulați o solicitare pentru a vedea răspunsul

Autentificare

Toate punctele finale API publice documentate necesită o cheie API. Trimiteți cheia în antetul X-API-Key.

Antetul cererii

Adăugați acest antet pentru a vă autentifica

X-API-Key: mcs_your_key_here

Sau ca parametru de interogare

Sau treceți ca parametru de interogare

?api_key=mcs_your_key_here

Limitele ratelor

Solicitările sunt autentificate prin cheia API. O cheie lipsă sau nevalidă returnează HTTP 401, o cheie dezactivată returnează HTTP 403, iar o limită depășită returnează HTTP 429.

Fără cheie API

Nu este permis

Cu cheie API

60 de solicitări pe minut, 1.000 pe zi și 30.000 pe lună implicit. Depășirea unei limite returnează HTTP 429 cu antetele X-RateLimit-* care vă arată limitele și un Retry-After vă anunță când fereastra se resetează. La cerere, pot fi acordate limite mai mari pentru fiecare cheie.

Anteturi pentru limita de rată:Un răspuns 429 poartă X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month și Retry-After. Răspunsurile de succes au un antet Cache-Control, astfel încât să puteți stoca în siguranță rezultatele pe partea clientului.

Formatul de răspuns

Fiecare răspuns de succes este JSON cu un obiect boolean și un obiect . Erorile folosesc același plic cu : false.

Răspuns de succes

JSON

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

Răspuns de eroare

JSON

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

Erori

Sunt utilizate coduri standard de stare HTTP. Cazuri comune:

Cod	Înțeles
`400`	Solicitare greșită — parametri nevalidi
`401`	Neautorizat - cheie API lipsă sau nevalidă
`403`	Interzis — cheia API dezactivată
`404`	Negăsit — resursa nu există
`429`	Prea multe solicitări — limita de rată a fost depășită
`500`	Eroare internă de server — încercați din nou mai târziu

Puncte finale ale serverului

Răsfoiți, filtrați și inspectați serverele Minecraft urmărite de mcstat.org.

GET

/api/v1/servers

Listează serverele

Lista paginată de servere publice cu filtre bogate.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`20`	Articole pe pagină.
`sort`	`string`	Nu	`recent`	Ordinea de sortare.
`search`	`string`	Nu	`—`	Interogare de text liber.
`country`	`string`	Nu	`—`	Filtru ISO pentru numele țării.
`version`	`string`	Nu	`—`	Filtrul de versiune Minecraft.
`tag`	`string`	Nu	`—`	Filtrați după etichetă.
`mode`	`string`	Nu	`—`	Filtru pentru modul joc.
`minPlayers`	`integer`	Nu	`—`	Numărul minim de jucători curent.
`maxPlayers`	`integer`	Nu	`—`	Numărul maxim de jucători actual.
`minUptime`	`number`	Nu	`—`	Procentul minim de funcționare.
`minVotes`	`integer`	Nu	`—`	Număr total minim de voturi.
`minRating`	`number`	Nu	`—`	Evaluare minimă (1–5).
`onlineOnly`	`boolean`	Nu	`—`	Includeți doar serverele care raportează online.

Exemplu de răspuns

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}

Detaliu server

Profil complet al serverului: istoricul statisticilor, timpul de funcționare, graficul de vot, clasamente.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`slug`	`string`	Da	`—`	Server slug (din lista /servere).
`period`	`string`	Nu	`24h`	Fereastră de timp: 24h, 7d, 30d, 90d, all-time.

Exemplu de răspuns

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

Alegătorii serverului

Alegătorii recenti (autentificați și anonimi) pentru serverul dat.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`slug`	`string`	Da	`—`	Server slug (din lista /servere).
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`7`	Articole pe pagină.

Exemplu de răspuns

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

Recenzii server

Recenzii și evaluări ale jucătorilor paginate pentru un server.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`slug`	`string`	Da	`—`	Server slug (din lista /servere).
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`5`	Articole pe pagină.

Exemplu de răspuns

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

Noutăți server

Postări de știri și actualizări aprobate pentru un server.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`slug`	`string`	Da	`—`	Server slug (din lista /servere).
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`3`	Articole pe pagină.

Exemplu de răspuns

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

Servere de top

Lista de tendințe optimizată pentru utilizarea paginii de pornire/widget-urilor.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`sort`	`string`	Nu	`votes`	Ordinea de sortare.
`limit`	`integer`	Nu	`10`	Articole pe pagină.
`country`	`string`	Nu	`—`	Filtru ISO pentru numele țării.
`gameMode`	`string`	Nu	`—`	Filtru pentru modul joc.

Exemplu de răspuns

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

Țările serverului

Numărul agregat de servere grupate în funcție de țară.

Exemplu de cerere

cURL

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

Parametrii de interogare

Fără parametri

Exemplu de răspuns

JSON

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

GET

/api/v1/servers/versions

Versiuni de server

Numărul agregat de servere grupate după versiunea Minecraft.

Exemplu de cerere

cURL

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

Parametrii de interogare

Fără parametri

Exemplu de răspuns

JSON

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

Punctele finale ale jucătorilor

Căutați profiluri de jucători, sesiuni, niveluri și istoric.

GET

/api/v1/players

Listați jucătorii

Directorul public al jucătorilor paginat.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`—`	Articole pe pagină.
`sort`	`string`	Nu	`recent`	Ordinea de sortare.
`search`	`string`	Nu	`—`	Interogare de text liber.

Exemplu de răspuns

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}

Detaliu jucător

Profil, sesiuni recente, servere jucate, K/D, realizări.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`id`	`string`	Da	`—`	Id-ul jucătorului, UUID sau porecla.

Exemplu de răspuns

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

Caută

Căutare unificată în servere și jucători.

GET

/api/v1/search

Căutare globală

Căutați servere și jucători într-un singur apel.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`q`	`string`	Da	`—`	Interogare de căutare (2–100 de caractere).
`type`	`string`	Nu	`all`	Tip de rezultat: all, servers, players.
`limit`	`integer`	Nu	`10`	Articole pe pagină.

Exemplu de răspuns

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

Statistici live și globale

Defalcări ale activității globale, regiunilor și țării în timp real.

GET

/api/v1/live

Statistici live

Totaluri online globale, servere de top, activitate recentă, defalcare în regiune și țară.

Exemplu de cerere

cURL

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

Parametrii de interogare

Fără parametri

Exemplu de răspuns

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

Istoria vie

Găleți orare cu numărul total de jucători online din ultimele 7 zile.

Exemplu de cerere

cURL

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

Parametrii de interogare

Fără parametri

Exemplu de răspuns

JSON

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

Clasamente

Jucători de top clasați în funcție de sesiuni, servere sau puncte de nivel.

GET

/api/v1/leaderboards

Clasamente

Jucători de top pentru filtrele de valori, perioadă, nivel și realizare selectate.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`metric`	`string`	Nu	`best`	Metrica de clasare: best, sessions, servers.
`period`	`string`	Nu	`all-time`	Fereastră de timp: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`20`	Articole pe pagină.
`tier`	`string`	Nu	`—`	Filtru de nivel.
`achievement`	`string`	Nu	`—`	Filtru de realizare.
`search`	`string`	Nu	`—`	Interogare de text liber.

Exemplu de răspuns

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

Piei și pelerine

Căutați skinuri și pelerine încărcate de comunitate.

GET

/api/v1/skins

Lista skin-uri

Răsfoiți încărcările de skin din comunitate cu sortare/filtru.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`24`	Articole pe pagină.
`sort`	`string`	Nu	`recent`	Ordinea de sortare.
`model`	`string`	Nu	`—`	Model de piele: clasic sau subțire.
`search`	`string`	Nu	`—`	Interogare de text liber.
`tag`	`string`	Nu	`—`	Filtrați după etichetă.
`owner`	`string`	Nu	`—`	Filtru de nume de utilizator proprietar.

Exemplu de răspuns

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}

Detaliu de piele

Metadatele complete ale pielii plus starea de like/favorită a spectatorului.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`slug`	`string`	Da	`—`	Server slug (din lista /servere).

Exemplu de răspuns

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

Enumeră pelerine

Răsfoiți încărcările de pelerină ale comunității cu sortare/filtru.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`page`	`integer`	Nu	`1`	Numărul paginii, începând cu 1.
`limit`	`integer`	Nu	`24`	Articole pe pagină.
`sort`	`string`	Nu	`recent`	Ordinea de sortare.
`search`	`string`	Nu	`—`	Interogare de text liber.
`tag`	`string`	Nu	`—`	Filtrați după etichetă.
`owner`	`string`	Nu	`—`	Filtru de nume de utilizator proprietar.

Exemplu de răspuns

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}

Detalii pelerină

Metadate complete ale pelerinei plus starea de apreciere/favorite a vizitatorului.

Exemplu de cerere

cURL

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

Parametrii de interogare

Nume	Tip	necesar	implicit	Descriere
`slug`	`string`	Da	`—`	Server slug (din lista /servere).

Exemplu de răspuns

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