{"openapi":"3.1.0","info":{"title":"HeadDB REST API","version":"1.0.0","description":"Browse the public Minecraft head catalog and submit additions. The v1 API uses stable numeric head IDs.","contact":{"url":"https://headdb.net"},"license":{"name":"GPL-3.0","url":"https://github.com/BitworksMC/HeadDB/blob/master/LICENSE"}},"servers":[{"url":"https://headdb.net","description":"Production"}],"tags":[{"name":"Heads","description":"Published head records and images"},{"name":"Taxonomy","description":"Categories and tags"},{"name":"Catalog","description":"Bulk and synchronization resources"},{"name":"Submissions","description":"Authenticated community submissions"}],"paths":{"/api/v1/heads":{"get":{"tags":["Heads"],"operationId":"listHeads","summary":"Search and list published heads","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Comma-separated tag slugs; all must match.","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","category"],"default":"id"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":12,"maximum":120,"default":48}}],"responses":{"200":{"description":"A page of heads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeadPage"}}}}}}},"/api/v1/heads/{id}":{"get":{"tags":["Heads"],"operationId":"getHead","summary":"Get one head by numeric ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Published head","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Head"}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"The stable ID belongs to a removed head."}}}},"/api/v1/heads/{id}/image":{"get":{"tags":["Heads"],"operationId":"getHeadImage","summary":"Render a cached square PNG preview","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"size","in":"query","schema":{"type":"integer","minimum":32,"maximum":512,"default":144}}],"responses":{"200":{"description":"PNG preview","content":{"image/png":{}}}}}},"/api/v1/textures/{hash}":{"get":{"tags":["Heads"],"operationId":"getUploadedTexture","summary":"Get an immutable HeadDB-hosted texture PNG","parameters":[{"name":"hash","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"Canonical 64×64 head texture","content":{"image/png":{}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/categories":{"get":{"tags":["Taxonomy"],"operationId":"listCategories","summary":"List categories and published counts","responses":{"200":{"description":"Category list"}}}},"/api/v1/tags":{"get":{"tags":["Taxonomy"],"operationId":"listTags","summary":"Search tags and published counts","responses":{"200":{"description":"Tag list"}}}},"/api/v1/catalog/manifest":{"get":{"tags":["Catalog"],"operationId":"getCatalogManifest","summary":"Get current revision and bulk artifact integrity","responses":{"200":{"description":"Catalog manifest"}}}},"/api/v1/legacy/heads.json":{"get":{"tags":["Catalog"],"operationId":"downloadLegacyCatalog","summary":"Download the HeadDB 6.0.3-compatible JSON array","responses":{"200":{"description":"Legacy head array"}}}},"/api/v1/submissions":{"post":{"tags":["Submissions"],"operationId":"createSubmission","summary":"Submit a proposed head","security":[{"cookieSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewSubmission"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/NewMultipartSubmission"}}}},"responses":{"201":{"description":"Submission accepted for review"},"401":{"description":"Sign-in required"},"409":{"description":"Texture already exists"}}}}},"components":{"securitySchemes":{"cookieSession":{"type":"apiKey","in":"cookie","name":"better-auth.session_token"}},"responses":{"NotFound":{"description":"No record exists for this ID"}},"schemas":{"Head":{"type":"object","required":["id","name","texture","textureSource","textureUrl","textureValue","category","tags"],"properties":{"id":{"type":"integer","examples":[1]},"name":{"type":"string","examples":["Melon"]},"texture":{"type":"string","pattern":"^[0-9a-f]{55,64}$"},"textureSource":{"type":"string","enum":["mojang","headdb"]},"textureUrl":{"type":"string","format":"uri"},"textureValue":{"type":"string","description":"Base64-encoded Minecraft textures property value."},"category":{"$ref":"#/components/schemas/TaxonomyItem"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyItem"}}}},"TaxonomyItem":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"HeadPage":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Head"}},"pagination":{"type":"object"}}},"NewSubmission":{"type":"object","required":["name","texture","category"],"properties":{"name":{"type":"string","minLength":2,"maxLength":110},"texture":{"type":"string","description":"A Mojang hash, textures.minecraft.net URL, or Base64 texture value."},"category":{"type":"string"},"tags":{"type":"array","maxItems":12,"items":{"type":"string"}},"notes":{"type":"string","maxLength":1000}}},"NewMultipartSubmission":{"type":"object","required":["name","category"],"oneOf":[{"required":["skin"]},{"required":["texture"]}],"properties":{"name":{"type":"string","minLength":2,"maxLength":110},"skin":{"type":"string","format":"binary","description":"A standard 64×64 or legacy 64×32 Minecraft skin PNG, at most 256 KiB."},"texture":{"type":"string","description":"A Mojang hash, textures.minecraft.net URL, or Base64 texture value."},"category":{"type":"string"},"tags":{"type":"string","description":"Comma-separated tag names, up to 12."},"notes":{"type":"string","maxLength":1000}}}}}}