Changelog

v3.5 - User System

v3.5 is mostly an internal platform update. Response skeletons are mostly similar, but users, developer tokens, privacy rules, per-user cache, and the new throttling system were added.

Authentication and users

See Authentication for the current authentication guide.

  • Added user accounts.
  • Added TOTP-based two-factor authentication.
  • Added token authentication through Authorization: Bearer <token>.
  • Added public tokens. Public tokens still use the token owner’s user cache and throttling identity, but requests behave like anonymous requests and do not bypass privacy settings.
  • Added per-user cache.
  • Added per-module throttling.
  • Added higher request limits for authenticated users.
  • Added theming.
  • Added Discord linking.
  • Added multiple Minecraft account linking and primary-account selection.
  • Added limited data request support.
  • Added privacy options controlling player stats route behavior.

OAuth2 is not included in this initial release, but it is planned for a future patch.

Response headers

  • Ratelimit-Bucket > The bucket the request belongs to.
  • Ratelimit-Limit > Requests allowed per minute for the current bucket.
  • Ratelimit-Reset > Remaining time before the current request cycle resets.
  • UserID > Authenticated user ID.
  • UserType > Authenticated user type, such as SESSION or TOKEN.
  • Cache-Source > User or Shared.

User cache is shared between session and token requests for the same user, except when using a public token.

Throttling

Initial throttling buckets:

  • SHARED: 50 RPM guest / 120 RPM authenticated.
  • PLAYER: 50 RPM guest / 120 RPM authenticated.
  • GUILD: 50 RPM guest / 120 RPM authenticated.
  • ITEMS: 50 RPM guest / 120 RPM authenticated.
  • LEADERBOARDS: 50 RPM guest / 120 RPM authenticated.
  • MAP: 50 RPM guest / 120 RPM authenticated.

Buckets are tracked independently. For example, using both the PLAYER and GUILD buckets gives each bucket its own request budget.

Authentication limitations:

  • Unlocking tokens requires at least one linked Minecraft account.
  • Accounts without a linked Minecraft account do not receive raised throttling rates.

Player profile and character endpoints

GET /player/{username}

  • Added restrictions to responses affected by privacy rules.
  • Added featuredStats, containing the five stats chosen by the player.
  • featuredStats is empty when the player has hidden main stats.
  • Online status privacy removes the player from the online player list, but still counts them in the total online player count.

GET /player/{username}/characters/{uuid}

  • Added configurable character skeleton output.
  • Character skeleton customization can remove individual stats from character data while keeping them in global data.
  • Added removedStat, listing stats removed from the character skeleton.

Leaderboards

GET /leaderboards/{lb_type}

  • Added leaderboard opt-out.
  • Opting out takes effect after the next leaderboard computation, usually within roughly 10 minutes.
  • Opting out anonymizes leaderboard entries instead of deleting scores.

Item endpoints

GET /item/database and POST /item/search

  • Fixed an issue where items could be skipped in pagination.
  • Changed pagination controller format.
  • Requests above the maximum page now return the last page instead of failing unexpectedly.

Controller format:

1{
2  "controller": {
3    "count": 5442,
4    "current_count": 20,
5    "pages": 273,
6    "prev": null,
7    "current": 1,
8    "next": 2
9  }
10}

An advanced search endpoint with modular filters and operators such as equality, greater-than, less-than, and ranges was started but not included in this release.

Error handling

Error responses now use a structured format:

1{
2  "error": "ErrorName",
3  "detail": "Error description",
4  "code": 400
5}

Multiple selectors follow the same structure:

1{
2  "error": "MultipleObjectsReturned",
3  "detail": "Query returned multiple results.",
4  "code": 300,
5  "objects": {
6    "1ed075fc-5aa9-42e0-a29f-640326c1d80c": {
7      "username": "Nepmia",
8      "rank": "Owner",
9      "supportRank": "hero",
10      "shortenedRank": "Owner",
11      "legacyRankColour": {
12        "main": "#aa0000",
13        "sub": "#ff5555"
14      },
15      "rankBadge": "nextgen/badges/rank_owner.svg"
16    },
17    "98bc2236-ada5-4039-b560-8aaa4cc50384": {
18      "username": "nepmia",
19      "rank": "Administrator",
20      "supportRank": null,
21      "shortenedRank": "Admin",
22      "legacyRankColour": {
23        "main": "#aa0000",
24        "sub": "#ff5555"
25      },
26      "rankBadge": "nextgen/badges/rank_administrator.svg"
27    }
28  }
29}

See Exceptions for the current exception reference.