API reference
Public catalog endpoints, filters, response shapes, caching, and errors.
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 exact tag slugs |
ids | Comma-separated stable head IDs |
match | all or any across supplied filters |
page | Page number, beginning at 1 |
limit | Results per page, 12–120 |
sort | id, name, category, or updated |
direction | asc or desc |
curl "https://headdb.net/api/v1/heads?category=alphabet&tags=punctuation-mark&page=2"tags does not perform a partial-text search. Use GET /api/v1/tags?q=dark
to discover matching tag slugs, or use the heads endpoint's q parameter to
search head names and tag names.
Get one head
GET /api/v1/heads/{id} returns one published head, including its category,
tags, timestamps, texture hash, textureSource, direct textureUrl, and Base64
textureValue. Removed IDs return 410; a merged ID returns 308 to its
canonical target; 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/categorieslists active categories and published-head counts.GET /api/v1/tagslists tags and published-head counts.GET /api/v1/catalog/manifestreturns catalog counts and the current revision.
Catalog synchronization
Plugins should download GET /api/v1/catalog/snapshot once and save the response's X-Catalog-Revision header with their local catalog. The snapshot includes both Mojang and HeadDB-hosted textures.
Subsequent refreshes use:
GET /api/v1/catalog/changes?sinceRevision=42&limit=1000Each change is either an upsert with the complete head record or a remove with its stable head ID. Follow nextCursor while hasMore is true. Apply the pages in order and save toRevision only after the final page has been committed. This catches additions, edits, category or tag changes, and removals without downloading the complete catalog again.
For simple append-only consumers, GET /api/v1/catalog/additions?afterId=101001 returns published heads with greater IDs, the current latestId, and a nextAfterId when another page exists. This is convenient, but it cannot report changes to an existing ID or a removed head.
Legacy plugin compatibility
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 use the modern snapshot and revision change feed. The legacy snapshot remains available for older HeadDB builds.
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"
}