> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.wynncraft.com/2025-07-23-v3-5/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.wynncraft.com/_mcp/server.

# v3.5 - User System

## Related endpoints

* [GET /player/\{username}](https://docs.wynncraft.com/modules/player/get-player)
* [GET /player/\{username}/characters/\{uuid}](https://docs.wynncraft.com/modules/player/get-player-character)
* [GET /player](https://docs.wynncraft.com/modules/player/list-online-players)
* [GET /item/database](https://docs.wynncraft.com/modules/item-recipe/list-items)
* [POST /item/search](https://docs.wynncraft.com/modules/item-recipe/search-items)
* [GET /leaderboards/\{lb\_type}](https://docs.wynncraft.com/modules/leaderboards/get-leaderboard)

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](/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}](https://docs.wynncraft.com/modules/player/get-player)

* 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}](https://docs.wynncraft.com/modules/player/get-player-character)

* 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}](https://docs.wynncraft.com/modules/leaderboards/get-leaderboard)

* 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](https://docs.wynncraft.com/modules/item-recipe/list-items) and [POST /item/search](https://docs.wynncraft.com/modules/item-recipe/search-items)

* 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:

```json
{
  "controller": {
    "count": 5442,
    "current_count": 20,
    "pages": 273,
    "prev": null,
    "current": 1,
    "next": 2
  }
}
```

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:

```json
{
  "error": "ErrorName",
  "detail": "Error description",
  "code": 400
}
```

Multiple selectors follow the same structure:

```json
{
  "error": "MultipleObjectsReturned",
  "detail": "Query returned multiple results.",
  "code": 300,
  "objects": {
    "1ed075fc-5aa9-42e0-a29f-640326c1d80c": {
      "username": "Nepmia",
      "rank": "Owner",
      "supportRank": "hero",
      "shortenedRank": "Owner",
      "legacyRankColour": {
        "main": "#aa0000",
        "sub": "#ff5555"
      },
      "rankBadge": "nextgen/badges/rank_owner.svg"
    },
    "98bc2236-ada5-4039-b560-8aaa4cc50384": {
      "username": "nepmia",
      "rank": "Administrator",
      "supportRank": null,
      "shortenedRank": "Admin",
      "legacyRankColour": {
        "main": "#aa0000",
        "sub": "#ff5555"
      },
      "rankBadge": "nextgen/badges/rank_administrator.svg"
    }
  }
}
```

See [Exceptions](/exceptions) for the current exception reference.