{"openapi":"3.1.0","info":{"title":"Pugtools Minecraft API","version":"1.0.0","description":"Read-only normalized Minecraft Java data, calculations, asset metadata, and configurable player-profile references. Pugtools is not an official Minecraft service and is not affiliated with Mojang or Microsoft.","contact":{"url":"https://pugtools.com/about/"},"license":{"name":"Pugtools API terms","identifier":"LicenseRef-Pugtools-API-Terms"}},"servers":[{"url":"https://api.pugtools.com","description":"Production"},{"url":"http://localhost:8787","description":"Local Wrangler"}],"tags":[{"name":"System"},{"name":"Minecraft data"},{"name":"Assets"},{"name":"Players"}],"paths":{"/v1/health":{"get":{"operationId":"getHealth","tags":["System"],"summary":"Check service and bundled catalog health.","responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/versions":{"get":{"operationId":"listVersions","tags":["Minecraft data"],"summary":"List Minecraft dataset versions available from this Worker.","description":"Lists every published version newest first, plus the immutable version each alias currently points at. An alias target is null when nothing is published for it.","responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"$ref":"#/components/schemas/Versions"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/search":{"get":{"operationId":"searchMinecraft","tags":["Minecraft data"],"summary":"Resolve friendly Minecraft terms deterministically.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/blocks/{id}":{"get":{"operationId":"getBlock","tags":["Minecraft data"],"summary":"Retrieve normalized block model and texture-reference metadata.","parameters":[{"name":"id","in":"path","required":true,"description":"Namespaced or local Minecraft identifier.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/items/{id}":{"get":{"operationId":"getItem","tags":["Minecraft data"],"summary":"Retrieve normalized item model and texture-reference metadata.","parameters":[{"name":"id","in":"path","required":true,"description":"Namespaced or local Minecraft identifier.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entities/{id}":{"get":{"operationId":"getEntity","tags":["Minecraft data"],"summary":"Retrieve normalized entity gameplay and renderer metadata.","parameters":[{"name":"id","in":"path","required":true,"description":"Namespaced or local Minecraft identifier.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/recipes/{id}":{"get":{"operationId":"getRecipe","tags":["Minecraft data"],"summary":"Retrieve crafting recipes that produce the requested item.","parameters":[{"name":"id","in":"path","required":true,"description":"Namespaced or local Minecraft identifier.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/trades/{profession}":{"get":{"operationId":"getVillagerTrades","tags":["Minecraft data"],"summary":"Retrieve resolved trade pools for a villager profession.","parameters":[{"name":"profession","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/ores/{id}":{"get":{"operationId":"getOreDistribution","tags":["Minecraft data"],"summary":"Retrieve source-derived ore placement curves and contexts.","parameters":[{"name":"id","in":"path","required":true,"description":"Namespaced or local Minecraft identifier.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/assets/search":{"get":{"operationId":"findMinecraftAsset","tags":["Assets"],"summary":"Search block, item, and entity asset metadata.","description":"Returns identifiers and metadata only. It never returns bulk vanilla asset files.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/RestrictedContent"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/assets/{id}":{"get":{"operationId":"getMinecraftAssetMetadata","tags":["Assets"],"summary":"Retrieve metadata for one Minecraft block, item, or entity asset.","description":"Texture and model fields are resource identifiers, not file download URLs.","parameters":[{"name":"id","in":"path","required":true,"description":"Namespaced or local Minecraft identifier.","schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"edition","in":"query","schema":{"type":"string","enum":["java"]}},{"name":"version","in":"query","description":"Published mc-datahub version id, or an alias. Use latest for the newest stable release and latest-snapshot for the newest snapshot. Omitting this parameter is the same as latest. Responses for an exact version id are immutable and cached for longer than alias responses.","schema":{"type":"string","maxLength":64,"examples":["latest","latest-snapshot"]}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/players/{usernameOrUuid}":{"get":{"operationId":"getPlayerProfile","tags":["Players"],"summary":"Retrieve a Minecraft Java profile and current upstream skin reference.","description":"This configurable upstream operation may return 503 until Pugtools has the required Java Game Service API access.","parameters":[{"name":"usernameOrUuid","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":36}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":["object","null"]},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/BadRequest"},"503":{"$ref":"#/components/responses/BadRequest"},"504":{"$ref":"#/components/responses/BadRequest"}}}},"/v1/players/{usernameOrUuid}/skin":{"get":{"operationId":"getPlayerSkinReference","tags":["Players"],"summary":"Retrieve the current Mojang-hosted skin reference for a Minecraft Java player.","description":"This configurable upstream operation may return 503 until Pugtools has the required Java Game Service API access.","parameters":[{"name":"usernameOrUuid","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":36}}],"responses":{"200":{"description":"Successful normalized response.","content":{"application/json":{"schema":{"type":"object","required":["ok","requestId","schemaVersion","minecraftVersion","data","warnings","meta","provenance"],"properties":{"ok":{"const":true},"requestId":{"type":"string","format":"uuid"},"schemaVersion":{"const":"1"},"minecraftVersion":{"type":"string","description":"Resolved Minecraft Java dataset version for this response."},"data":{"type":["object","null"]},"warnings":{"type":"array","items":{"type":"string"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"provenance":{"$ref":"#/components/schemas/ResponseProvenance"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/BadRequest"},"503":{"$ref":"#/components/responses/BadRequest"},"504":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"ResponseMeta":{"type":"object","required":["edition","provider","canonicalUrl","contentClass"],"properties":{"edition":{"const":"java"},"provider":{"enum":["pugtools","mojang"]},"canonicalUrl":{"type":"string","format":"uri"},"contentClass":{"enum":["DATA","UPSTREAM_REFERENCE","USER_PROVIDED_ASSET","PUGTOOLS_GENERATED","RESTRICTED_GAME_ASSET"]}}},"ResponseProvenance":{"type":"object","description":"Where the bundled Minecraft catalog came from.","required":["source","sourceCommit","generatedAt"],"properties":{"source":{"const":"mc-datahub"},"sourceCommit":{"type":"string","description":"Short git commit that generated the bundled catalog."},"generatedAt":{"type":"string","format":"date-time"}}},"Versions":{"type":"object","required":["versions","aliases"],"properties":{"versions":{"type":"array","description":"Published dataset versions, newest first.","items":{"type":"object","required":["id","channel"],"properties":{"id":{"type":"string","description":"Immutable version id, for example 26.3-snapshot-9."},"channel":{"enum":["release","snapshot"]}}}},"aliases":{"type":"object","description":"Immutable version each alias resolves to right now, or null when the alias has no target.","required":["latest","latest-snapshot"],"properties":{"latest":{"type":["string","null"]},"latest-snapshot":{"type":["string","null"]}}}}},"Error":{"type":"object","required":["ok","requestId","error"],"properties":{"ok":{"const":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","NOT_FOUND","PLAYER_LOOKUPS_DISABLED","RATE_LIMITED","RESTRICTED_CONTENT","UNSUPPORTED_EDITION","UNSUPPORTED_VERSION","UPSTREAM_ERROR","UPSTREAM_TIMEOUT"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}},"responses":{"BadRequest":{"description":"Input failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested record was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"The request rate limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RestrictedContent":{"description":"The request asks for restricted or bulk vanilla game assets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}