REST API

Documentación API

Integre datos en vivo del servidor, jugador, skin y comunidad de Minecraft desde mcstat.org en sus propias aplicaciones, bots y paneles.

URL base

Todas las solicitudes de API comienzan con esta URL base

https://mcstat.org/api/v1

Ver como Markdown

Documentación Markdown sin procesar para IAs, bots y herramientas

Claves API

Administre y monitoree sus claves API

Cree, rote y vea análisis de sus claves API en el panel.

Abrir panel de claves API

Zona de juegos API

Pruebe los puntos finales directamente en el navegador

Verificación de bot

Este entorno de pruebas no requiere clave API; se requiere verificación humana para reducir el abuso.

Punto final

GET

/api/v1/servers

Parámetros de consulta

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

Solicitar URL

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

Ejecute una solicitud para ver la respuesta

Autenticación

Todos los puntos finales de API públicos documentados requieren una clave API. Envíe su clave en el encabezado X-API-Key.

Encabezado de solicitud

Agregue este encabezado para autenticarse

X-API-Key: mcs_your_key_here

O como parámetro de consulta

O pasar como parámetro de consulta

?api_key=mcs_your_key_here

Límites de tarifas

Las solicitudes se autentican mediante clave API. Una clave faltante o no válida devuelve HTTP 401, una clave deshabilitada devuelve HTTP 403 y un límite excedido devuelve HTTP 429.

Sin clave API

No permitido

Con clave API

60 solicitudes por minuto, 1.000 por día y 30.000 por mes por defecto. Exceder un límite devuelve HTTP 429 con encabezados X-RateLimit-* que muestran sus límites y un Retry-After que le indica cuándo se restablece la ventana. Se pueden otorgar límites más altos por clave a pedido.

Encabezados de límite de tasa:Una respuesta 429 lleva X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month y Retry-After. Las respuestas exitosas llevan un encabezado Cache-Control para que pueda almacenar en caché los resultados de forma segura en el lado del cliente.

Formato de respuesta

Cada respuesta exitosa es JSON con un objeto booleano y . Los errores utilizan el mismo sobre con : falso.

Respuesta exitosa

JSON

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

Respuesta de error

JSON

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

Errores

Se utilizan códigos de estado HTTP estándar. Casos comunes:

Código	Significado
`400`	Solicitud incorrecta: parámetros no válidos
`401`	No autorizado: clave API faltante o no válida
`403`	Prohibido: clave API deshabilitada
`404`	No encontrado: el recurso no existe
`429`	Demasiadas solicitudes: se superó el límite de tarifa
`500`	Error interno del servidor: inténtelo de nuevo más tarde

Puntos finales del servidor

Explore, filtre e inspeccione los servidores de Minecraft rastreados por mcstat.org.

GET

/api/v1/servers

Listar servidores

Lista paginada de servidores públicos con filtros enriquecidos.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`20`	Artículos por página.
`sort`	`string`	No	`recent`	Orden de clasificación.
`search`	`string`	No	`—`	Consulta de texto libre.
`country`	`string`	No	`—`	Filtro de nombre de país ISO.
`version`	`string`	No	`—`	Filtro de versión de Minecraft.
`tag`	`string`	No	`—`	Filtrar por etiqueta.
`mode`	`string`	No	`—`	Filtro de modo de juego.
`minPlayers`	`integer`	No	`—`	Recuento mínimo de jugadores actuales.
`maxPlayers`	`integer`	No	`—`	Número máximo de jugadores actuales.
`minUptime`	`number`	No	`—`	Porcentaje mínimo de tiempo de actividad.
`minVotes`	`integer`	No	`—`	Recuento total mínimo de votos.
`minRating`	`number`	No	`—`	Calificación mínima (1–5).
`onlineOnly`	`boolean`	No	`—`	Incluya únicamente los servidores que informan en línea.

Ejemplo de respuesta

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}

Detalle del servidor

Perfil completo del servidor: historial de estadísticas, tiempo de actividad, tabla de votos, rangos.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`slug`	`string`	si	`—`	Slug de servidor (de la lista /servers).
`period`	`string`	No	`24h`	Ventana de tiempo: 24h, 7d, 30d, 90d, all-time.

Ejemplo de respuesta

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

Votantes del servidor

Votantes recientes (autenticados y anónimos) para el servidor determinado.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`slug`	`string`	si	`—`	Slug de servidor (de la lista /servers).
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`7`	Artículos por página.

Ejemplo de respuesta

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

Reseñas del servidor

Reseñas y valoraciones de jugadores paginadas de un servidor.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`slug`	`string`	si	`—`	Slug de servidor (de la lista /servers).
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`5`	Artículos por página.

Ejemplo de respuesta

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

Novedades del servidor

Publicaciones de noticias y novedades aprobadas de un servidor.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`slug`	`string`	si	`—`	Slug de servidor (de la lista /servers).
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`3`	Artículos por página.

Ejemplo de respuesta

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

Servidores superiores

Lista de tendencias optimizada para uso en la página de inicio/widget.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`sort`	`string`	No	`votes`	Orden de clasificación.
`limit`	`integer`	No	`10`	Artículos por página.
`country`	`string`	No	`—`	Filtro de nombre de país ISO.
`gameMode`	`string`	No	`—`	Filtro de modo de juego.

Ejemplo de respuesta

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

Países servidores

Recuento agregado de servidores agrupados por país.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Sin parámetros

Ejemplo de respuesta

JSON

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

GET

/api/v1/servers/versions

Versiones del servidor

Recuento agregado de servidores agrupados por versión de Minecraft.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Sin parámetros

Ejemplo de respuesta

JSON

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

Puntos finales del jugador

Busque perfiles de jugadores, sesiones, niveles e historial.

GET

/api/v1/players

Listar jugadores

Directorio de jugadores público paginado.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`—`	Artículos por página.
`sort`	`string`	No	`recent`	Orden de clasificación.
`search`	`string`	No	`—`	Consulta de texto libre.

Ejemplo de respuesta

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}

Detalle del jugador

Perfil, sesiones recientes, servidores jugados, K/D, logros.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`id`	`string`	si	`—`	ID de jugador, UUID o apodo.

Ejemplo de respuesta

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

Buscar

Búsqueda unificada en servidores y jugadores.

GET

/api/v1/search

búsqueda global

Busca servidores y jugadores en una sola llamada.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`q`	`string`	si	`—`	Consulta de búsqueda (de 2 a 100 caracteres).
`type`	`string`	No	`all`	Tipo de resultado: all, servers, players.
`limit`	`integer`	No	`10`	Artículos por página.

Ejemplo de respuesta

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

Estadísticas en vivo y globales

Desgloses de actividad global, región y país en tiempo real.

GET

/api/v1/live

Estadísticas en vivo

Totales globales en línea, servidores principales, actividad reciente, desglose por región y país.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Sin parámetros

Ejemplo de respuesta

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

Historia en vivo

Grupos por hora del total de jugadores en línea durante los últimos 7 días.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Sin parámetros

Ejemplo de respuesta

JSON

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

Tablas de clasificación

Los mejores jugadores clasificados por sesiones, servidores o puntos de nivel.

GET

/api/v1/leaderboards

Tablas de clasificación

Mejores jugadores para los filtros de métricas, períodos, niveles y logros seleccionados.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`metric`	`string`	No	`best`	Métrica de ranking: best, sessions, servers.
`period`	`string`	No	`all-time`	Ventana de tiempo: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`20`	Artículos por página.
`tier`	`string`	No	`—`	Filtro de niveles.
`achievement`	`string`	No	`—`	Filtro de logros.
`search`	`string`	No	`—`	Consulta de texto libre.

Ejemplo de respuesta

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

Pieles y capas

Busque máscaras y capas cargadas por la comunidad.

GET

/api/v1/skins

Lista de máscaras

Explore las cargas de aspectos de la comunidad con clasificación/filtro.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`24`	Artículos por página.
`sort`	`string`	No	`recent`	Orden de clasificación.
`model`	`string`	No	`—`	Modelo de piel: clásica o delgada.
`search`	`string`	No	`—`	Consulta de texto libre.
`tag`	`string`	No	`—`	Filtrar por etiqueta.
`owner`	`string`	No	`—`	Filtro de nombre de usuario del propietario.

Ejemplo de respuesta

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}

Detalle de la piel

Metadatos de aspecto completo más el estado favorito/me gusta del espectador.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`slug`	`string`	si	`—`	Slug de servidor (de la lista /servers).

Ejemplo de respuesta

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

Lista de capas

Explore las cargas de capas de la comunidad con clasificación/filtro.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`page`	`integer`	No	`1`	Número de página, comenzando en 1.
`limit`	`integer`	No	`24`	Artículos por página.
`sort`	`string`	No	`recent`	Orden de clasificación.
`search`	`string`	No	`—`	Consulta de texto libre.
`tag`	`string`	No	`—`	Filtrar por etiqueta.
`owner`	`string`	No	`—`	Filtro de nombre de usuario del propietario.

Ejemplo de respuesta

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}

Detalle de capa

Metadatos completos de la capa más el estado de me gusta/favorito del usuario.

Solicitud de ejemplo

cURL

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

Parámetros de consulta

Nombre	Tipo	requerido	predeterminado	Descripción
`slug`	`string`	si	`—`	Slug de servidor (de la lista /servers).

Ejemplo de respuesta

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