Zavdav: Initial API documentation

2026-08-25T00:24:19Z

Initial API documentation

New page

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 <code><nowiki>https://api.betamc.org</nowiki></code>.

== GET /api/v1/server/stats ==

Returns a collection of total server statistics.

=== Response Format ===

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

=== Example Response ===

URL used: <code><nowiki>https://api.betamc.org/api/v1/server/stats</nowiki></code>

<pre>
{
"unique_players": 22055,
"economy_size": 4815877.6824758479,
"total_playtime": 487629222793
}
</pre>

== GET /api/v1/server/players ==

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

=== Response Format ===

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

=== Example Response ===

URL used: <code><nowiki>https://api.betamc.org/api/v1/server/players</nowiki></code>

<pre>
{
"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"
}
]
}
</pre>

== GET /api/v1/player/:identifier ==

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

=== Request Format ===

'''Path Variables'''
* <code>identifier</code> ''(string)'' - The name or UUID of a player.

=== Response Format ===

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

=== Example Response ===

URL used: <code><nowiki>https://api.betamc.org/api/v1/player/zavdav</nowiki></code>

<pre>
{
"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
}
</pre>

== GET /api/v1/leaderboard ==

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

=== Request Format ===

'''Request Parameters'''
* <code>category</code> ''(string, required)'' - Specifies which leaderboard should be returned.
* <code>page</code> ''(int, optional)'' - The page on the respective leaderboard. Page numbers start at 0. Defaults to 0.

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

=== Response Format ===

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

=== Example Response ===

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

<pre>
{
"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
}
</pre>

API - Revision history

Zavdav: Initial API documentation