If you're a developer for mods and plugins you're probably interested in an API to deliver the raw head data for your plugin.

What the API can do

With our API, you can do requests on each category of the custom heads section.

Within the response, you get the name, value and uuid of the heads and the tags if activated.

The API is not able to return the heads of a certain tag only or submit heads on its own.

Currently, only heads inside the Minecraft Heads Collection (MCH Collection) are delivered.

When to use the API

You should only use the API if you need regular updates on all heads of a certain category.

Remember to cache the API results. We usually do a head release once a week, so the result of the API also only changes once a week.

If you just need a few heads for example as menu items or for a few custom items in the game, you don't have to call the API.

Simply use the values from each heads page directly within your plugin.

This makes your plugin a lot faster since all API calls need a few seconds to load while it's not necessary to do so.

How to use the API

In order to get the heads of a certain category, add the url query "cat=category" to the API url, while the category is one of the following:

• alphabet
• animals
• blocks
• decoration
• food-drinks
• humans
• humanoid
• miscellaneous
• monsters
• plants

If you would like to get the tags as well, add "tags=true" to the url query.

If you start a project with the Minecraft Heads API

Please contact us before you start the project and tell us about your plans.

After the project, we please you to add a banner to your projects website which links back to us.

You can find some proper banners here.

So where can I find the API?

Minecraft Heads API

Minecraft Heads v2.0 - API Updates

The API will be rewritten as one of the first projects after the release of Minecraft Heads v2.0.

You'll get additional info as soon as the planning phase begins.

Keep an eye on our Discord in order to get all updates.

There'll be a transition phase where both APIs are active so you have time to update your plugin or mod.