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

# Introduction

> **Note**
>
> V1 and V2 APIs are deprecated and are considered legacy APIs.

The Wynncraft API lets applications read public game, player, guild, item, leaderboard, map, and news data.

Base URL:

[https://api.wynncraft.com/v3](https://api.wynncraft.com/v3)

If you are migrating from a legacy API, most structures were kept familiar where practical. Some responses were reworked where the old shape was difficult to use, especially player stats.

API changelogs and upcoming changes are announced on the [developer Discord](https://discord.gg/nUFD9xX) and listed in [changelog](/changelog).

## Caching

GET requests are cached with route-specific TTLs. Cached responses include standard cache headers such as `Cache-Control` and `Expires`.

Responses can come from different cache sources:

| Source   | Description                                                                   |
| -------- | ----------------------------------------------------------------------------- |
| `USER`   | Cached for the current authenticated user. Shared between that user's tokens. |
| `SHARED` | Cached globally and shared between all callers.                               |

## Throttling and Rate Limits

Rate limits are tracked per bucket. Current buckets are:

| Bucket         |  Guest | Authenticated |
| -------------- | -----: | ------------: |
| `SHARED`       | 50 RPM |       120 RPM |
| `PLAYER`       | 50 RPM |       120 RPM |
| `GUILD`        | 50 RPM |       120 RPM |
| `ITEMS`        | 50 RPM |       120 RPM |
| `LEADERBOARDS` | 50 RPM |       120 RPM |
| `MAP`          | 50 RPM |       120 RPM |

Each bucket is tracked independently. For example, using both `PLAYER` and `GUILD` buckets allows requests against each bucket separately.

See [Authentication](/authentication) for authenticated request support.

## Headers

The API includes quality-of-life HTTP headers:

| Header                | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `Cache-Control`       | TTL of the current route in seconds.                     |
| `Cache-Source`        | Origin of the cached content.                            |
| `Date`                | Date of the current request.                             |
| `Expires`             | Expiration date for cached responses.                    |
| `RateLimit-Remaining` | Requests remaining before rate limiting.                 |
| `RateLimit-Reset`     | Seconds before the rate-limit counter resets.            |
| `RateLimit-Limit`     | Allowed requests in the current cycle.                   |
| `RateLimit-Bucket`    | Rate-limit bucket used by the request.                   |
| `Version`             | Current API version.                                     |
| `UserID`              | Authenticated user ID, when authenticated.               |
| `UserType`            | Authenticated user type, `SESSION`, `TOKEN`, or `OAUTH`. |

## Errors

Errors use a common format:

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

See [Exceptions](/exceptions) for the known exception list.

## Multi-Selectors

Some queries can match multiple resources. In those cases, the API can return a `MultipleObjectsReturned` response with code `300` and an `objects` dictionary.

```json
{
  "error": "MultipleObjectsReturned",
  "detail": "Query returned multiple results.",
  "code": 300,
  "objects": {
    "1ed075fc-5aa9-42e0-a29f-640326c1d80c": {
      "username": "Salted",
      "rank": "Administrator",
      "supportRank": "hero",
      "shortenedRank": "Admin",
      "legacyRankColour": {
        "main": "#aa0000",
        "sub": "#ff5555"
      },
      "rankBadge": "nextgen/badges/rank_owner.svg"
    }
  }
}
```

## API Markup Parser

Some API fields contain rendered Wynncraft markup as HTML. The parser always emits predictable `<span>` elements.

Allowed style values:

* `text-decoration: underline`
* `text-decoration: line-through`
* `font-style: italic`
* `font-weight: bolder`
* `color: #XXXXXX`
* `margin-left: 7.5px`
* `margin-left: 20px`

Allowed classes:

| Class                | Description                                  |
| -------------------- | -------------------------------------------- |
| `font-ascii`         | Regular Wynncraft font.                      |
| `font-common`        | Elemental and combat icon font.              |
| `font-default`       | Merged common/ascii font. Rare in responses. |
| `font-five`          | Font used by some in-game banners.           |
| `font-wynnic`        | Wynnic web font.                             |
| `font-high_gavelian` | High Gavelian font.                          |
| `font-old_fruman`    | Old Fruman font.                             |

Fonts are available on the CDN under

[https://cdn.wynncraft.com/nextgen/fonts](https://cdn.wynncraft.com/nextgen/fonts)

.

```css
@font-face {
  font-family: "five";
  src: url("https://cdn.wynncraft.com/nextgen/fonts/five.woff");
  font-weight: normal;
  font-style: normal;
  font-display: block;
}

.font-five {
  font-family: "five";
}
```

## Media URLs

Some responses include partial media paths. Complete those paths with the CDN base URL:

[https://cdn.wynncraft.com/nextgen](https://cdn.wynncraft.com/nextgen)

The API will never return the full URLs for assets coming from the CDN.