REST API

API دستاویزات

mcstat.org سے لائیو Minecraft سرور، پلیئر، جلد اور کمیونٹی ڈیٹا کو اپنی ایپس، بوٹس اور ڈیش بورڈز میں ضم کریں۔

بنیادی URL

تمام API درخواستیں اس بنیادی URL سے شروع ہوتی ہیں۔

https://mcstat.org/api/v1

Markdown کے طور پر دیکھیں

AI، بوٹس اور ٹولز کے لیے خام Markdown دستاویزات

API کیز

اپنی API کیز کا نظم اور نگرانی کریں۔

ڈیش بورڈ میں اپنی API کلیدوں کے لیے تجزیات بنائیں، گھمائیں اور دیکھیں۔

API کلیدی ڈیش بورڈ کھولیں۔

API پلے گراؤنڈ

براؤزر میں براہ راست اختتامی پوائنٹس کی جانچ کریں۔

بوٹ جانچ

اس پلے گراؤنڈ کو API کلید کی ضرورت نہیں ہے؛ غلط استعمال کو کم کرنے کے لیے انسانی تصدیق ضروری ہے۔

اختتامی نقطہ

GET

/api/v1/servers

سوال کے پیرامیٹرز

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 کی درخواست کریں۔

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

جواب دیکھنے کے لیے ایک درخواست چلائیں۔

تصدیق

تمام دستاویزی عوامی API اختتامی پوائنٹس کو API کلید کی ضرورت ہوتی ہے۔ X-API-Key ہیڈر میں اپنی کلید بھیجیں۔

ہیڈر کی درخواست کریں۔

تصدیق کرنے کے لیے اس ہیڈر کو شامل کریں۔

X-API-Key: mcs_your_key_here

یا بطور استفسار پیرامیٹر

یا بطور استفسار پیرامیٹر پاس کریں۔

?api_key=mcs_your_key_here

شرح کی حد

درخواستوں کی توثیق API کلید سے ہوتی ہے۔ ایک غائب یا غلط کلید HTTP 401 لوٹاتی ہے، ایک غیر فعال کلید HTTP 403 لوٹاتی ہے، اور حد سے تجاوز HTTP 429 لوٹاتی ہے۔

API کلید کے بغیر

اجازت نہیں ہے۔

API کلید کے ساتھ

60 درخواستیں فی منٹ، 1,000 فی دن اور 30,000 ماہانہ بطور ڈیفالٹ۔ حد سے تجاوز کرنا X-RateLimit-* ہیڈر کے ساتھ HTTP 429 لوٹاتا ہے جو آپ کی حدود دکھاتا ہے اور ونڈو کے دوبارہ سیٹ ہونے پر آپ کو بتانے کے بعد دوبارہ کوشش کریں۔ درخواست پر فی کلید زیادہ حدیں دی جا سکتی ہیں۔

شرح کی حد کے ہیڈرز:ایک 429 جواب میں X-RateLimit-Limit-Minute، X-Rate Limit-Limit-Day، X-Rate Limit-Remaining-Day، X-Rate Limit-Limit-Month، X-Rate Limit-باقی-مہینہ اور دوبارہ کوشش کرنے کے بعد ہوتا ہے۔ کامیاب جوابات میں Cache-Control ہیڈر ہوتا ہے تاکہ آپ کلائنٹ سائیڈ کے نتائج کو محفوظ طریقے سے کیش کر سکیں۔

جوابی شکل

ہر کامیاب جواب JSON ہوتا ہے جس میں بولین اور آبجیکٹ ہوتا ہے۔ غلطیاں ایک ہی لفافے کو کے ساتھ استعمال کرتی ہیں: غلط۔

کامیابی کا جواب

JSON

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

غلطی کا جواب

JSON

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

غلطیاں

معیاری HTTP اسٹیٹس کوڈز استعمال کیے جاتے ہیں۔ عام معاملات:

کوڈ	مطلب
`400`	غلط درخواست - غلط پیرامیٹرز
`401`	غیر مجاز — غائب یا غلط API کلید
`403`	ممنوع — API کلید غیر فعال ہے۔
`404`	نہیں ملا - وسیلہ موجود نہیں ہے۔
`429`	بہت زیادہ درخواستیں — شرح کی حد سے تجاوز کر گئی۔
`500`	اندرونی سرور کی خرابی — بعد میں دوبارہ کوشش کریں۔

سرور کے اختتامی مقامات

mcstat.org کے ذریعے ٹریک کیے گئے مائن کرافٹ سرورز کو براؤز، فلٹر اور معائنہ کریں۔

GET

/api/v1/servers

سرورز کی فہرست بنائیں

بھرپور فلٹرز والے عوامی سرورز کی صفحہ بندی کی فہرست۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`20`	آئٹمز فی صفحہ۔
`sort`	`string`	نہیں	`recent`	ترتیب ترتیب دیں۔
`search`	`string`	نہیں	`-`	مفت متن کا استفسار۔
`country`	`string`	نہیں	`-`	ISO ملک کا نام فلٹر۔
`version`	`string`	نہیں	`-`	مائن کرافٹ ورژن فلٹر۔
`tag`	`string`	نہیں	`-`	ٹیگ کے لحاظ سے فلٹر کریں۔
`mode`	`string`	نہیں	`-`	گیم موڈ فلٹر۔
`minPlayers`	`integer`	نہیں	`-`	کم از کم موجودہ کھلاڑیوں کی تعداد۔
`maxPlayers`	`integer`	نہیں	`-`	موجودہ کھلاڑیوں کی زیادہ سے زیادہ تعداد۔
`minUptime`	`number`	نہیں	`-`	کم از کم اپ ٹائم فیصد۔
`minVotes`	`integer`	نہیں	`-`	کم از کم کل ووٹوں کی گنتی۔
`minRating`	`number`	نہیں	`-`	کم از کم درجہ بندی (1–5)۔
`onlineOnly`	`boolean`	نہیں	`-`	صرف آن لائن رپورٹنگ کرنے والے سرورز کو شامل کریں۔

مثال کا جواب

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}

سرور کی تفصیل

مکمل سرور پروفائل: اعدادوشمار کی تاریخ، اپ ٹائم، ووٹ چارٹ، رینک۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`slug`	`string`	جی ہاں	`-`	سرور سلگ (/ سرورز کی فہرست سے)۔
`period`	`string`	نہیں	`24h`	ٹائم ونڈو: 24h, 7d, 30d, 90d, all-time.

مثال کا جواب

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

سرور ووٹرز

دیئے گئے سرور کے لیے حالیہ ووٹرز (تصدیق شدہ اور گمنام)۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`slug`	`string`	جی ہاں	`-`	سرور سلگ (/ سرورز کی فہرست سے)۔
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`7`	آئٹمز فی صفحہ۔

مثال کا جواب

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

سرور کے جائزے

کسی سرور کے لیے صفحہ بندی شدہ کھلاڑیوں کے جائزے اور درجہ بندیاں۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`slug`	`string`	جی ہاں	`-`	سرور سلگ (/ سرورز کی فہرست سے)۔
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`5`	آئٹمز فی صفحہ۔

مثال کا جواب

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

سرور اپ ڈیٹس

کسی سرور کے لیے منظور شدہ خبریں اور اپ ڈیٹ پوسٹس۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`slug`	`string`	جی ہاں	`-`	سرور سلگ (/ سرورز کی فہرست سے)۔
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`3`	آئٹمز فی صفحہ۔

مثال کا جواب

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

ٹاپ سرورز

رجحان سازی کی فہرست ہوم پیج/ویجیٹ کے استعمال کے لیے موزوں ہے۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`sort`	`string`	نہیں	`votes`	ترتیب ترتیب دیں۔
`limit`	`integer`	نہیں	`10`	آئٹمز فی صفحہ۔
`country`	`string`	نہیں	`-`	ISO ملک کا نام فلٹر۔
`gameMode`	`string`	نہیں	`-`	گیم موڈ فلٹر۔

مثال کا جواب

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

سرور ممالک

ملک کے لحاظ سے گروپ کردہ سرورز کی مجموعی تعداد۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

کوئی پیرامیٹرز نہیں۔

مثال کا جواب

JSON

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

GET

/api/v1/servers/versions

سرور کے ورژن

Minecraft ورژن کے لحاظ سے گروپ کردہ سرورز کی مجموعی تعداد۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

کوئی پیرامیٹرز نہیں۔

مثال کا جواب

JSON

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

پلیئر اینڈ پوائنٹس

پلیئر پروفائلز، سیشنز، درجات اور تاریخ دیکھیں۔

GET

/api/v1/players

کھلاڑیوں کی فہرست بنائیں

صفحہ بندی شدہ عوامی پلیئر ڈائرکٹری۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`-`	آئٹمز فی صفحہ۔
`sort`	`string`	نہیں	`recent`	ترتیب ترتیب دیں۔
`search`	`string`	نہیں	`-`	مفت متن کا استفسار۔

مثال کا جواب

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}

پلیئر کی تفصیل

پروفائل، حالیہ سیشنز، سرورز چلائے گئے، K/D، کامیابیاں۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`id`	`string`	جی ہاں	`-`	پلیئر آئی ڈی، یو یو آئی ڈی یا عرفی نام۔

مثال کا جواب

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

تلاش کریں۔

سرورز اور کھلاڑیوں میں یکجا تلاش۔

GET

/api/v1/search

عالمی تلاش

ایک ہی کال میں سرورز اور کھلاڑی تلاش کریں۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`q`	`string`	جی ہاں	`-`	تلاش کا استفسار (2-100 حروف)۔
`type`	`string`	نہیں	`all`	نتیجہ کی قسم: all, servers, players.
`limit`	`integer`	نہیں	`10`	آئٹمز فی صفحہ۔

مثال کا جواب

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

لائیو اور عالمی اعدادوشمار

ریئل ٹائم عالمی سرگرمی، علاقہ اور ملک کی خرابی۔

GET

/api/v1/live

لائیو اعدادوشمار

عالمی آن لائن ٹوٹل، ٹاپ سرورز، حالیہ سرگرمی، علاقہ اور ملک کی خرابی۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

کوئی پیرامیٹرز نہیں۔

مثال کا جواب

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

زندہ تاریخ

پچھلے 7 دنوں میں کل آن لائن کھلاڑیوں کی فی گھنٹہ کی بالٹی۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

کوئی پیرامیٹرز نہیں۔

مثال کا جواب

JSON

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

لیڈر بورڈز

سیشنز، سرورز یا درجے کے پوائنٹس کے لحاظ سے درجہ بند ٹاپ پلیئرز۔

GET

/api/v1/leaderboards

لیڈر بورڈز

منتخب میٹرک، مدت، درجے اور کامیابی کے فلٹرز کے لیے سرفہرست کھلاڑی۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`metric`	`string`	نہیں	`best`	درجہ بندی میٹرک: best, sessions, servers.
`period`	`string`	نہیں	`all-time`	ٹائم ونڈو: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`20`	آئٹمز فی صفحہ۔
`tier`	`string`	نہیں	`-`	ٹائر فلٹر۔
`achievement`	`string`	نہیں	`-`	کامیابی کا فلٹر۔
`search`	`string`	نہیں	`-`	مفت متن کا استفسار۔

مثال کا جواب

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

کھالیں اور کیپس

کمیونٹی کی طرف سے اپ لوڈ کردہ کھالیں اور کیپس تلاش کریں۔

GET

/api/v1/skins

کھالوں کی فہرست بنائیں

برادری کی جلد کے اپ لوڈز کو ترتیب/فلٹر کے ساتھ براؤز کریں۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`24`	آئٹمز فی صفحہ۔
`sort`	`string`	نہیں	`recent`	ترتیب ترتیب دیں۔
`model`	`string`	نہیں	`-`	جلد کا ماڈل: کلاسک یا پتلا۔
`search`	`string`	نہیں	`-`	مفت متن کا استفسار۔
`tag`	`string`	نہیں	`-`	ٹیگ کے لحاظ سے فلٹر کریں۔
`owner`	`string`	نہیں	`-`	مالک کا صارف نام فلٹر۔

مثال کا جواب

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}

جلد کی تفصیل

مکمل جلد کا میٹا ڈیٹا نیز ناظرین کی پسند/پسندیدہ حالت۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`slug`	`string`	جی ہاں	`-`	سرور سلگ (/ سرورز کی فہرست سے)۔

مثال کا جواب

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

فہرست کیپس

کمیونٹی کیپ اپ لوڈز کو ترتیب/فلٹر کے ساتھ براؤز کریں۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`page`	`integer`	نہیں	`1`	صفحہ نمبر، 1 سے شروع ہوتا ہے۔
`limit`	`integer`	نہیں	`24`	آئٹمز فی صفحہ۔
`sort`	`string`	نہیں	`recent`	ترتیب ترتیب دیں۔
`search`	`string`	نہیں	`-`	مفت متن کا استفسار۔
`tag`	`string`	نہیں	`-`	ٹیگ کے لحاظ سے فلٹر کریں۔
`owner`	`string`	نہیں	`-`	مالک کا صارف نام فلٹر۔

مثال کا جواب

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}

کیپ کی تفصیل

کیپ کا مکمل میٹا ڈیٹا اور دیکھنے والے کی پسند/پسندیدہ حالت۔

مثال کی درخواست

cURL

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

سوال کے پیرامیٹرز

نام	قسم	کی ضرورت ہے	پہلے سے طے شدہ	تفصیل
`slug`	`string`	جی ہاں	`-`	سرور سلگ (/ سرورز کی فہرست سے)۔

مثال کا جواب

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