Reminder:

V1 and V2 APIs are officially deprecated and will be referred to as Legacy APIs from now on.

Introduction

The Wynncraft API is a tool provided to Wynncraft players to interact with many aspects of the game alongside other players. The API is not 100% complete yet (see planned features), however this documentation should help you to get started with it.

If you are migrating from one of our legacy API, know that we tried to keep the data structure as similar as possible to make migration easier, however, some structures have been completely reworked (e.g. Player Stats) because the old structures were non-practical.

Changelogs and announcements for upcoming changes on the API are on the developer discord.

Current API location

The Wynncraft API is located at https://api.wynncraft.com/v3 .

Caching

Each GET request is cached with a different TTL, requests having a cache possess a Cache-Control header and their documentation has their TTL.

Throttling and Rate-Limit

Throttling rules allows clients to perform 120 requests per minute at the moment, when the user system will be released, users will have the ability to request higher request amount before being rate-limited.

Headers

The API include quality of life HTTP Headers:

• Cache-Control: TTL of the current route in seconds
• Date: Date of the current request
• Expires: If the route is cached, this will be the date when the cache will be purged
• RateLimit-Remaining: Number of requests before being Rate-Limited
• RateLimit-Reset: Number of seconds before the Rate-Limit counter resets
• RateLimit-Limit: Number of allowed request in a cycle, 120 as stated above
• Version: Current version of the API (currently v3.3)

Multi-selectors

There are some edges cases where multiple objects can match your query, in that case the API will return a special response containing the said objects. This response will be easely identifiable as it is using the status code 300: Multiple Choices and will always use the same data structure:

"objectIdentifier (UUID/Prefix/...)": {
    "descriptiveKey1": "descriptiveValue1",
    "descriptiveKey2": "descriptiveValue2",
    # [...]
}

API Markup parser

The API automatically parses in-game config that use MC colors codes or our custom markup to predictable and usable HTML.

To properly reparse it / use it yourself here are the rules it uses:

• All tags will always be <span>
• The only classes you can find on those tags are font classes
• The style attribute on tags can only contain these values:
  • text-decoration: underline
  • text-decoration: line-through
  • font-style: italic
  • font-weight: bolder
  • color: colValue (colValue is variable but will always be in a hexadecimal format so #XXXXXX)
  • margin-left with value of 7.5px OR 20px
• The class attribute on tags can only contain these classes:
  • font-ascii => The regular wynncraft font
  • font-common => Font containing elemental & combat related icons
  • font-default => Merged version of common and ascii (extremely rare if you see it, it's actually worth a bug report)
  • font-five => The font used in elements like banners in-game
  • font-wynnic => Wynic as a web font
  • font-high_gavelian => High gavelian font

All these fonts are available on our CDN for usage, they're located at /nextgen/fonts and has the .woff format. Their name is the same as their class name if you remove the font- prefix.

TIP

You can simply load one of the font with 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';
}

Planned features

We have made an announcement about planned features for the API and the web network in general, read it here

FAQ

Why are player stats split in 3 different routes instead of 1?

This is done to optimize response content, there are use cases where all stats would be needed but in reality, when you request player stats, you usually don't need every character, and if you do it's to calculate stats on all of them, which is why we included a bunch of those in the player main stats in globalData, if you think some global data are missing you can always request for them to be added.

If you still wish to have full player stats you can add a query parameter to your request:
?fullResult=True which will return a response with every character included.

Is there a way to bypass pagination on item results?

Yes, you can use ?fullResult=True in the URL to return everything in one response.

Is there a way to hide some of my stats from the public?

Yes, you can use the command /toggle publicProfile to hide some public info. Currently skillPoints in player character data and the access to player character ability map

Can you add X and X to the API?

The API is still in development, not all features you may want are added to it yet, but we do read your suggestions on features so feel free to give us some.