API

Read the catalogue from code

A small read-only JSON API over the same data this site runs on. No key, no signup, no CORS restrictions.

Base URLhttps://heads.kal.pe/api

GET/api/heads

A paginated list of heads. This is the endpoint behind the grid on the homepage.

Query parameters

page: Page number. Default 1.
limit: Results per page. Default 50.
category: Filter to one category, e.g. monsters, food, blocks.
search: Match against name, display name and tags, ranked by relevance.
sort: newest, oldest, popular, clicks, copies or downloads.

Example response

{
  "heads": [
    {
      "_id": "6a80c75c6050a7627e244f2d",
      "name": "226acf32-9ee5-4ac3-bbe3-8f7d5c50d6d6",
      "displayName": "Creeper",
      "category": "monsters",
      "image": "https://mc-heads.net/avatar/2070c589…/128",
      "command": "/give @p minecraft:player_head{…}",
      "textureHash": "2070c589…",
      "uuid": "226acf32-9ee5-4ac3-bbe3-8f7d5c50d6d6",
      "tags": ["monsters", "mob"]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 93215,
    "totalPages": 1865,
    "hasNext": true,
    "hasPrev": false
  }
}

GET/api/heads/:id

One head by its id, with the same fields as a list entry.

GET/api/heads/random

A single random head. Useful for a head-of-the-day, or for testing.

POST/api/heads/:id/track

Increment a counter on a head. This is what powers the popularity sorts.

Request body

{ "type": "click" | "download" | "copy" | "view" }

GET/api/name-to-uuid/:name

Resolve a Minecraft username to its UUID, via Mojang.

GET/api/uuid-to-name/:uuid

Resolve a UUID back to the current username on that account.

Rate limits

100 requests per minute and 1,000 per hour, per IP. Go over and you'll get a 429; wait for the window to roll and continue.

Please cache

The catalogue changes rarely. If you're building a browser or a bot, cache responses rather than refetching per page view. It keeps the limits generous for everyone.

Images

The image field points at mc-heads.net, not at us. Use textureHash if you'd rather render heads yourself.