Minecraft REST API

Base URL: https://api.pugtools.com. The API is read-only, uses JSON, and currently supports normalized Java Edition data.

Quick examples

curl "https://api.pugtools.com/v1/search?q=diamond%20ore"
curl "https://api.pugtools.com/v1/blocks/minecraft:diamond_ore"
curl "https://api.pugtools.com/v1/recipes/piston"
curl "https://api.pugtools.com/v1/trades/librarian"

Endpoints

• GET /v1/health
• GET /v1/versions
• GET /v1/search?q=
• GET /v1/blocks/:id
• GET /v1/items/:id
• GET /v1/entities/:id
• GET /v1/recipes/:id
• GET /v1/trades/:profession
• GET /v1/ores/:ore
• GET /v1/assets/search?q=
• GET /v1/assets/:id
• GET /v1/players/:usernameOrUuid
• GET /v1/players/:usernameOrUuid/skin

Response envelope

Every successful response uses the same envelope. The resolved dataset version is always explicit, warnings is always present and may be empty, and provenance records the catalog commit the data was generated from.

{
  "ok": true,
  "requestId": "6f1c0f0e-6a1a-4c2a-9a1b-2f9b0c5f7d21",
  "schemaVersion": "1",
  "minecraftVersion": "26.3-snapshot-9",
  "data": { "id": "minecraft:diamond_ore", "type": "block" },
  "warnings": [],
  "meta": {
    "edition": "java",
    "provider": "pugtools",
    "canonicalUrl": "https://pugtools.com/tools/assets/?q=Diamond%20Ore",
    "contentClass": "DATA"
  },
  "provenance": {
    "source": "mc-datahub",
    "sourceCommit": "954aa1b3",
    "generatedAt": "2026-08-14T22:08:55.815Z"
  }
}

Dataset versions

Every data endpoint accepts an optional version parameter. Pass an exact published version id, latest for the newest stable release, or latest-snapshot for the newest snapshot. Leaving it out is the same as latest. The response always reports the resolved immutable id in minecraftVersion, never the alias, and adds a warning when an alias had to fall back to a snapshot. Responses for an exact version id are immutable and cached for a day, while alias responses are cached for a few minutes so a newly published dataset shows up quickly.

curl "https://api.pugtools.com/v1/versions"
curl "https://api.pugtools.com/v1/blocks/minecraft:diamond_ore?version=latest-snapshot"

The data payload of /v1/versions lists every published version, newest first, with the id each alias points at right now. An alias is null when nothing is published for it.

{
  "versions": [{ "id": "26.3-snapshot-9", "channel": "snapshot" }],
  "aliases": {
    "latest": "26.3-snapshot-9",
    "latest-snapshot": "26.3-snapshot-9"
  }
}

Asset responses are metadata

Model and texture fields are Minecraft resource identifiers. The API does not expose a filesystem browser, raw vanilla file route, bulk archive, or arbitrary URL proxy. Requests for bulk vanilla assets are rejected by the shared service.

Errors

Errors use a stable code and message. The body repeats the X-Request-Id header value as requestId so a failure can be reported without the response headers.

{
  "ok": false,
  "requestId": "6f1c0f0e-6a1a-4c2a-9a1b-2f9b0c5f7d21",
  "error": {
    "code": "NOT_FOUND",
    "message": "No block was found for minecraft:not_a_real_block."
  }
}

Validation errors return 400, missing records 404, restricted content 403, rate limits 429, and configurable or upstream player failures 502 to 504.

Complete specification

Use the OpenAPI 3.1 document for schemas and client generation. Service policies are on the terms and policies page.