MC Icons API

A free, no-key-required JSON API for searching and fetching Minecraft texture metadata. Search/get responses always return JSON with URLs to the images, never a raw image file.

Base URL: https://mc-icons.com

GET /api/v1/search

Search icons by name. q matches anywhere in the display name (case-insensitive), e.g. q=oak log matches "Oak Log".

Param	Required	Description
`q`	Yes	Search text, e.g. `oak log`
`category`	No	Filter to one category, e.g. `Building Blocks`
`limit`	No	Max results, 1-100 (default 20)

GET https://mc-icons.com/api/v1/search?q=oak+log

{
  "query": "oak log",
  "count": 1,
  "results": [
    {
      "id": "oak_log",
      "displayName": "Oak Log",
      "category": "Building Blocks",
      "type": "block",
      "thumbnailUrl": "https://mc-icons.com/thumbs/oak_log.png",
      "fullUrl": "https://mc-icons.com/full/oak_log.png",
      "pageUrl": "https://mc-icons.com/icon/oak_log"
    }
  ]
}

GET /api/v1/icon/:id

Get a single icon by its exact id (the same id used in /icon/:id page URLs).

GET https://mc-icons.com/api/v1/icon/oak_log

{
  "id": "oak_log",
  "displayName": "Oak Log",
  "category": "Building Blocks",
  "type": "block",
  "thumbnailUrl": "https://mc-icons.com/thumbs/oak_log.png",
  "fullUrl": "https://mc-icons.com/full/oak_log.png",
  "pageUrl": "https://mc-icons.com/icon/oak_log"
}

Returns 404 with {"error": "..."} if the id doesn't exist.

GET /api/v1/categories

List every category with how many icons it contains.

GET https://mc-icons.com/api/v1/categories

[
  {
    "name": "Building Blocks",
    "count": 571
  },
  {
    "name": "Miscellaneous",
    "count": 434
  }
]

Downloading an image

Once you have an id, download the actual image directly - these return the image bytes, not JSON:

GET https://mc-icons.com/download/oak_log/full        → PNG, 512×512
GET https://mc-icons.com/download/oak_log/thumb       → PNG, 128×128
GET https://mc-icons.com/download/oak_log/full/webp   → WEBP, 512×512
GET https://mc-icons.com/download/oak_log/full/jpg    → JPG, 512×512 (transparency flattened to white)

Supported formats: png (default), jpg, jpeg, webp.