API reference

The base URL is https://headdb.net/api/v1. Public catalog reads need no authentication. The machine-readable OpenAPI 3.1 document is generated by the same application.

List heads

GET /api/v1/heads

Parameter	Meaning
q	Name search or exact numeric ID
category	Category slug
tags	Comma-separated tag slugs; all supplied tags must match
page	Page number, beginning at 1
limit	Results per page, 12–120
sort	id, name, or category
direction	asc or desc

curl "https://headdb.net/api/v1/heads?category=alphabet&tag=dark&page=2"

Get one head

GET /api/v1/heads/{id} returns one published head, including its category, tags, texture hash, textureSource, direct textureUrl, and Base64 textureValue. Removed or unknown IDs return 404.

GET /api/v1/heads/{id}/image?size=128 returns a rendered PNG face. Supported sizes are 32–512 pixels. The service fetches the canonical Minecraft texture and overlays its hat layer.

GET /api/v1/textures/{hash} serves a HeadDB-uploaded canonical texture PNG. These content-addressed responses are public, CORS-enabled, and cached as immutable for one year.

Taxonomy and revision

• GET /api/v1/categories lists active categories and published-head counts.
• GET /api/v1/tags lists tags and published-head counts.
• GET /api/v1/catalog/manifest returns catalog counts and the current revision.

Plugin compatibility snapshot

GET /api/v1/legacy/heads.json returns the compact array expected by HeadDB 6.x. It preserves the fields id, name, texture, category, and tags, supports gzip through the web server, and publishes an ETag for efficient refreshes. Because HeadDB 6.x hard-codes Mojang's texture host, this compatibility feed includes Mojang-backed heads only; first-party uploads are available through the v1 API.

New integrations should prefer paginated /api/v1/heads; the snapshot exists for the plugin's atomic full-database refresh.

Errors

Errors follow RFC 9457 problem details:

{
  "type": "https://headdb.net/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "limit must be between 1 and 100"
}