Voxyl Network API


Overview

To get access to the API, first you need an API key. An API key is your account's personal key. You can only have one key, where new keys will replace the old key.

To create a new API key use /api new on the Minecraft server, this will also override the existing key. If you instead want to see your existing key, use /api get.



REST API

The API is a simple REST API. This essentially means that any queries to the Voxyl API are stateless, and are passed through the HTTP request packet. The documentation uses the following terminology:

  • Path: This is a list of variables to be included in the path of the URL itself rather than a named URL parameter.
  • Parameters: To supply a parameter, there are three main scenarios.
    • Query strings are the standard method of specifying parameters.
    • Every endpoint has an api parameter. This can specified by the query string, or may alternatively be given by the voxyl-api-key header.
    • JSON request payloads are only available for post requests. To do so, set the content-type to application/json and put well-formed JSON in the body.
  • Returns: This lists the structure of the returned JSON data.

Example query: api.voxyl.net/player/info/e1b72de9-5b10-48fb-afe0-50eaa3e7b6eb?api=YOUR_API_KEY.
Replace YOUR_API_KEY with your API key, and put it in your web browser. Once done, congratulations! You did your first API request.

The following sections detail the format for specific queries. The rate limiting is currently quite generous, so do as many API requests as you need.

Each endpoint has a success field which indicates whether the request was successful. If the request was not successful then reason and reasonId are included. Some common reasonId values are no_api_key, invalid_api_key, missing_argument, invalid_argument, unhandled_exception


1. Player info

These are all the calls for player info.

1.1. Basic Info get api.voxyl.net/player/info/[uuid]
Path
uuid The UUID of the player.
Parameters
api Your API key.
Returns
lastLoginName The last name of the player.
lastLoginTime The last login time of the player, UNIX timecode in seconds.
role The rank or role of the player.

1.2. Overall Stats get api.voxyl.net/player/stats/overall/[uuid]
Path
uuid The UUID of the player.
Parameters
api Your API key.
Returns
level The level of the player.
exp The current experience for that level.
weightedwins Player's total weighted wins

1.3. Game Stats get api.voxyl.net/player/stats/game/[uuid]
Path
uuid The UUID of the player.
Parameters
api Your API key.
Returns
stats Key-value map of games.
stats[][wins] The number of games won.
stats[][kills] The kills in this specific game type.
stats[][beds] The total number of beds broken in the game if applicable.
stats[][finals] The total number of finals

1.4. Player Guild get api.voxyl.net/player/guild/[uuid]
Path
uuid The UUID of the player.
Parameters
api Your API key.
Returns
guildRole The guild role OWNER, ADMIN, MODERATOR, or MEMBER.
joinTime The join time (UNIX timestamp seconds).
guildId The ID of the guild. This is not the tag.

1.5. Get Player Stat Ranking get api.voxyl.net/player/ranking/[uuid]
Path
uuid The UUID of the player.
Parameters
api Your API key.
ref The game reference. Use /join list for a list of them in game.
type wins, kills, finals, or beds
Returns
ranking The ranking of the player

2. Guild info

Information about guilds.

2.1. Guild Info get api.voxyl.net/guild/info/[tag | -id]
Path
tag The tag of the guild.
id The ID of the guild. An alternative option (Use - prefix)
Parameters
api Your API key.
Returns
id The ID of the guild. Used internally.
name The name of the guild.
desc The description of the guild.
xp Total guild XP.
num The number of members.
ownerUUID The UUID of the owner.
time UNIX timestamp in seconds of the creation date.

2.2. Guild Members get api.voxyl.net/guild/members/[tag | -id]
Path
tag The tag of the guild.
id The ID of the guild. An alternative option (Use - prefix)
Parameters
api Your API key.
Returns
members An array containing all members in the guild.
members[][role] The guild role OWNER, ADMIN, MODERATOR, or MEMBER.
members[][uuid] The UUID of the member.
members[][time] The join time (UNIX timestamp seconds).

2.3. Top Guilds get api.voxyl.net/guild/top
Parameters
api Your API key.
num The top number to return. A maximum of 100.
Returns
guilds An array of guilds ordered by XP
guild[][placing] From 1, the placing of the guild.
guild[][id] The guild ID.
guild[][tag] The guild tag.
guild[][name] The name of the guild.
guild[][xp] The XP of the guild.

3. Announcements

View current announcements. This is viewable ingame with the books. Note: This endpoint is not finished yet :(.

3.1. Get All Announcements get api.voxyl.net/announcement/all
Parameters
api Your API key.
Returns
id The ID of the announcement.
title The title of the announcement.
author The UUID of the author.
time A UNIX timestamp in seconds of the publish time.

4. Leaderboards

View the leaderboards.

4.1. Get Normal Leaderboard get api.voxyl.net/leaderboard/normal
Parameters
api Your API key.
type The type of leaderboard: weightedwins or level.
num The number of rows to retrieve, max of 100.
Returns
players An array of players ordered by the type provided.
players[][position] From 1, the position of the player on the leaderboard.
players[][uuid] The UUID of the player.
players[][weightedwins] The number of weighted wins.
players[][level] The level of the player.

4.2. Get Technique Leaderboard get api.voxyl.net/leaderboard/technique
Parameters
api Your API key.
technique The technique type, do /techniquelist in game to view all.
Returns
players An array of players ordered by the type provided.
players[][position] From 1, the position of the player on the leaderboard.
players[][uuid] The UUID of the player.
players[][time] The time in milliseconds for the record.
players[][submittime] The submit time as a UNIX timestamp.

4.3. Get Game Leaderboard get api.voxyl.net/leaderboard/game/[ref]
Path
ref The game reference. Use /join list for a list of them in game.
Parameters
api Your API key.
period weekly or daily
type wins or winstreaks
Returns
players A list of players.
players[][uuid] The UUID of the player.
players[][value] The value, either wins or winstreaks.

5. Achievements

View a players achievements and information about those achievements.

5.1. Get Player Achievements get api.voxyl.net/achievements/player/[uuid]
Path
uuid The UUID of the player.
Parameters
api Your API key.
Returns
achievements[] A list of achievement IDs. The details of the IDs can be grabbed once and stored from the achievement info endpoint.

5.2. Get All Achievements get api.voxyl.net/achievements/info/
Parameters
api Your API key.
Returns
info[] A list of achievement objects.
info[][id] The ID of the achievement.
info[][name] The name of the achievement.
info[][xp] The XP rewarded for the achievement.
info[][desc] The description of the achievement.

6. Games

View specific information about games by their UUID.

6.1. Get Game Info get api.voxyl.net/game/info/[uuid]
Path
uuid The UUID of the game.
Parameters
api Your API key.
Returns
winnerUUID The UUID of the winner of the game. This may be null.
winningTeamId The ID of the winning team. This is an integer. -1 if there were no winners.
ref The game reference. Use /join list for a list of them in game.
timeStarted UNIX timecode in seconds.
numberOfPlayers The number of players who participated.
numberOfTeams The number of teams in the game.
secondsRunning The time, in seconds, that the game lasted.
totalKills The combined total of kills during the game.
totalFinals The combined total of final kills during the game.
midGameDisconnects The number of times people disconnected during the game.
mapID The ID of the map.
serverName The server the game was played on.
players[] A list of players who participated in the game.
players[][uuid] The UUID of the player. If the player is a bot, then the least significant bits of the UUID is 100 and the most significant bits is a small number.
players[][kills] The number of kills the player achieved.
players[][deaths] The number of times the player died during the game.
players[][finalKills] The number of final kills the player achieved.
players[][playTime] The number of seconds the player played the game.
players[][playTimePercentage] The percentage of the time the player was in the game.
players[][teamId] The team ID of the player.

6.2. Get Game Status get api.voxyl.net/game/status/[uuid]
Path
uuid The UUID of the game.
Parameters
api Your API key.
Returns
active Whether the game is currently active

7. Integration

View information about non-Minecraft accounts.

7.1. Get Discord From Player get api.voxyl.net/integration/discord_from_player/[uuid]
Path
uuid The UUID of the player.
Parameters
api Your API key.
Returns
id The id of the discord account.

7.2. Get Player From Discord get api.voxyl.net/integration/player_from_discord/[id]
Path
id The id of the discord account.
Parameters
api Your API key.
Returns
uuid The UUID of the player.

8. Privileged

Some API keys have extra privileges. Enter your API key into the form below to view documentation for additional features.