Getting started
Choose the quickest path for installing HeadDB, browsing heads, or using the API.
Run HeadDB on a server
Server owners should start with Install HeadDB. Choose the
modern Paper jar or the legacy Bukkit-compatible jar, place exactly one in the
server's plugins/ directory, and perform a full restart. Once the catalog is
ready, /hdb opens the menu.
The commands and permissions guide covers player access, search filters, and direct give commands. The configuration guide covers catalog refreshes, economy support, menus, and custom categories.
Browse the catalog
Open Browse to search by name or numeric ID, restrict results to a category or tag, and choose an ordering. The complete filter state is stored in the URL, so a filtered view can be bookmarked or shared.
Each result provides shortcuts for its numeric ID and detail page. The detail page can also copy the /hdb give command, texture hash, and permanent link.
Signed-in users can favorite a head, add it to a public/private collection,
export collections as YAML, and report bad metadata.
Make an API request
Public reads do not require an API key.
curl "https://headdb.net/api/v1/heads?q=dragon&limit=20"Responses use JSON. Paginated head responses contain items and pagination
objects. Invalid requests use application/problem+json with a stable type,
status, and human-readable detail.
Stability
The supported API prefix is /api/v1. Additive response fields may appear without a version change. Removing or changing a field's meaning requires a new major API version.