v3.5 - User System

Related endpoints

• GET /player/{username}
• GET /player/{username}/characters/{uuid}
• GET /player
• GET /item/database
• POST /item/search
• GET /leaderboards/{lb_type}

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.