◀ Back to Blog

What Is Minecraft Heads API? Guide to MCHeads v2.0

Introduction

If you’re asking what is Minecraft Heads API, you’re usually looking for the MCHeads / Minecraft Heads head-data API: a REST API that lets developers fetch Minecraft player head data, avatar previews, and texture metadata from a service associated with the Minecraft Heads website. It is not a generic Minecraft mod, and it is not an official Mojang service. The API exists so websites, plugins, and tools can fetch head images, player profiles, and related metadata without manual copying or scraping.

Minecraft Heads is the name most users associate with the head database and the website, while MCHeads is commonly used for the service behind it. The website lets people browse and copy heads by hand; the API lets developers query the same kind of data from code. That difference matters if you’re building a plugin, a dashboard, a profile page, or any other website integration that needs live Minecraft head data.

Players use it to find head icons. Server owners use it to power menus and cosmetics. Plugin developers and web developers use it to automate head lookup inside a plugin, admin panel, or dashboard.

This guide covers the practical side: available endpoints, JSON response structure, usage examples, rate limits, troubleshooting, and best practices. Before shipping production code, check the current documentation for the latest behavior and any changes from Mojang-related name or UUID handling.

What is Minecraft Heads API?

Minecraft Heads API is a developer-facing REST API used by sites and tools to look up Minecraft player head data from MCHeads and related head libraries. It typically returns a player head image, skin texture metadata, and lookup data tied to a username or UUID, often in JSON. That makes it easy to map a player’s identity to their rendered avatar or head preview.

This is different from browsing Minecraft Heads in a web UI, where you manually search and copy a head. With the API, your code requests data directly for profile cards, dashboards, server plugins, and community websites. Unless the current documentation explicitly says otherwise, it is separate from Mojang’s official services and should not be treated as an official Mojang API.

Is Minecraft Heads API the same as MCHeads?

In practice, people often use the names interchangeably, but they are not always identical in meaning. Minecraft Heads usually refers to the website and head collection, while MCHeads often refers to the service or API behind it. If you are comparing the Minecraft Heads website with the MCHeads API, think of the website as the browsing interface and the API as the programmatic interface.

Is Minecraft Heads API official?

No. It is not an official Mojang API. It is a third-party REST API built around Minecraft player data and head rendering.

Do I need an API key to use Minecraft Heads API?

That depends on the current documentation for API v2.0. Some endpoints may be public, while others may require an API key, bearer token, or another credential. If the service allows anonymous access, you can call it from a browser, Node.js, or PHP without a key. If it requires authentication, include the required header or token exactly as documented.

What endpoints does Minecraft Heads API offer?

The exact endpoint list can change, but the common patterns are:

  • Username lookup endpoint: resolves a Minecraft username to head data
  • UUID lookup endpoint: resolves a Minecraft UUID to head data
  • Player head endpoint: returns the head asset or a link to the head asset
  • Texture endpoint: returns the underlying texture URL or texture metadata

A request may use a path parameter such as /heads/username/Notch or a query parameter such as ?username=Notch. The current documentation should be your source of truth for the exact route names.

How do I get a Minecraft player head by username?

Use the username lookup endpoint and pass the player’s username in the path or query string. A typical flow is:

  1. Send the request to the username endpoint.
  2. Read the returned JSON.
  3. Extract the head image or texture link.
  4. Use that link in your app, plugin, or website.

Example with cURL:

curl -s "https://api.mcheads.net/v2/heads/username/Notch"

Example with JavaScript fetch:

async function getHeadByUsername(username) {
  const res = await fetch(`https://api.mcheads.net/v2/heads/username/${encodeURIComponent(username)}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return await res.json();
}

How do I get a Minecraft player head by UUID?

Use the UUID lookup endpoint and pass the player’s UUID. This is usually the better option for long-term storage because usernames can change.

Example with cURL:

curl -s "https://api.mcheads.net/v2/heads/uuid/069a79f444e94726a5befca90e38aaf5"

Example with PHP:

$json = file_get_contents('https://api.mcheads.net/v2/heads/uuid/069a79f444e94726a5befca90e38aaf5');
$data = json_decode($json, true);

If you need to find a UUID first, use a Mojang profile lookup tool, a trusted UUID finder, or your own account database. For Java Edition players, the UUID is the stable identifier you should cache and store.

What does the API response look like?

A successful response is usually JSON containing head data and player metadata. The exact schema depends on the endpoint and version, but a typical response may include:

  • username
  • uuid
  • textureUrl
  • headImageUrl
  • skinTexture
  • signature

Example shape:

{
  "username": "Notch",
  "uuid": "069a79f444e94726a5befca90e38aaf5",
  "textureUrl": "https://.../texture.png",
  "headImageUrl": "https://.../head.png",
  "skinTexture": {
    "value": "...",
    "signature": "..."
  }
}

Error responses are usually shorter and may include a status code, message, or error object instead of head data.

What JSON fields are returned by the API?

Field names vary by endpoint and version, so confirm the current documentation before coding against them. Common fields include:

  • username for the Minecraft player name
  • uuid for the player identifier
  • textureUrl for the raw texture URL
  • headImageUrl for the rendered image of the player head
  • skinTexture for the underlying skin texture payload
  • renderedImage for a preview or avatar-style image

If your app depends on a specific field, build a fallback path for missing keys.

What is the difference between a head image URL and a texture URL?

A head image URL points to a rendered image of the Minecraft player head. It is usually the easiest option for a website, profile card, or dashboard because you can display it directly.

A texture URL points to the underlying skin texture or texture asset. Use it when you need the raw source for custom rendering, plugin logic, or image processing.

In short:

  • Head image URL = ready-to-display rendered image
  • Texture URL = raw texture source used to generate the image

Does Minecraft Heads API have rate limits?

Most public APIs do, and this one may as well. Check the current documentation for the exact rate limit rules, burst behavior, and any 429 handling. Even if the service is generous, you should still cache responses and avoid repeated lookups for the same username or UUID.

Can I use Minecraft Heads API in JavaScript?

Yes. JavaScript is a common choice for browser apps, Node.js services, and frontend dashboards. Use fetch, handle errors, and cache the response when possible.

If you call it from a browser, watch for CORS restrictions. If the API does not allow cross-origin requests, route the request through your backend instead of calling it directly from client-side code.

Can I use Minecraft Heads API in PHP?

Yes. PHP works well for server-side website integration, especially when you want to fetch head data and render it into a page or profile card. Use file_get_contents, cURL, or a PHP HTTP client, then decode the JSON response.

How do I troubleshoot a broken head image or empty response?

Start with the input and the raw response:

  1. Confirm the username or UUID is correct.
  2. Inspect the raw JSON for missing fields or an error message.
  3. Verify that the texture URL or image URL is still valid.
  4. Check whether your app is blocked by CORS or a network error.

Broken images often come from stale cache entries, invalid identifiers, or a temporary upstream failure. Empty responses usually mean the lookup failed or the API returned an error object instead of head data.

What is the difference between Minecraft Heads and the MCHeads website?

The Minecraft Heads website is the browsing interface where users search, preview, and copy heads manually. MCHeads is the service name commonly used for the backend or API layer that powers programmatic access. In other words, the website is for humans; the API is for code.

Can I use the API in a Minecraft plugin or website?

Yes. That is one of the main use cases. A plugin can fetch head data for menus, cosmetics, or player profiles, while a website can use it for a dashboard, profile card, or avatar display.

For plugin and website integration, keep these best practices in mind:

  • Cache responses by UUID when possible
  • Use username lookups only when needed
  • Respect the service’s rate limit
  • Handle missing players gracefully

Is the API free for personal or commercial use?

Check the current documentation and service terms. Some head APIs are free for personal use and may also allow commercial use, but that depends on the provider’s policy. Do not assume commercial rights without verifying the license or usage terms.

Does it support Bedrock players or only Java Edition?

Most Minecraft head and skin lookup services are centered on Java Edition players because they rely on Mojang UUID and username data. Bedrock support may be limited, indirect, or separate. If you need Bedrock support, confirm it in the current documentation before building around it.

How do I find a Minecraft UUID?

You can find a Minecraft UUID by using a Mojang profile lookup, a trusted UUID lookup tool, or your own account records. If you already have a username, many tools can resolve it to a UUID for Java Edition players. Store the UUID in your database so your app can keep working even if the player changes their username.

What are the best practices for caching API responses?

Cache by UUID when possible, because it is more stable than a username. Use a short-to-medium cache lifetime for head data, and refresh only when needed. If your app shows a rendered image or texture URL, store the response long enough to reduce repeated requests but not so long that you keep stale data forever.

Good caching habits include:

  • Cache successful lookups
  • Reuse cached data for repeated profile card or dashboard views
  • Respect server-provided cache headers if present
  • Log cache misses and API failures separately

FAQ

Is Minecraft Heads API the same as MCHeads?
They are often used interchangeably, but the website and the API are not the same thing. The website is the UI; the API is the programmatic service.

Is Minecraft Heads API official?
No. It is not an official Mojang service.

Do I need an API key to use Minecraft Heads API?
Maybe. Check the current documentation for API v2.0 access rules.

What does the API response look like?
Usually a JSON object with username, uuid, and texture or image fields.

Can I use Minecraft Heads API in JavaScript or PHP?
Yes. JavaScript fetch, Node.js, PHP, and browser-based integrations are all common use cases.

Does it have rate limits?
Likely yes, or at least some throttling rules. Confirm in the documentation.

What should I do first when something fails?
Check the username or UUID, inspect the raw response, confirm the current schema in the documentation, and then test again with a known-good player.

◀ All PostsAPI Docs