Interfaces for websites and plugins
Eranio Published on: 15. November 2026
Achievements (Minecraft): Interfaces for websites and other plugins
Three ways to work with the data: a read only web interface for your own website, a Java API for other plugins, and own achievements from a file. All of them work on your own server without eranio.de and without any panel.
Web interface (read only)
The plugin can answer JSON requests over HTTP. It is off by default.
web-api:
enabled: true
port: 8765
bind: 127.0.0.1
token: 'a-long-random-text'
cors-origins: ['https://example.org']
rate-limit-per-minute: 120
trust-proxy: false
| Key | Meaning |
|---|---|
enabled |
Starts the interface with the server |
port, bind |
Where it listens. 127.0.0.1 is only reachable from the same machine, use a reverse proxy for the internet |
token |
If set, every request needs the header Authorization: Bearer <token>. If empty, anybody who can reach the port can read the public data below |
cors-origins |
Websites that may call the interface from a browser (* allows all). Needed only for JavaScript on another domain |
rate-limit-per-minute |
Requests per address and minute, 0 switches the limit off |
trust-proxy |
Use the X-Forwarded-For header of your reverse proxy as the visitor address for the limit |
The interface only reads. Players with a private profile never appear. It never returns IP addresses or other personal data besides name, UUID and progress.
Endpoints
Every answer is JSON with the field schema (currently 1). Successful answers carry the payload in data, errors carry error with code and message. Time values are ISO 8601 in UTC. Fields are only ever added, never renamed inside schema 1.
| Request | Answer |
|---|---|
GET /api/v1/status |
Plugin version, API version, game, number of achievements and categories, players online and known |
GET /api/v1/players?limit=50&offset=0 |
Players sorted by points (limit 1 to 200). Private profiles are skipped, so a page can be shorter than limit |
GET /api/v1/players/{name or uuid} |
One player with points, unlocked_by_tier, points_by_tier, unlocks and progress. Secret achievements show up in progress only after they are unlocked |
GET /api/v1/leaderboard?by=points&limit=10 |
Ranking by points, unlocked or playtime (limit 1 to 100) with a rank per row |
GET /api/v1/achievements |
The catalog with categories and achievements. Secret ones show ??? and no goal. Includes unlocked_count and rarity_percent |
GET /api/v1/recent?limit=20 |
The latest unlocks of public players |
Example for GET /api/v1/leaderboard?limit=2:
{
"schema": 1,
"data": [
{ "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Alex", "unlocked": 87, "points": 2310, "playtime_seconds": 412800, "last_seen": "2026-11-15T09:12:44Z", "rank": 1 },
{ "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6", "name": "Steve", "unlocked": 64, "points": 1675, "playtime_seconds": 301200, "last_seen": "2026-11-14T21:03:10Z", "rank": 2 }
]
}
Example for an error:
{ "schema": 1, "error": { "code": "not_found", "message": "Unknown player" } }
| Status | error.code |
Meaning |
|---|---|---|
| 400 | bad_request |
A parameter has a wrong value |
| 401 | unauthorized |
Token missing or wrong |
| 404 | not_found |
Unknown player or endpoint, or a private profile |
| 405 | method_not_allowed |
Only GET and OPTIONS are accepted |
| 429 | rate_limited |
Too many requests, wait the seconds from the Retry-After header |
| 500 | internal_error |
Unexpected error, see the server log |
Data of players who are online is current. Saved values of players who are offline are at most one minute old.
Examples
curl:
curl -H 'Authorization: Bearer a-long-random-text' 'http://127.0.0.1:8765/api/v1/leaderboard?by=points&limit=5'
Plain PHP with a cache file (asks the server at most once a minute):
<?php
function leaderboard(): array
{
$cache = sys_get_temp_dir() . '/achievements-leaderboard.json';
if (is_file($cache) && time() - filemtime($cache) < 60) {
return json_decode(file_get_contents($cache), true)['data'];
}
$context = stream_context_create(['http' => [
'header' => "Authorization: Bearer a-long-random-text\r\n",
'timeout' => 3,
]]);
$body = @file_get_contents('http://127.0.0.1:8765/api/v1/leaderboard?limit=10', false, $context);
if ($body === false) {
return is_file($cache) ? json_decode(file_get_contents($cache), true)['data'] : [];
}
file_put_contents($cache, $body);
return json_decode($body, true)['data'];
}
foreach (leaderboard() as $row) {
echo htmlspecialchars($row['rank'] . '. ' . $row['name'] . ': ' . $row['points'] . ' points') . "<br>\n";
}
Laravel:
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;
$top = Cache::remember('achievements.leaderboard', 60, function () {
return Http::withToken(config('services.achievements.token'))
->timeout(3)
->get(config('services.achievements.url') . '/api/v1/leaderboard', ['limit' => 10])
->throw()
->json('data');
});
JavaScript on a website (needs your domain in cors-origins, and a read only token is not secret in a browser, so use an empty token or a proxy on your own server):
<ol id="top"></ol>
<script>
fetch('https://stats.example.org/api/v1/leaderboard?limit=10')
.then((r) => r.json())
.then((body) => {
const list = document.getElementById('top');
body.data.forEach((row) => {
const li = document.createElement('li');
li.textContent = row.name + ': ' + row.points + ' points';
list.appendChild(li);
});
});
</script>
Security
- Keep
bind: 127.0.0.1and publish the interface through a reverse proxy with HTTPS (nginx, Apache, Caddy). The proxy can also add its own limits. - Set a
tokenas soon as the port is reachable from other machines, and keep it out of JavaScript that visitors can read. For a public leaderboard let your own server fetch the data and cache it, as in the PHP examples. - Only list the websites you really use in
cors-origins. Usetrust-proxy: trueonly when a proxy you control sits in front.
Java API for other plugins
The API lives in the package de.eranio.achievements.minecraft.api. Get it from the Bukkit services manager with AchievementsApi.get(), which returns null when Achievements is not installed. Add softdepend: [Achievements] (or depend) to your plugin.yml and the small jar Achievements-API-1.0.0.jar as a compileOnly file dependency, it contains only the API classes and events.
Reading
| Method | Returns |
|---|---|
apiVersion(), pluginVersion(), gameKey() |
Versions and the game key (minecraft) |
categories(), achievements() |
The catalog with names and descriptions in German and English, tier, points, goal, unlock count and rarity |
player(uuidOrName) |
PlayerInfo with points, points and unlocks per tier, unlock list and progress list |
players(limit, offset), leaderboard(by, limit) |
PlayerSummary rows, by is points, unlocked or playtime |
recentUnlocks(limit) |
The latest unlocks of public players |
progress(uuid, key) |
The current value of a counter |
Reading touches the storage. Call it away from the main thread on busy servers.
Writing
| Method | Effect |
|---|---|
addProgress(uuid, key, amount) |
Raises a counter. Achievements bound to the counter unlock on their own |
raiseProgress(uuid, key, value) |
Raises a counter to at least this value |
grant(uuid, id), revoke(uuid, id) |
Unlocks or removes an achievement of an online player |
registerAchievement(owner, CustomAchievement) |
Adds an achievement at runtime, with category, tier, goal, icon and German and English texts. Unlocks stay when the owner is disabled |
unregisterAchievements(owner) |
Removes everything the owner registered |
Events
AchievementUnlockEvent is fired before an unlock and can be cancelled. AchievementProgressEvent is fired whenever a counter changes and carries the key, the previous and the current value.
Example
public final class ExampleAddon extends JavaPlugin implements Listener {
private AchievementsApi achievements;
@Override
public void onEnable() {
achievements = AchievementsApi.get();
if (achievements == null) {
getLogger().warning("Achievements is not installed");
return;
}
achievements.registerAchievement(this, CustomAchievement.builder("example_lucky_fisher")
.category("example", "Beispiel-Plugin", "Example plugin", "FISHING_ROD")
.tier("silber")
.icon("COD")
.counter("example_lucky_catches", 10)
.german("Glückspilz", "Fange 10 Mal einen Schatz.")
.english("Lucky angler", "Catch treasure 10 times.")
.build());
getServer().getPluginManager().registerEvents(this, this);
}
@EventHandler
public void onFish(PlayerFishEvent event) {
if (event.getState() == PlayerFishEvent.State.CAUGHT_FISH && event.getCaught() != null) {
achievements.addProgress(event.getPlayer().getUniqueId(), "example_lucky_catches", 1);
}
}
@EventHandler
public void onUnlock(AchievementUnlockEvent event) {
if (event.getPlayer().getWorld().getName().equals("blocked")) {
event.setCancelled(true);
}
}
@EventHandler
public void onProgress(AchievementProgressEvent event) {
if (event.getKey().equals("example_lucky_catches")) {
event.getPlayer().sendMessage("Catches: " + event.getCurrent());
}
}
public int pointsOf(Player player) {
return achievements.player(player.getUniqueId().toString()).map(AchievementsApi.PlayerInfo::points).orElse(0);
}
}
Own achievements from a file
Create plugins/Achievements/custom-achievements.yml next to the bundled catalog. It uses the same structure and is merged on start and on /achievements reload. An id that exists already is replaced.
categories:
server:
icon: COMPASS
de: Unser Server
en: Our server
commands:
warps_used: ['/warp', '/home']
achievements:
traveller:
category: server
tier: silber
icon: ENDER_PEARL
key: warps_used
goal: 25
de: {name: "Vielreisender", desc: "Nutze 25 Mal /warp oder /home."}
en: {name: "Frequent traveller", desc: "Use /warp or /home 25 times."}
helper:
category: server
tier: gold
icon: EMERALD
key: helped_players
goal: 10
de: {name: "Helfer", desc: "Hilf 10 Spielern."}
en: {name: "Helper", desc: "Help 10 players."}
Three kinds of triggers:
- Statistic. The
sourcessection binds a counter to a game statistic, see the configuration guide. - Command counter. The
commandssection counts every time a player runs one of the listed commands. - Manual. A key without source or command is only raised by hand or by another plugin. From the console or a script:
/achievements progress <player> <id or counter> <amount>. For<id or counter>you can give an achievement id or the counter name,<amount>is added.
Tables for MySQL
With storage.type: mysql a website can read the tables directly. Write through the API, not into the tables.
| Table | Columns |
|---|---|
ach_players |
uuid, name, first_join, last_seen (ms), private_profile (1 = hide), active_title, points, achievements (count), playtime_seconds |
ach_counters |
uuid, ckey, value |
ach_sets |
uuid, skey, value (for example visited biomes) |
ach_unlocks |
uuid, achievement, unlocked_at (ms) |
ach_achievements |
The catalog: id, sort, category, category_de, category_en, tier, points, hidden, icon, goal, name_de, desc_de, hint_de, name_en, desc_en, hint_en |
Skip rows with private_profile = 1 on public pages, and do not show hint_* or the texts of secret achievements (hidden = 1) that a player has not unlocked.