◀ Back to Blog

Minecraft Heads API Documentation: Endpoints, Examples

What is the Minecraft Heads API?

The Minecraft Heads API is a third-party REST API from Minecraft-Heads.com that lets developers browse, search, and retrieve Minecraft head entries programmatically. It is useful for head browser pages, catalog views, Minecraft plugins, Discord bots, and websites that need head metadata and texture data without scraping the site.

This is not an official Mojang or Minecraft API. It is community-maintained, so treat it as external infrastructure with versioning, changelog updates, and possible breaking changes over time.

Is there official Minecraft Heads API documentation?

Yes, Minecraft-Heads.com provides developer documentation for the API. This article summarizes the practical parts of that documentation: base URL, endpoints, query parameters, path parameters, JSON response format, HTTP status codes, rate limiting, and examples in JavaScript, PHP, and cURL.

What data does the API return?

A typical head record includes a head ID, name, category, tags, texture data, and a base64 texture value. Some responses may also include preview URLs, slugs, or other metadata used by the site.

The head ID identifies a specific record. The base64 texture value is the encoded payload Minecraft uses for the head texture; it is not the same thing as the numeric ID. Categories and tags help organize heads for search filters, catalog pages, and menus.

Base URL, authentication, and API v2.0

The base URL for the Minecraft Heads API is versioned. In practice, requests are made against the API v2.0 path on Minecraft-Heads.com, for example:

https://minecraft-heads.com/api/v2.0/

The API is publicly readable, so standard requests do not require an API key or other authentication. If the service ever introduces authentication, it should be documented in the developer documentation and sent through an HTTP header such as Authorization, not embedded in the URL.

API v2.0 matters because versioning helps isolate breaking changes. If you are migrating from an older version, review the changelog before switching production traffic.

Endpoints, path parameters, and query parameters

The API is typically organized around endpoints for listing heads, searching heads, retrieving a head by ID, and browsing categories or tags.

Common request patterns include:

  • List heads: returns a paginated collection of Minecraft heads
  • Search heads: filters by name, tag, category, or other supported search filters
  • Get head by ID: returns one head record using a path parameter
  • Browse categories and tags: returns taxonomy data for navigation or filtering

Path parameters identify a specific resource, such as a head ID. Query parameters control pagination, search terms, sort order, and filters.

Example patterns:

GET /api/v2.0/heads
GET /api/v2.0/heads?search=creeper
GET /api/v2.0/heads/{headId}
GET /api/v2.0/categories
GET /api/v2.0/tags

If the API uses slightly different endpoint names in the current developer documentation, follow the documented paths exactly. The important part is the structure: list, search, single-record, and taxonomy endpoints.

How do I get a list of Minecraft heads?

Use the list endpoint with pagination. A typical request returns a page of head objects plus metadata such as the current page, page size, and total count.

curl -sS "https://minecraft-heads.com/api/v2.0/heads?page=1&perPage=20" \
  -H "Accept: application/json"

Pagination is important for catalog pages and browser views because it prevents large responses and makes infinite scroll or page navigation easier.

How do I search Minecraft heads by name or tag?

Use search filters in the query string. Depending on the API version, you may search by a name term, a tag, a category, or a combination of filters.

curl -sS "https://minecraft-heads.com/api/v2.0/heads?search=creeper&tag=mobs" \
  -H "Accept: application/json"

For a head browser or catalog page, search should be debounced on the frontend and cached on the backend when possible. That keeps the UI responsive and reduces unnecessary requests.

How do I retrieve a Minecraft head by ID?

Use the single-record endpoint with the head ID as a path parameter.

curl -sS "https://minecraft-heads.com/api/v2.0/heads/1234" \
  -H "Accept: application/json"

If the ID is invalid or does not exist, the API should return an HTTP status code such as 404. Your code should handle that case separately from network failures.

What does the JSON response look like?

A list response usually contains an array of heads and pagination metadata:

{
  "data": [
    {
      "id": 1234,
      "name": "Creeper Head",
      "slug": "creeper-head",
      "category": "Mobs",
      "tags": ["creeper", "mob"],
      "textures": {
        "value": "eyJ0ZXh0dXJlcyI6...",
        "url": "https://textures.minecraft.net/texture/..."
      },
      "previewUrl": "https://minecraft-heads.com/.../preview.png"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}

A single-head response usually returns one object:

{
  "data": {
    "id": 1234,
    "name": "Creeper Head",
    "category": "Mobs",
    "tags": ["creeper", "mob"],
    "textures": {
      "value": "eyJ0ZXh0dXJlcyI6...",
      "url": "https://textures.minecraft.net/texture/..."
    },
    "previewUrl": "https://minecraft-heads.com/.../preview.png"
  }
}

Use textures.value when you need the base64 texture payload, and use textures.url when you need a renderable texture source. If your app only needs display data, the preview URL may be enough.

What parameters does the API support?

The exact parameter set depends on the endpoint, but the common ones are:

  • page for pagination
  • perPage or similar page-size controls
  • search for name matching
  • tag or tags for tag filtering
  • category for category filtering

Use query parameters for filtering and path parameters for exact resource lookup. If a parameter is not documented, do not assume it exists.

What error codes can the API return?

The API can return standard HTTP status codes. Common examples include:

  • 200 success
  • 400 invalid request or malformed parameters
  • 401 unauthorized, if authentication is ever required
  • 403 forbidden or access denied
  • 404 invalid head ID or missing record
  • 429 rate limited
  • 500 server error

When you receive a non-200 response, inspect the status code and response body before retrying.

What are the rate limits for the API?

The documentation should be checked for the current rate limits, because limits can change with versioning or infrastructure updates. If the API returns rate-limit headers such as Retry-After or X-RateLimit-*, use them to decide when to retry.

To avoid hitting rate limits:

  • cache list and search responses
  • debounce search input in JavaScript
  • avoid polling on short intervals
  • back off exponentially after 429 responses

How do I use the API in JavaScript?

You can use fetch in the browser or Node.js, or axios if you prefer a library.

fetch example

async function getHeads() {
  const res = await fetch("https://minecraft-heads.com/api/v2.0/heads?search=creeper", {
    headers: { Accept: "application/json" }
  });

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }

  const data = await res.json();
  return data;
}

axios example

import axios from "axios";

async function searchHeads() {
  try {
    const res = await axios.get("https://minecraft-heads.com/api/v2.0/heads", {
      params: { search: "creeper" },
      headers: { Accept: "application/json" }
    });
    console.log(res.data);
  } catch (err) {
    console.error(err.response?.status, err.response?.data || err.message);
  }
}

If you are using this in a website, remember that CORS may block direct browser requests. In that case, proxy the request through your backend.

How do I use the API in PHP?

PHP can call the API with cURL and decode the JSON response.

<?php
$url = 'https://minecraft-heads.com/api/v2.0/heads?search=creeper';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Accept: application/json']
]);
$body = curl_exec($ch);
if ($body === false) {
    die(curl_error($ch));
}
$data = json_decode($body, true);
curl_close($ch);

In PHP, check both the HTTP status code and the decoded JSON before rendering results.

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

Yes. A Minecraft plugin can call the API server-side, cache responses, and use the data in commands, GUIs, or menus. A website can use the API too, but browser-based calls may require a backend proxy because of CORS.

For a head browser or catalog page, the API is a good fit if you need:

  • searchable head listings
  • category and tag filters
  • preview images or texture metadata
  • pagination for large result sets

How do categories and tags work in the API?

Categories are broad groupings, such as mobs or themed collections. Tags are more specific labels that help with search filters and cross-listing. A single head can belong to one category and have multiple tags.

Use categories for navigation and tags for finer filtering. For example, a catalog page might let users browse by category first and then narrow results by tag.

How do I handle empty results or invalid IDs?

Treat empty results as a normal outcome when a search is too narrow. If the API returns a valid JSON response with an empty data array, show a no-results message instead of an error.

If the head ID is invalid, expect a 404 or similar HTTP status code. If the response body is malformed or the endpoint returns HTML instead of JSON, check the base URL, versioned path, and request headers.

What changed in API v2.0?

API v2.0 introduced a versioned structure and more predictable JSON responses. That usually means better endpoint organization, clearer parameter handling, and fewer surprises for developers building against the REST API.

Because versioning can include breaking changes, review the changelog before upgrading from an older version. Test list, search, and single-head requests before you switch production traffic.

FAQ

Do I need an API key to use Minecraft Heads API?
No, standard read access does not require an API key.

What is the base URL for the Minecraft Heads API?
The API is versioned under the Minecraft-Heads.com domain, with requests made against the /api/v2.0/ path.

What is the JSON response structure?
Most responses wrap results in a data field and may include pagination metadata in meta.

Can I use it in Node.js?
Yes. fetch and axios both work well in Node.js.

Is the API suitable for a head browser or catalog page?
Yes. Pagination, search filters, categories, and tags make it a strong fit for that use case.

Conclusion

Minecraft-Heads.com provides a practical REST API for developers who need Minecraft heads in a website, plugin, or internal tool. If you follow the documented endpoints, respect rate limiting, and handle empty results and invalid IDs cleanly, you can build a reliable integration around Minecraft Heads data without scraping the site.

◀ All PostsAPI Docs