REST API

API Dokümantasyonu

mcstat.org üzerindeki canlı Minecraft sunucu, oyuncu, skin ve topluluk verilerini kendi uygulamalarınıza, botlarınıza ve panellerinize entegre edin.

Temel URL

Tüm API istekleri bu temel URL ile başlar

https://mcstat.org/api/v1

Markdown olarak görüntüle

Yapay zekâlar, botlar ve araçlar için ham Markdown dokümanı

API Anahtarları

API anahtarlarınızı yönetin ve izleyin

API anahtarlarınızı oluşturun, döndürün ve analitiklerini dashboard'da görüntüleyin.

API Key Dashboard'u Aç

API Deneme

Endpoint'leri doğrudan tarayıcıda test et

Bot Doğrulama

Bu deneme alanı API anahtarı istemez; kötüye kullanımı azaltmak için sadece doğrulama gerekir.

Uç Nokta

GET

/api/v1/servers

Query Parametreleri

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

İstek URL'si

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

Yanıtı görmek için bir istek çalıştırın

Kimlik doğrulama

Dokümante edilen tüm public API endpoint'leri API anahtarı gerektirir. Anahtarınızı X-API-Key header'ı ile gönderin.

İstek header'ı

Kimlik doğrulama için bu başlığı ekleyin

X-API-Key: mcs_your_key_here

Veya query parametresi olarak

Veya sorgu parametresi olarak iletin

?api_key=mcs_your_key_here

Hız limitleri

İstekler API anahtarı ile doğrulanır. Eksik veya geçersiz anahtar HTTP 401, devre dışı bırakılmış anahtar HTTP 403, aşılan limit ise HTTP 429 döndürür.

API anahtarı olmadan

İzin verilmez

API anahtarı ile

Varsayılan olarak dakikada 60, günde 1.000 ve ayda 30.000 istek. Limit aşıldığında HTTP 429 döner; yanıt, limitlerinizi gösteren X-RateLimit-* başlıklarını ve pencerenin ne zaman sıfırlanacağını bildiren Retry-After başlığını içerir. Talep üzerine anahtar bazında daha yüksek limitler tanımlanabilir.

Rate Limit Başlıkları: 429 yanıtı X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month ve Retry-After başlıklarını taşır. Başarılı yanıtlar, sonuçları istemci tarafında güvenle önbelleğe alabilmeniz için Cache-Control başlığı içerir.

Yanıt formatı

Her başarılı yanıt, bir boolean değeri ve bir nesnesi içeren JSON formatındadır. Hatalar aynı zarfı : false ile kullanır.

Başarılı yanıt

JSON

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

Hata yanıtı

JSON

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

Hatalar

Standart HTTP durum kodları kullanılır. Yaygın durumlar:

Kod	Anlamı
`400`	Bad request — geçersiz parametreler
`401`	Unauthorized — API anahtarı eksik veya geçersiz
`403`	Yasak — API anahtarı devre dışı
`404`	Not found — kaynak mevcut değil
`429`	Too many requests — hız limiti aşıldı
`500`	Internal server error — daha sonra tekrar deneyin

Sunucu endpoint'leri

mcstat.org tarafından takip edilen Minecraft sunucularını gözden geçirin, filtreleyin ve inceleyin.

GET

/api/v1/servers

Sunucuları listele

Zengin filtreler ile sayfalanmış public sunucu listesi.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`20`	Sayfa başına öğe sayısı.
`sort`	`string`	Hayır	`recent`	Sıralama düzeni.
`search`	`string`	Hayır	`—`	Serbest metin sorgusu.
`country`	`string`	Hayır	`—`	ISO ülke adı filtresi.
`version`	`string`	Hayır	`—`	Minecraft sürüm filtresi.
`tag`	`string`	Hayır	`—`	Etikete göre filtrele.
`mode`	`string`	Hayır	`—`	Oyun modu filtresi.
`minPlayers`	`integer`	Hayır	`—`	Mevcut minimum oyuncu sayısı.
`maxPlayers`	`integer`	Hayır	`—`	Mevcut maksimum oyuncu sayısı.
`minUptime`	`number`	Hayır	`—`	Minimum uptime yüzdesi.
`minVotes`	`integer`	Hayır	`—`	Minimum toplam oy sayısı.
`minRating`	`number`	Hayır	`—`	Minimum puan (1–5).
`onlineOnly`	`boolean`	Hayır	`—`	Sadece online raporlayan sunucuları dahil et.

Örnek yanıt

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}

Sunucu detayı

Tam sunucu profili: istatistik geçmişi, uptime, oy grafiği, sıralamalar.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`slug`	`string`	Evet	`—`	Sunucu slug'ı (/servers listesinden).
`period`	`string`	Hayır	`24h`	Zaman aralığı: 24h, 7d, 30d, 90d, all-time.

Örnek yanıt

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

Sunucu oyverenler

Belirtilen sunucu için son oy verenler (kimlik doğrulamalı ve anonim).

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`slug`	`string`	Evet	`—`	Sunucu slug'ı (/servers listesinden).
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`7`	Sayfa başına öğe sayısı.

Örnek yanıt

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

Sunucu yorumları

Bir sunucu için sayfalanmış oyuncu yorumları ve puanları.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`slug`	`string`	Evet	`—`	Sunucu slug'ı (/servers listesinden).
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`5`	Sayfa başına öğe sayısı.

Örnek yanıt

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

Sunucu güncellemeleri

Bir sunucu için onaylanmış haber ve güncelleme gönderileri.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`slug`	`string`	Evet	`—`	Sunucu slug'ı (/servers listesinden).
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`3`	Sayfa başına öğe sayısı.

Örnek yanıt

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

En iyi sunucular

Ana sayfa/widget kullanımı için optimize edilmiş trend listesi.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`sort`	`string`	Hayır	`votes`	Sıralama düzeni.
`limit`	`integer`	Hayır	`10`	Sayfa başına öğe sayısı.
`country`	`string`	Hayır	`—`	ISO ülke adı filtresi.
`gameMode`	`string`	Hayır	`—`	Oyun modu filtresi.

Örnek yanıt

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

Sunucu ülkeleri

Ülkeye göre gruplanmış sunucu sayıları.

Örnek istek

cURL

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

Query Parametreleri

Parametre yok

Örnek yanıt

JSON

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

GET

/api/v1/servers/versions

Sunucu sürümleri

Minecraft sürümüne göre gruplanmış sunucu sayıları.

Örnek istek

cURL

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

Query Parametreleri

Parametre yok

Örnek yanıt

JSON

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

Oyuncu endpoint'leri

Oyuncu profillerini, oturumları, kademeleri ve geçmişi sorgulayın.

GET

/api/v1/players

Oyuncuları listele

Sayfalanmış public oyuncu dizini.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`—`	Sayfa başına öğe sayısı.
`sort`	`string`	Hayır	`recent`	Sıralama düzeni.
`search`	`string`	Hayır	`—`	Serbest metin sorgusu.

Örnek yanıt

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}

Oyuncu detayı

Profil, son oturumlar, oynanan sunucular, K/D, başarımlar.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`id`	`string`	Evet	`—`	Oyuncu id, UUID veya takma ad.

Örnek yanıt

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

Arama

Sunucular ve oyuncularda birleşik arama.

GET

/api/v1/search

Genel arama

Tek çağrıda sunucu ve oyuncu arayın.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`q`	`string`	Evet	`—`	Arama sorgusu (2–100 karakter).
`type`	`string`	Hayır	`all`	Sonuç türü: all, servers, players.
`limit`	`integer`	Hayır	`10`	Sayfa başına öğe sayısı.

Örnek yanıt

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

Canlı ve Küresel istatistikler

Gerçek zamanlı küresel aktivite, bölge ve ülke dağılımları.

GET

/api/v1/live

Canlı istatistikler

Küresel online toplamları, en iyi sunucular, son aktiviteler, bölge ve ülke dağılımı.

Örnek istek

cURL

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

Query Parametreleri

Parametre yok

Örnek yanıt

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

Canlı geçmiş

Son 7 gündeki toplam online oyuncuların saatlik dökümü.

Örnek istek

cURL

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

Query Parametreleri

Parametre yok

Örnek yanıt

JSON

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

Liderlik tabloları

Oturum, sunucu veya kademe puanına göre sıralanan en iyi oyuncular.

GET

/api/v1/leaderboards

Liderlik tabloları

Seçilen metrik, dönem, kademe ve başarım filtrelerine göre en iyi oyuncular.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`metric`	`string`	Hayır	`best`	Sıralama metriği: best, sessions, servers.
`period`	`string`	Hayır	`all-time`	Zaman aralığı: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`20`	Sayfa başına öğe sayısı.
`tier`	`string`	Hayır	`—`	Kademe filtresi.
`achievement`	`string`	Hayır	`—`	Başarım filtresi.
`search`	`string`	Hayır	`—`	Serbest metin sorgusu.

Örnek yanıt

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

Skinler ve Pelerinler

Topluluk tarafından yüklenen skinleri ve pelerinleri arayın.

GET

/api/v1/skins

Skinleri listele

Topluluk skin yüklemelerini sıralama/filtre ile gözden geçirin.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`24`	Sayfa başına öğe sayısı.
`sort`	`string`	Hayır	`recent`	Sıralama düzeni.
`model`	`string`	Hayır	`—`	Skin modeli: classic veya slim.
`search`	`string`	Hayır	`—`	Serbest metin sorgusu.
`tag`	`string`	Hayır	`—`	Etikete göre filtrele.
`owner`	`string`	Hayır	`—`	Sahip kullanıcı adı filtresi.

Örnek yanıt

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}

Skin detayı

Tam skin meta verisi ve görüntüleyenin beğeni/favori durumu.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`slug`	`string`	Evet	`—`	Sunucu slug'ı (/servers listesinden).

Örnek yanıt

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

Pelerinleri listele

Topluluk pelerin yüklemelerini sıralama/filtre ile gözden geçirin.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`page`	`integer`	Hayır	`1`	Sayfa numarası, 1'den başlar.
`limit`	`integer`	Hayır	`24`	Sayfa başına öğe sayısı.
`sort`	`string`	Hayır	`recent`	Sıralama düzeni.
`search`	`string`	Hayır	`—`	Serbest metin sorgusu.
`tag`	`string`	Hayır	`—`	Etikete göre filtrele.
`owner`	`string`	Hayır	`—`	Sahip kullanıcı adı filtresi.

Örnek yanıt

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}

Pelerin detayı

Tam pelerin meta verisi ve görüntüleyenin beğeni/favori durumu.

Örnek istek

cURL

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

Query Parametreleri

Ad	Tür	zorunlu	varsayılan	Açıklama
`slug`	`string`	Evet	`—`	Sunucu slug'ı (/servers listesinden).

Örnek yanıt

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