Achievements

Base: /api/achievements

Catalog, leaderboard and player progress of an optional achievements plugin

Handler: AchievementsHandler

Endpoints

GET /api/achievements/status Get achievements status GET /api/achievements/categories List categories GET /api/achievements/achievements List achievements GET /api/achievements/players List players GET /api/achievements/player/{name} Get player profile GET /api/achievements/recent Recent unlocks GET /api/achievements/server-firsts List server firsts POST /api/achievements/grant Grant achievement POST /api/achievements/revoke Revoke achievement

GET /api/achievements/status

Get achievements status

Shows whether an achievements plugin is installed, and if so its API version, plugin version and variant (gameKey).

Response Example

{
  "available": true,
  "apiVersion": 1,
  "pluginVersion": "1.3.5",
  "gameKey": "vulkim"
}

cURL

curl -X GET 'http://localhost:5550/api/achievements/status' \
  -H 'X-Admin-Token: YOUR_TOKEN'

`gameKey` is usually default. A customized variant such as Vulkim reports its own key. If no achievements plugin is installed, this endpoint still answers with 200 and only available: false, every other achievements endpoint then returns 404.

Internal Behavior

Looks for the general achievements plugin first, then the Vulkim variant, through a fixed class list.

GET /api/achievements/categories

List categories

Returns every achievement category with icon, German and English name and the number of achievements per category.

Response Example

[
  {
    "id": "zeit",
    "icon": "clock",
    "name_de": "Spielzeit",
    "name_en": "Playtime",
    "total": 8
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/categories' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Calls the categories method of the detected achievements plugin through reflection.

GET /api/achievements/achievements

List achievements

Returns the full achievement catalog with category, tier, goal, scope, German and English name and description, whether it is hidden, and how often it was already unlocked server wide.

Response Example

[
  {
    "id": "spielzeit_10h",
    "category": "zeit",
    "tier": "bronze",
    "hidden": false,
    "goal": 36000,
    "scope": "personal",
    "name_de": "Durchhalten",
    "name_en": "Staying Power",
    "desc_de": "Verbringe 10 Stunden auf dem Server",
    "desc_en": "Spend 10 hours on the server",
    "unlockedCount": 42
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/achievements' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Calls the achievements method through reflection, unlockedCount comes from a separate count per achievement.

GET /api/achievements/players

List players

Returns a page of players with number of unlocks, total points, last login and playtime.

Parameters

Name	Type	Required	Description
`limit`	integer	No	Page size, default 25, maximum 500
`offset`	integer	No	Offset for the next page, default 0

Response Example

[
  {
    "uuid": "5a6a1c2e-0000-0000-0000-000000000000",
    "name": "Eranio",
    "unlocked": 12,
    "total": 340,
    "lastSeen": 1760000000000,
    "playtimeSeconds": 54000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/players?limit=25&offset=0' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads a page of the player list from the plugin storage layer, no reflection needed.

GET /api/achievements/player/{name}

Get player profile

Returns playtime, active title, unlocked achievements with their time and the progress on ongoing achievements for a player.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name or UUID

Response Example

{
  "uuid": "5a6a1c2e-0000-0000-0000-000000000000",
  "name": "Eranio",
  "playtimeSeconds": 54000,
  "activeTitle": "Spielzeit Meister",
  "unlocked": [
    {
      "id": "spielzeit_10h",
      "unlockedAt": 1759999999000
    }
  ],
  "progress": [
    {
      "id": "spielzeit_50h",
      "current": 36000,
      "goal": 180000
    }
  ]
}

cURL

curl -X GET 'http://localhost:5550/api/achievements/player/Eranio' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Resolves the name first through the live online profile, otherwise through the storage layer. Returns 404 for an unknown player.

GET /api/achievements/recent

Recent unlocks

Returns the most recently unlocked achievements server wide with player, achievement and time.

Parameters

Name	Type	Required	Description
`limit`	integer	No	Count, default 20, maximum 200

Response Example

[
  {
    "player": "Eranio",
    "achievement": "spielzeit_10h",
    "at": 1759999999000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/recent?limit=20' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads the most recent unlocks from the storage layer, newest first.

GET /api/achievements/server-firsts

List server firsts

Returns, for every achievement that counts as a server first, who unlocked it first on the server.

Response Example

[
  {
    "achievement": "erster_boss",
    "uuid": "5a6a1c2e-0000-0000-0000-000000000000",
    "name": "Eranio",
    "at": 1759999999000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/achievements/server-firsts' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads the stored server firsts from the storage layer.

POST /api/achievements/grant

Grant achievement

Unlocks an achievement for a player.

Request Body

Field	Type	Required	Description
`player`	string	Yes	Player name or UUID, must be online
`id`	string	Yes	ID of the achievement

Response Example

{
  "success": true,
  "player": "Eranio",
  "id": "spielzeit_10h"
}

cURL

curl -X POST 'http://localhost:5550/api/achievements/grant' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"player": "Eranio", "id": "spielzeit_10h"}'

Only works while the player is online, the plugin needs a loaded profile for it.

Internal Behavior

Resolves the player through the live online profile and unlocks the catalog entry.

POST /api/achievements/revoke

Revoke achievement

Removes an already unlocked achievement from a player again.

Request Body

Field	Type	Required	Description
`player`	string	Yes	Player name or UUID, must be online
`id`	string	Yes	ID of the achievement

Response Example

{
  "success": true,
  "player": "Eranio",
  "id": "spielzeit_10h"
}

cURL

curl -X POST 'http://localhost:5550/api/achievements/revoke' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"player": "Eranio", "id": "spielzeit_10h"}'

Only works while the player is online.

Internal Behavior

Resolves the player through the live online profile, revokes the achievement and also deletes the entry asynchronously from the storage layer.