Introduction | Wynncraft

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.

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 and listed in 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 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` or `TOKEN`.

Errors

Errors use a common format:

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

See 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.

1 {
2   "error": "MultipleObjectsReturned",
3   "detail": "Query returned multiple results.",
4   "code": 300,
5   "objects": {
6     "1ed075fc-5aa9-42e0-a29f-640326c1d80c": {
7       "username": "Salted",
8       "rank": "Administrator",
9       "supportRank": "hero",
10       "shortenedRank": "Admin",
11       "legacyRankColour": {
12         "main": "#aa0000",
13         "sub": "#ff5555"
14       },
15       "rankBadge": "nextgen/badges/rank_owner.svg"
16     }
17   }
18 }

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.

1 @font-face {
2   font-family: "five";
3   src: url("https://cdn.wynncraft.com/nextgen/fonts/five.woff");
4   font-weight: normal;
5   font-style: normal;
6   font-display: block;
7 }
8 
9 .font-five {
10   font-family: "five";
11 }

Media URLs

Some responses include partial media paths. Complete those paths with the CDN base URL: https://cdn.wynncraft.com/nextgen

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