API

The BetaMC RESTful API allows developers to retrieve information relating to the server and its players.

Most notably, it powers the BetaMC web statistics interface found at https://stats.betamc.org.

Endpoints

The following section documents all API endpoints which are currently part of the specification.

The base URL for all endpoints is https://api.betamc.org.

GET /api/v1/server/stats

Returns a collection of total server statistics.

Response Format

• unique_players (int) - The number of unique players that have played on the server.
• economy_size (decimal) - The total amount of money in the economy (includes banks).
• total_playtime (long) - The total playtime amassed by all players, in milliseconds.

Example Response

URL used: https://api.betamc.org/api/v1/server/stats

{
  "unique_players": 22055,
  "economy_size": 4815877.6824758479,
  "total_playtime": 487629222793
}

GET /api/v1/server/players

Returns basic information for all players currently connected to the server.

Response Format

• online (int) - The number of players currently online.
• max (int) - The maximum allowed players on the server.
• players (array) - An array containing data for all online players.
  • name (string) - The player's username.
  • uuid (string) - The player's UUID.
  • prefix (string) - The player's ingame prefix.

Example Response

URL used: https://api.betamc.org/api/v1/server/players

{
  "online": 9,
  "max": 100,
  "players": [
    {
      "name": "zavdav",
      "uuid": "142d3862-e360-419b-9ab3-421fed84f565",
      "prefix": "§8[§4Admin§8]§7"
    },
    {
      "name": "cade510",
      "uuid": "8a706dd1-8647-42a7-9124-abd3acfe7677",
      "prefix": "§b[Donator§3+§b]§7"
    },
    {
      "name": "ApplyForStaff",
      "uuid": "58fd5339-01f3-461a-a25b-904ab1d35029",
      "prefix": "§b[Donator]§7"
    },
    {
      "name": "CameraMan",
      "uuid": "c162963c-89fd-43ba-adce-c39b83f5e3f8",
      "prefix": "§b[Donator]§7"
    },
    {
      "name": "khangboy",
      "uuid": "c208b7bb-bbec-32da-b510-b9c643848b8f",
      "prefix": "§8[Player]§7"
    },
    {
      "name": "Pawoof_",
      "uuid": "a88edc15-2b3b-45e3-89f2-bc72c97e3e48",
      "prefix": "§b[Donator§4+§b]§7"
    },
    {
      "name": "Sharkkky",
      "uuid": "d67a867c-41ff-4ed7-bec0-8c1baeefb21d",
      "prefix": "§b[Donator§3+§b]§7"
    },
    {
      "name": "Sublim_",
      "uuid": "8e8e12b6-568f-4136-bc16-564dd030ad8e",
      "prefix": "§8[Player]§7"
    },
    {
      "name": "R0LU",
      "uuid": "74ef3909-260f-43d9-968b-db6d4b38b267",
      "prefix": "§b[Donator]§7"
    }
  ]
}

GET /api/v1/player/:identifier

Returns detailed information for a single player that has played on the server.

Request Format

Path Variables

• identifier (string) - The name or UUID of a player.

Response Format

• name (string) - The player's username.
• uuid (string) - The player's UUID.
• prefix (string) - The player's ingame prefix.
• online (boolean) - true if the player is currently online, false otherwise.
• first_join (long) - The epoch timestamp of the player's first join, in milliseconds.
• last_join (long) - The epoch timestamp of the player's last join, in milliseconds.
• overall (double) - The player's overall score.
• playtime (long) - The player's playtime, in milliseconds.
• balance (decimal) - The player's balance, which includes balances of banks they own.
• blocks_placed (long) - How many blocks the player has placed.
• blocks_broken (long) - How many blocks the player has broken.
• blocks_traveled (long) - How many blocks the player has traveled.
• players_killed (long) - How many players the player has killed.
• mobs_killed (long) - How many mobs the player has killed.
• deaths (long) - How often the player has died.
• damage_dealt (long) - How much damage the player has dealt to other players and mobs.
• damage_taken (long) - How much damage the player has taken.

Example Response

URL used: https://api.betamc.org/api/v1/player/zavdav

{
  "name": "zavdav",
  "uuid": "142d3862-e360-419b-9ab3-421fed84f565",
  "prefix": "§8[§4Admin§8]§7",
  "online": true,
  "first_join": 1738783621992,
  "last_join": 1785369362368,
  "overall": 522.364284027542,
  "playtime": 1573513273,
  "balance": 45942.1897607606,
  "blocks_placed": 49824,
  "blocks_broken": 153235,
  "blocks_traveled": 6482402.4611444084,
  "players_killed": 36,
  "mobs_killed": 1116,
  "deaths": 51,
  "damage_dealt": 66347,
  "damage_taken": 8496
}

GET /api/v1/leaderboard

Returns a page of a leaderboard containing players and their respective score on the leaderboard.

Request Format

Request Parameters

• category (string, required) - Specifies which leaderboard should be returned.
• page (int, optional) - The page on the respective leaderboard. Page numbers start at 0. Defaults to 0.

Valid leaderboard categories are:

• overall (double) - The player's overall score.
• playtime (long) - The player's playtime, in milliseconds.
• balance (decimal) - The player's balance, which includes balances of banks they own.
• blocks_placed (long) - How many blocks the player has placed.
• blocks_broken (long) - How many blocks the player has broken.
• blocks_traveled (long) - How many blocks the player has traveled.
• players_killed (long) - How many players the player has killed.
• mobs_killed (long) - How many mobs the player has killed.
• deaths (long) - How often the player has died.
• damage_dealt (long) - How much damage the player has dealt to other players and mobs.
• damage_taken (long) - How much damage the player has taken.

Response Format

• players (array) - An array representing the selected page of the selected leaderboard. Never exceeds a size of 10.
  • name (string) - The player's username.
  • uuid (string) - The player's UUID.
  • prefix (string) - The player's ingame prefix.
  • <statistic> (variable) - The player's score for the statistic targeted by the leaderboard. The field is named according to the category specified.
• total (int) - The number of entries in the leaderboard.
• page (int) - The selected page.
• pages (int) - The number of pages which can be retrieved.

Example Response

URL used: https://api.betamc.org/api/v1/leaderboard?category=blocks_placed&page=2

{
  "players": [
    {
      "name": "StayInSchoolKid",
      "uuid": "c455b223-f1a1-4d17-b9fe-0f47b58a3dba",
      "prefix": "§8[§9Mod§8]§7",
      "blocks_placed": 250815
    },
    {
      "name": "AozoraKii",
      "uuid": "88892fc3-226a-387a-bed0-606611ae7d00",
      "prefix": "§b[Donator§d+§b]§7",
      "blocks_placed": 244325
    },
    {
      "name": "scarletvixen",
      "uuid": "23791de3-6f69-4156-ac38-deced839a80b",
      "prefix": "§8[Player]§7",
      "blocks_placed": 229594
    },
    {
      "name": "EggBot751",
      "uuid": "29149df8-b2b6-4a7e-96b4-d3414ae10cf9",
      "prefix": "§8[§9Mod§8]§7",
      "blocks_placed": 229427
    },
    {
      "name": "Orknarok_666",
      "uuid": "413e630d-d87a-4cb7-adaf-01af67d014b2",
      "prefix": "§2[Trusted]§7",
      "blocks_placed": 227161
    },
    {
      "name": "matt",
      "uuid": "ea89fd1b-4c61-40a8-9999-80f3d70ebb57",
      "prefix": "§8[§9Mod§8]§7",
      "blocks_placed": 222986
    },
    {
      "name": "KingDaKa4",
      "uuid": "f1177546-fe39-462d-8ce6-a56f8515bed0",
      "prefix": "§b[Donator]§7",
      "blocks_placed": 220431
    },
    {
      "name": "MuaksimNo1",
      "uuid": "977ee282-508c-4e1f-9a7a-1d0fff81fd36",
      "prefix": "§8[Player]§7",
      "blocks_placed": 218444
    },
    {
      "name": "Creepaster",
      "uuid": "5c323712-fca6-4215-9846-019d9460bc93",
      "prefix": "§b[Donator§a+§b]§7",
      "blocks_placed": 186697
    },
    {
      "name": "607",
      "uuid": "c2cc4f08-9655-4510-bff8-22c239a07d62",
      "prefix": "§b[Donator]§7",
      "blocks_placed": 179732
    }
  ],
  "total": 22055,
  "page": 2,
  "pages": 2206
}