API Usage
CraftersAPI Documentation
Welcome to the CraftersAPI documentation. This API allows players to access various statistics from the Crafters.one server . To use the API, you need to obtain an API key, which is given on request via tickets, and make requests to the endpoints provided.
Obtaining an API Key
To interact with the CraftersAPI, you must have an API key. Open a ticket to request permission to use the API. Once permission is obtained; follow these steps to get your API key:
1. In-Game Command: Use the command /craftersapi new <NameOfAPIKey>
in-game to generate a new API key.
2. Viewing Keys: Use the command /craftersapi keys
to view your API keys.
3. Cancelling a Key: Use the command /craftersapi cancel <NameOfAPIKey>
to cancel an existing API key.
Making Requests
Base URL
All API requests are made to the following base URLs:
Version 2 (Recommended):
Version 1 (Deprecated):
Authentication
All requests to the API must include a valid API key. The API key should be included in the request headers with the key x-api-key.
Rate Limiting
The API is rate-limited to 600 requests per 10 minutes per API Key.
Version 2
It is recommended that you only use endpoints from the API Version 2, and store the results in a database for further processing.
Base URL
Headers
X-API-KEY
(required): Your API key. Required for all v2 endpoints.
Changes in this version
This version reduces the post-processing on the server-side. This makes requests for bulk data significantly faster, but relies on the end user to process the data themself (sorting, filtering, etc.)
A major structural change is the usage of path parameters, rather than query parameters, for some endpoints. This is indicated in the endpoint URL such as GET /player/<uuid>
where <uuid>
should be replaced with a player's UUID string.
Endpoints
Get Player
Retrieves special player data from the server. (i.e. data not included in stats or advancements)
Endpoint
GET /player/<uuid>
Parameters
uuid
(required): The UUID of the player whose info you want to retrieve.
Example Response
{
"uuid": "34e9f59b-854d-4889-9b06-a862933c3c94",
"username": "Plexiate",
"join_date": 1611876703869,
"last_seen": 1725869477354,
"number": 3,
"score": 23295,
"lifetime_xp": 752798
}
Get Advancements
Provides all advancements' completion status for a player. (If an advancement is not completed, it may or may not be included in the response at all.)
Endpoint
GET /advancements/<uuid>
Parameters
uuid
(required): The UUID of the player whose info you want to retrieve.
Example Response
{
"minecraft:adventure/adventuring_time": true,
...
}
Get Recipes
Provides all recipes' unlocked status for a player. (If a recipe is not unlocked, it may or may not be included in the response at all.)
Endpoint
GET /recipes/<uuid>
Parameters
uuid
(required): The UUID of the player whose info you want to retrieve.
Example Response
{
"minecraft:recipes/misc/blue_dye": true,
"minecraft:recipes/transportation/acacia_boat": true,
...
}
Version 1 (Deprecated)
Get Player Stats
Endpoint
GET /stats/players
Headers
x-api-key
(required): Your API key.
Parameters
player
(required): The UUID of the player whose stats you want to retrieve.
Example Request
GET https://crafters.one/api/v1/stats/players?player=PLAYER_UUID
Response
A successful request returns a JSON object containing the player's statistics. Example response:
"animals_bred": 172, "cake_slices_eaten": 52, "damage_absorbed": 649, "damage_dealt": 1296101, "damage_dealt_absorbed": 1061, "damage_dealt_resisted": 0, "damage_resisted": 17131, "damage_taken": 241982, "deaths": 44, "fish_caught": 715, "is_online": false, "join_date": 1611876703869, "jumps": 514088, "last_seen": 1717894499615, "mob_kills": 83480, "netherite_hoes_crafted": 1, "play_time": 9566304, "player_kills": 291, "score": 100, "time_since_death": 8611, "time_since_rest": 8631, "username": "Plexiate", "uuid": "34e9f59b-854d-4889-9b06-a862933c3c94"
Additional Information
- animals_bred: The number of animals bred by the player.
- cake_slices_eaten: The number of cake slices eaten by the player.
- damage_absorbed: The total damage absorbed by the player.
- damage_dealt: The total damage dealt by the player.
- damage_dealt_absorbed: The total damage dealt by the player that was absorbed.
- damage_dealt_resisted: The total damage dealt by the player that was resisted.
- damage_resisted: The total damage resisted by the player.
- damage_taken: The total damage taken by the player.
- deaths: The number of times the player has died.
- fish_caught: The number of fish caught by the player.
- is_online: A boolean indicating if the player is currently online.
- join_date: The timestamp of when the player first joined the server.
- jumps: The number of jumps made by the player.
- last_seen: The timestamp of when the player was last seen online.
- mob_kills: The number of mobs killed by the player.
- netherite_hoes_crafted: The number of netherite hoes crafted by the player.
- play_time: The total playtime in seconds.
- player_kills: The number of other players the player has killed.
- score: The player's current score.
- time_since_death: The time in seconds since the player last died.
- time_since_rest: The time in seconds since the player last rested.
- username: The player's username.
- uuid: The player's unique identifier.
For a statistic such as join_date and last_seen you can use a tool such as Unix Time Converter to get a date and time out of it.
Get World Stats
Endpoint
GET /stats/world
Headers
x-api-key
(required): Your API key.
Example Request
GET https://crafters.one/api/v1/stats/world
Response
A successful request returns a JSON object containing the player's statistics. Example response:
"day_count_end": 84978, "day_count_nether": 84977, "day_count_overworld": 16, "online_players": [ "Plexiate" ], "time_of_day": "day", "total_players": 865, "weather_overworld": "clear"
Additional Information
- day_count_end: The number of days that have passed in the End dimension.
- day_count_nether: The number of days that have passed in the Nether dimension.
- day_count_overworld: The number of days that have passed in the Overworld dimension.
- online_players: A list of players currently online.
- time_of_day: The current time of day in the game (e.g., "night").
- total_players: The total number of players who have joined the server.
- weather_overworld: The current weather in the Overworld (e.g., "clear").
Get Top Players
Endpoint
GET /stats/top_players
Headers
x-api-key
(required): Your API key.
Parameters
stat
(required): The bukkit statistic you want to retrieve.type
(optional): The Block, Item, or Entity when using DROP, PICKUP, MINE_BLOCK, USE_ITEM, BREAK_ITEM, CRAFT_ITEM, KILL_ENTITY, ENTITY_KILLED_BY, or TARGET_HIT.limit
(optional): The number of top players requested to return in the list. This can be left off to only retrieve the number one player.
Example Request
GET https://crafters.one/api/v1/stats/top_players?stat=STAT_HERE&type=TYPE_HERE&limit=10
Response
A successful request returns a JSON object containing the player's statistics. Example response:
"statistic": "CAKE_SLICES_EATEN", "top_players": [ { "username": "ShimmyMySherbet", "uuid": "892725c0-8f95-4561-bdf2-2d0ba15a4539", "value": 373 }, { "username": "legowarrior779", "uuid": "3da89c7a-fe24-49e6-aacc-728e38fbcdaa", "value": 266 }, { "username": "MommyTayy", "uuid": "fac7a21c-caed-4434-8733-e8ea1fe4d729", "value": 234 }, { "username": "MerelyMiserable", "uuid": "3411710b-9cfc-4360-aa9a-db9137ea9a37", "value": 228 }, { "username": "Cameron_TNT", "uuid": "9c2427cf-9cb1-405c-9a85-8f468e687ff5", "value": 168 } ]
Using Postman with CraftersAPI
Step-by-Step Guide
1. Install Postman: If you haven’t already, download and install Postman from Postman’s official website.
2. Open Postman
3. Create a New Request:
- Click on the “New” button in the top left corner of the Postman interface. - Select “HTTP” from the menu.
4. Set Up the Request:
- In the new request window, select “GET” from the dropdown menu next to the URL field. - Enter the URL for the API endpoint you want to test. For example, to get player stats, enter: https://crafters.one/api/v1/stats/players
5. Headers:
- Click on the “Headers” tab below the URL field. - Add the required query parameters: - x-api-key: Your API key.
6. Query Parameters:
- Click on the “Params” tab below the URL field. - Add the required query parameters: - player: The UUID of the player whose stats you want to retrieve.
7. Send the Request
8. View the Response
This documentation should help you get started with using the CraftersAPI. If you have any questions or encounter any issues please contact [email protected] or open a ticket for assistance.