Eranio
Color theme

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.1 and publish the interface through a reverse proxy with HTTPS (nginx, Apache, Caddy). The proxy can also add its own limits.
  • Set a token as 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. Use trust-proxy: true only 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 sources section binds a counter to a game statistic, see the configuration guide.
  • Command counter. The commands section 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.