BlocksItems API

Free, comprehensive REST API for Minecraft items, blocks, recipes, and more. Data from vanilla and 515+ mods across versions 1.16.5, 1.18.2, 1.20.1, and 1.21.1.

107,645Items
68,663Blocks
2,319Mods

Base URL:

/api/v1

All responses return JSON with a consistent structure. List endpoints include pagination metadata. The OpenAPI spec is also available.

Quick Start
curl '/api/v1/items?search=diamond&limit=5'
Response Format
{
  "data": [...],
  "page": 1,
  "limit": 50,
  "total": 59435,
  "pages": 1189,
  "status": "ok"
}

Authentication

No API key is required for basic usage. All endpoints are publicly accessible.

For higher rate limits, you can use an API key via the X-API-Key header or api_key query parameter.

X-API-Key header optional

API key for higher rate limits

api_key query optional

Alternative: pass API key as query parameter

With API Key
curl -H 'X-API-Key: your_key_here' \
  '/api/v1/items'

# Or as query parameter
curl '/api/v1/items?api_key=your_key_here'

Rate Limits

Rate limits are applied per IP address or per API key. The response includes rate limit headers.

Free Tier

6,000 req/min

No API key required

API Key

Higher limits

Contact [email protected]

Rate Limit Headers
X-RateLimit-Limit: 6000
X-RateLimit-Remaining: 5999
X-RateLimit-Reset: 1700000060

Pagination

List endpoints support pagination via page and limit query parameters. The response includes total count and total pages.

page integer default: 1

Page number (starts at 1)

limit integer default: 50

Items per page (max 100 for most endpoints)

Paginated Response
{
  "data": [...],
  "page": 2,
  "limit": 50,
  "total": 59435,
  "pages": 1189,
  "status": "ok"
}
GET /api/v1/items

List Items

Returns a paginated list of items with optional filtering by namespace, mod, rarity, tag, or search term.

Parameters

namespace string optional

Filter by namespace (e.g., minecraft, create)

mod_id string optional

Filter by mod ID

search string optional

Search in display name and full_id

rarity string optional

Filter by rarity

commonuncommonrareepic
tag string optional

Filter by tag (e.g., minecraft:tools)

page integer optional default: 1

Page number

limit integer optional default: 50

Items per page (1-100)

curl 'https://blocksitems.com/api/v1/items?search=diamond&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/items?search=diamond&limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/items', params={
    'search': 'diamond',
    'limit': 5,
})
print(resp.json())
Response
{
  "data": [
    {
      "id": "...",
      "full_id": "minecraft:diamond",
      "display_name": "Diamond",
      "rarity": "common",
      "max_stack_size": 64,
      "icon_url": "https://blocksitems.com/api/v1/images/abc123"
    }
  ],
  "page": 1,
  "limit": 5,
  "total": 42,
  "pages": 9,
  "status": "ok"
}
Try it
GET /api/v1/items/{full_id}

Get Item

Returns a single item by its full ID including all properties, tags, icon URL, and mod information.

Parameters

full_id string required

Full item ID (e.g., minecraft:diamond_sword)

curl 'https://blocksitems.com/api/v1/items/minecraft:diamond_sword'
const res = await fetch('https://blocksitems.com/api/v1/items/minecraft:diamond_sword');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/items/minecraft:diamond_sword')
print(resp.json())
Response
{
  "data": {
    "id": "...",
    "full_id": "minecraft:diamond_sword",
    "display_name": "Diamond Sword",
    "max_stack_size": 1,
    "max_damage": 1561,
    "is_damageable": true,
    "rarity": "common",
    "tags": ["minecraft:swords"]
  },
  "status": "ok"
}
Try it
GET /api/v1/items/lookup/{full_id}

Lookup Item

Returns a single item with optimized fields for material lists. Faster than Get Item, with optional model data.

Parameters

full_id string required

Full item ID (e.g., minecraft:diamond)

include_model boolean optional default: false

Include full model data in response

modpack string optional

Filter by modpack slug (e.g., atm10)

version string optional

Filter by modpack version (e.g., 1.21.1)

curl 'https://blocksitems.com/api/v1/items/lookup/minecraft:diamond'
const res = await fetch('https://blocksitems.com/api/v1/items/lookup/minecraft:diamond');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/items/lookup/minecraft:diamond')
print(resp.json())
Response
{
  "data": {
    "full_id": "minecraft:diamond",
    "display_name": "Diamond",
    "icon_url": "https://blocksitems.com/api/v1/images/abc123"
  },
  "found": true,
  "status": "ok"
}
Try it
POST /api/v1/items/lookup

Bulk Lookup Items

Returns multiple items by their full IDs in a single request. Accepts up to 500 item IDs.

Parameters

item_ids array required

Array of item IDs to look up (max 500)

include_model boolean optional default: false

Include full model data in response

modpack string optional

Filter by modpack slug

version string optional

Filter by modpack version

curl -X POST 'https://blocksitems.com/api/v1/items/lookup' \
  -H 'Content-Type: application/json' \
  -d '{"item_ids": ["minecraft:diamond", "minecraft:iron_ingot"]}'
const res = await fetch('https://blocksitems.com/api/v1/items/lookup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    item_ids: ['minecraft:diamond', 'minecraft:iron_ingot']
  })
});
const data = await res.json();
console.log(data);
import requests

resp = requests.post('https://blocksitems.com/api/v1/items/lookup', json={
    'item_ids': ['minecraft:diamond', 'minecraft:iron_ingot']
})
print(resp.json())
Response
{
  "data": {
    "minecraft:diamond": { "full_id": "minecraft:diamond", "display_name": "Diamond" },
    "minecraft:iron_ingot": { "full_id": "minecraft:iron_ingot", "display_name": "Iron Ingot" }
  },
  "found": 2,
  "not_found": [],
  "status": "ok"
}
GET /api/v1/items/by-mod/{mod_id}

Items by Mod

Returns a paginated list of all items for a specific mod.

Parameters

mod_id string required

Mod ID (e.g., minecraft, create, ae2)

page integer optional default: 1

Page number

limit integer optional default: 100

Items per page (1-100)

include_model boolean optional default: false

Include full model data

modpack string optional

Filter by modpack slug

version string optional

Filter by modpack version

curl 'https://blocksitems.com/api/v1/items/by-mod/create?limit=5'
const res = await fetch('https://blocksitems.com/api/v1/items/by-mod/create?limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/items/by-mod/create', params={'limit': 5})
print(resp.json())
Response
{
  "data": [
    { "full_id": "create:brass_ingot", "display_name": "Brass Ingot" }
  ],
  "page": 1,
  "limit": 5,
  "total": 245,
  "status": "ok"
}
Try it
GET /api/v1/blocks

List Blocks

Returns a paginated list of blocks with optional filtering by namespace, mod, tag, light emission, hardness, and waterloggable status.

Parameters

namespace string optional

Filter by namespace (e.g., minecraft, create)

mod_id string optional

Filter by mod ID

search string optional

Search in display name and full_id

tag string optional

Filter by tag (e.g., minecraft:mineable/pickaxe)

light_min integer optional default: -1

Minimum light emission (-1 to disable, 0-15)

light_max integer optional default: -1

Maximum light emission (-1 to disable, 0-15)

hardness_min float optional default: -1

Minimum destroy speed (-1 to disable)

hardness_max float optional default: -1

Maximum destroy speed (-1 to disable)

is_waterloggable string optional

Filter by waterloggable status

truefalse
page integer optional default: 1

Page number

limit integer optional default: 50

Blocks per page (1-100)

curl 'https://blocksitems.com/api/v1/blocks?search=stone&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/blocks?search=stone&limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/blocks', params={
    'search': 'stone',
    'limit': 5,
})
print(resp.json())
Response
{
  "data": [
    {
      "full_id": "minecraft:stone",
      "display_name": "Stone",
      "light_emission": 0,
      "destroy_speed": 1.5,
      "has_collision": true
    }
  ],
  "page": 1,
  "limit": 5,
  "total": 128,
  "status": "ok"
}
Try it
GET /api/v1/blocks/{full_id}

Get Block

Returns a single block by its full ID including all physical properties, tags, icon URL, and mod information.

Parameters

full_id string required

Full block ID (e.g., minecraft:stone)

curl 'https://blocksitems.com/api/v1/blocks/minecraft:stone'
const res = await fetch('https://blocksitems.com/api/v1/blocks/minecraft:stone');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/blocks/minecraft:stone')
print(resp.json())
Response
{
  "data": {
    "full_id": "minecraft:stone",
    "display_name": "Stone",
    "explosion_resistance": 6.0,
    "destroy_speed": 1.5,
    "light_emission": 0,
    "has_collision": true,
    "requires_correct_tool": true
  },
  "status": "ok"
}
Try it
GET /api/v1/blocks/lookup/{full_id}

Lookup Block

Returns a single block with optimized fields for material lists. Faster than Get Block, with optional model data.

Parameters

full_id string required

Full block ID (e.g., minecraft:stone)

include_model boolean optional default: false

Include full model data in response

modpack string optional

Filter by modpack slug

version string optional

Filter by modpack version

curl 'https://blocksitems.com/api/v1/blocks/lookup/minecraft:stone'
const res = await fetch('https://blocksitems.com/api/v1/blocks/lookup/minecraft:stone');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/blocks/lookup/minecraft:stone')
print(resp.json())
Response
{
  "data": {
    "full_id": "minecraft:stone",
    "display_name": "Stone",
    "namespace": "minecraft",
    "path": "stone",
    "icon_url": "https://blocksitems.com/api/v1/images/abc123",
    "icon_hash": "abc123",
    "primary_color": "#808080",
    "map_color_hex": "#9d8f7c",
    "light_emission": 0,
    "is_transparent": false
  },
  "found": true,
  "status": "ok"
}
Try it
POST /api/v1/blocks/lookup

Bulk Lookup Blocks

Returns multiple blocks by their full IDs in a single request. Accepts up to 500 block IDs.

Parameters

block_ids array required

Array of block IDs to look up (max 500)

include_model boolean optional default: false

Include full model data in response

modpack string optional

Filter by modpack slug

version string optional

Filter by modpack version

curl -X POST 'https://blocksitems.com/api/v1/blocks/lookup' \
  -H 'Content-Type: application/json' \
  -d '{"block_ids": ["minecraft:stone", "minecraft:dirt"]}'
const res = await fetch('https://blocksitems.com/api/v1/blocks/lookup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    block_ids: ['minecraft:stone', 'minecraft:dirt']
  })
});
const data = await res.json();
console.log(data);
import requests

resp = requests.post('https://blocksitems.com/api/v1/blocks/lookup', json={
    'block_ids': ['minecraft:stone', 'minecraft:dirt']
})
print(resp.json())
Response
{
  "data": {
    "minecraft:stone": {
      "full_id": "minecraft:stone",
      "display_name": "Stone",
      "namespace": "minecraft",
      "path": "stone",
      "icon_url": "https://blocksitems.com/api/v1/images/abc123",
      "icon_hash": "abc123",
      "primary_color": "#808080",
      "map_color_hex": "#9d8f7c",
      "light_emission": 0,
      "is_transparent": false
    },
    "minecraft:dirt": {
      "full_id": "minecraft:dirt",
      "display_name": "Dirt",
      "namespace": "minecraft",
      "path": "dirt",
      "icon_url": "https://blocksitems.com/api/v1/images/def456",
      "icon_hash": "def456",
      "primary_color": "#866043",
      "map_color_hex": "#976d4d",
      "light_emission": 0,
      "is_transparent": false
    }
  },
  "found": 2,
  "not_found": [],
  "status": "ok"
}
GET /api/v1/blocks/by-mod/{mod_id}

Blocks by Mod

Returns a paginated list of all blocks for a specific mod.

Parameters

mod_id string required

Mod ID (e.g., minecraft, create, ae2)

page integer optional default: 1

Page number

limit integer optional default: 100

Blocks per page (1-100)

include_model boolean optional default: false

Include full model data

modpack string optional

Filter by modpack slug

version string optional

Filter by modpack version

curl 'https://blocksitems.com/api/v1/blocks/by-mod/create?limit=5'
const res = await fetch('https://blocksitems.com/api/v1/blocks/by-mod/create?limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/blocks/by-mod/create', params={'limit': 5})
print(resp.json())
Response
{
  "data": [
    {
      "full_id": "create:brass_block",
      "display_name": "Block of Brass",
      "namespace": "create",
      "path": "brass_block",
      "icon_url": "https://blocksitems.com/api/v1/images/ghi789",
      "icon_hash": "ghi789",
      "primary_color": "#c8a44e",
      "map_color_hex": "#a7a7a7",
      "light_emission": 0,
      "is_transparent": false
    }
  ],
  "page": 1,
  "limit": 5,
  "total": 120,
  "status": "ok"
}
Try it
GET /api/v1/recipes

List Recipes

Returns a paginated list of recipes. Filter by result item, ingredient, recipe type, or namespace.

Parameters

item_id string optional

Filter by result item ID (e.g., minecraft:iron_ingot)

ingredient_id string optional

Filter by ingredient item ID

recipe_type string optional

Filter by recipe type (e.g., minecraft:crafting_shaped)

namespace string optional

Filter by namespace

page integer optional default: 1

Page number

limit integer optional default: 50

Recipes per page (1-100)

curl 'https://blocksitems.com/api/v1/recipes?item_id=minecraft:iron_ingot&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/recipes?item_id=minecraft:iron_ingot&limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/recipes', params={
    'item_id': 'minecraft:iron_ingot',
    'limit': 5,
})
print(resp.json())
Response
{
  "data": [
    {
      "id": "...",
      "recipe_id": "minecraft:iron_ingot_from_smelting_iron_ore",
      "type": "minecraft:smelting",
      "ingredients": [...],
      "result": { "item_id": "minecraft:iron_ingot", "count": 1 }
    }
  ],
  "page": 1,
  "limit": 5,
  "total": 3,
  "status": "ok"
}
Try it
GET /api/v1/recipes/{id}

Get Recipe

Returns a single recipe by its UUID, including ingredients, result, pattern, and cooking details.

Parameters

id string required

Recipe UUID

curl 'https://blocksitems.com/api/v1/recipes/{uuid}'
const res = await fetch('https://blocksitems.com/api/v1/recipes/{uuid}');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/recipes/{uuid}')
print(resp.json())
Response
{
  "data": {
    "id": "...",
    "type": "minecraft:crafting_shaped",
    "pattern": ["###", " | ", " | "],
    "ingredients": [...],
    "result": { "item_id": "minecraft:diamond_pickaxe", "count": 1 }
  },
  "status": "ok"
}
Try it
GET /api/v1/colors/search

Search by Color

Search for blocks by color similarity using OKLAB perceptual color space. Provide a hex color or RGB values.

Parameters

hex string optional

Hex color code (e.g., #FF5733 or FF5733)

r integer optional default: -1

Red component (0-255, -1 to disable)

g integer optional default: -1

Green component (0-255, -1 to disable)

b integer optional default: -1

Blue component (0-255, -1 to disable)

tolerance float optional default: 0.15

Color distance tolerance in OKLAB space (0.01-1.0, lower = stricter)

namespace string optional

Filter by namespace (e.g., minecraft for vanilla only)

page integer optional default: 1

Page number

limit integer optional default: 50

Results per page (1-200)

curl 'https://blocksitems.com/api/v1/colors/search?hex=%23FF5733&tolerance=0.15&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/colors/search?hex=%23FF5733&tolerance=0.15&limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/colors/search', params={
    'hex': '#FF5733',
    'tolerance': 0.15,
    'limit': 5,
})
print(resp.json())
Response
{
  "data": [
    {
      "full_id": "minecraft:red_terracotta",
      "display_name": "Red Terracotta",
      "color_hex": "#8E3C2E",
      "color_distance": 0.08
    }
  ],
  "search_color": "#FF5733",
  "page": 1,
  "total": 12,
  "status": "ok"
}
Try it
POST /api/v1/colors/gradient/linear

Linear Gradient

Generate a linear gradient of blocks between two colors. Returns blocks ordered by position in the gradient.

Parameters

color1 string required

First color (hex)

color2 string required

Second color (hex)

length integer required

Number of blocks in gradient (2-100)

namespace string optional

Filter by namespace (e.g., minecraft)

unique_blocks boolean optional default: false

Use each block only once

curl -X POST 'https://blocksitems.com/api/v1/colors/gradient/linear' \
  -H 'Content-Type: application/json' \
  -d '{"color1": "#FF0000", "color2": "#0000FF", "length": 10}'
const res = await fetch('https://blocksitems.com/api/v1/colors/gradient/linear', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    color1: '#FF0000',
    color2: '#0000FF',
    length: 10
  })
});
const data = await res.json();
console.log(data);
import requests

resp = requests.post('https://blocksitems.com/api/v1/colors/gradient/linear', json={
    'color1': '#FF0000',
    'color2': '#0000FF',
    'length': 10,
})
print(resp.json())
Response
{
  "gradient": [
    { "position": 0.0, "target_color": "#FF0000", "block": { "full_id": "minecraft:red_wool" } },
    { "position": 1.0, "target_color": "#0000FF", "block": { "full_id": "minecraft:blue_wool" } }
  ],
  "length": 10,
  "color1": "#FF0000",
  "color2": "#0000FF",
  "status": "ok"
}
POST /api/v1/colors/gradient/triangle

Triangle Gradient

Generate a triangular gradient with 3 corner colors. Returns a 2D array of blocks in a triangle pattern.

Parameters

color1 string required

Corner 1 color (hex)

color2 string required

Corner 2 color (hex)

color3 string required

Corner 3 color (hex)

size integer required

Size of triangle edge (2-20)

namespace string optional

Filter by namespace

unique_blocks boolean optional default: false

Use each block only once

curl -X POST 'https://blocksitems.com/api/v1/colors/gradient/triangle' \
  -H 'Content-Type: application/json' \
  -d '{"color1": "#FF0000", "color2": "#00FF00", "color3": "#0000FF", "size": 5}'
const res = await fetch('https://blocksitems.com/api/v1/colors/gradient/triangle', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    color1: '#FF0000', color2: '#00FF00',
    color3: '#0000FF', size: 5
  })
});
const data = await res.json();
console.log(data);
import requests

resp = requests.post('https://blocksitems.com/api/v1/colors/gradient/triangle', json={
    'color1': '#FF0000', 'color2': '#00FF00',
    'color3': '#0000FF', 'size': 5,
})
print(resp.json())
Response
{
  "gradient": [[...], [...]],
  "size": 5,
  "colors": ["#FF0000", "#00FF00", "#0000FF"],
  "status": "ok"
}
POST /api/v1/colors/gradient/square

Square Gradient

Generate a rectangular gradient with diagonal interpolation from top-left to bottom-right. Returns a 2D array of blocks.

Parameters

color1 string required

Top-left corner color (hex)

color2 string required

Bottom-right corner color (hex)

width integer required

Width of square (2-20)

height integer required

Height of square (2-20)

namespace string optional

Filter by namespace

curl -X POST 'https://blocksitems.com/api/v1/colors/gradient/square' \
  -H 'Content-Type: application/json' \
  -d '{"color1": "#FF0000", "color2": "#0000FF", "width": 5, "height": 5}'
const res = await fetch('https://blocksitems.com/api/v1/colors/gradient/square', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    color1: '#FF0000', color2: '#0000FF',
    width: 5, height: 5
  })
});
const data = await res.json();
console.log(data);
import requests

resp = requests.post('https://blocksitems.com/api/v1/colors/gradient/square', json={
    'color1': '#FF0000', 'color2': '#0000FF',
    'width': 5, 'height': 5,
})
print(resp.json())
Response
{
  "gradient": [[...], [...]],
  "width": 5,
  "height": 5,
  "status": "ok"
}
POST /api/v1/colors/gradient/save

Save Gradient

Save a gradient configuration and get a short code for sharing.

Parameters

gradient_type string required

Type of gradient (linear, square, triangle)

color1 string required

First/start color (hex)

color2 string required

Second/end color (hex)

color3 string optional

Third color for triangle gradient (hex)

size integer required

Size/length of gradient

namespace string optional

Namespace filter

curl -X POST 'https://blocksitems.com/api/v1/colors/gradient/save' \
  -H 'Content-Type: application/json' \
  -d '{"gradient_type": "linear", "color1": "#FF0000", "color2": "#0000FF", "size": 10}'
const res = await fetch('https://blocksitems.com/api/v1/colors/gradient/save', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    gradient_type: 'linear',
    color1: '#FF0000', color2: '#0000FF', size: 10
  })
});
const data = await res.json();
console.log(data);
import requests

resp = requests.post('https://blocksitems.com/api/v1/colors/gradient/save', json={
    'gradient_type': 'linear',
    'color1': '#FF0000', 'color2': '#0000FF', 'size': 10,
})
print(resp.json())
Response
{
  "short_code": "aBcDeF12",
  "url": "https://blocksitems.com/colors/gradient/aBcDeF12",
  "status": "ok"
}
GET /api/v1/colors/gradient/{short_code}

Get Saved Gradient

Retrieve a saved gradient configuration by its short code.

Parameters

short_code string required

Short code for the gradient

curl 'https://blocksitems.com/api/v1/colors/gradient/aBcDeF12'
const res = await fetch('https://blocksitems.com/api/v1/colors/gradient/aBcDeF12');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/colors/gradient/aBcDeF12')
print(resp.json())
Response
{
  "gradient_type": "linear",
  "color1": "#FF0000",
  "color2": "#0000FF",
  "size": 10,
  "view_count": 5,
  "status": "ok"
}
Try it
POST /api/v1/mapart/generate

Generate Map Art

Upload a pre-resized PNG image (base64-encoded) and convert it to a Minecraft map art layout using block map colors. Returns a palette, block grid, and material list.

Parameters

maps_wide integer required

Number of maps horizontally (1-4)

maps_tall integer required

Number of maps vertically (1-4)

zoom_level integer required

Map zoom level (0-4). Blocks per map = 128 × 2^zoom

image_data string required

Base64-encoded PNG image, pre-resized to final block dimensions

namespace string optional

Comma-separated namespaces to include (e.g., minecraft,create)

modpack string optional

Modpack slug filter (e.g., atm10)

version string optional

Minecraft version filter (e.g., 1.21.1)

dithering string optional default: none

Dithering algorithm

nonefloyd_steinberg
curl -X POST 'https://blocksitems.com/api/v1/mapart/generate' \
  -H 'Content-Type: application/json' \
  -d '{"maps_wide": 1, "maps_tall": 1, "zoom_level": 0, "image_data": "iVBOR...", "dithering": "none"}'
const res = await fetch('https://blocksitems.com/api/v1/mapart/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    maps_wide: 1, maps_tall: 1, zoom_level: 0,
    image_data: canvas.toDataURL('image/png').split(',')[1],
    dithering: 'floyd_steinberg'
  })
});
const data = await res.json();
console.log(data);
import requests, base64

with open('image.png', 'rb') as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post('https://blocksitems.com/api/v1/mapart/generate', json={
    'maps_wide': 1, 'maps_tall': 1, 'zoom_level': 0,
    'image_data': img_b64, 'dithering': 'floyd_steinberg',
})
print(resp.json())
Response
{
  "id": "aBcDeF12",
  "width": 128,
  "height": 128,
  "palette": [
    { "index": 0, "full_id": "minecraft:stone", "display_name": "Stone", "map_color_hex": "#808080" }
  ],
  "material_list": [
    { "full_id": "minecraft:stone", "display_name": "Stone", "count": 450 }
  ],
  "unique_blocks": 42,
  "total_blocks": 16384,
  "status": "ok"
}
GET /api/v1/mapart/{short_code}

Get Saved Map Art

Retrieve a saved map art by its short code. Returns the palette, grid, and material list.

Parameters

short_code string required

Short code for the map art

curl 'https://blocksitems.com/api/v1/mapart/aBcDeF12'
const res = await fetch('https://blocksitems.com/api/v1/mapart/aBcDeF12');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/mapart/aBcDeF12')
print(resp.json())
Response
{
  "id": "aBcDeF12",
  "width": 128,
  "height": 128,
  "palette": [...],
  "grid": [0, 1, 0, 2, ...],
  "material_list": [...],
  "status": "ok"
}
Try it
GET /api/v1/mapart/{short_code}/export/schematic

Export as Schematic

Download the map art as a WorldEdit .schem file (Sponge Schematic v2).

Parameters

short_code string required

Short code for the map art

curl -o mapart.schem 'https://blocksitems.com/api/v1/mapart/aBcDeF12/export/schematic'
const res = await fetch('https://blocksitems.com/api/v1/mapart/aBcDeF12/export/schematic');
const blob = await res.blob();
// Save blob as .schem file
import requests

resp = requests.get('https://blocksitems.com/api/v1/mapart/aBcDeF12/export/schematic')
with open('mapart.schem', 'wb') as f:
    f.write(resp.content)
Response
Binary .schem file (Content-Type: application/octet-stream)
GET /api/v1/mapart/{short_code}/export/litematic

Export as Litematic

Download the map art as a Litematica .litematic file.

Parameters

short_code string required

Short code for the map art

curl -o mapart.litematic 'https://blocksitems.com/api/v1/mapart/aBcDeF12/export/litematic'
const res = await fetch('https://blocksitems.com/api/v1/mapart/aBcDeF12/export/litematic');
const blob = await res.blob();
// Save blob as .litematic file
import requests

resp = requests.get('https://blocksitems.com/api/v1/mapart/aBcDeF12/export/litematic')
with open('mapart.litematic', 'wb') as f:
    f.write(resp.content)
Response
Binary .litematic file (Content-Type: application/octet-stream)
GET /api/v1/mapart/{short_code}/export/nbt

Export as Structure NBT

Download the map art as a vanilla Minecraft structure .nbt file (compatible with structure blocks and Create mod).

Parameters

short_code string required

Short code for the map art

curl -o mapart.nbt 'https://blocksitems.com/api/v1/mapart/aBcDeF12/export/nbt'
const res = await fetch('https://blocksitems.com/api/v1/mapart/aBcDeF12/export/nbt');
const blob = await res.blob();
// Save blob as .nbt file
import requests

resp = requests.get('https://blocksitems.com/api/v1/mapart/aBcDeF12/export/nbt')
with open('mapart.nbt', 'wb') as f:
    f.write(resp.content)
Response
Binary .nbt file (Content-Type: application/octet-stream)
GET /api/v1/mods

List Mods

Returns a paginated list of mods with item and block counts.

Parameters

search string optional

Search in mod name and ID

page integer optional default: 1

Page number

limit integer optional default: 50

Mods per page (1-100)

curl 'https://blocksitems.com/api/v1/mods?search=create&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/mods?search=create&limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/mods', params={'search': 'create', 'limit': 5})
print(resp.json())
Response
{
  "data": [
    {
      "mod_id": "create",
      "name": "Create",
      "item_count": 245,
      "block_count": 120
    }
  ],
  "page": 1,
  "total": 1,
  "status": "ok"
}
Try it
GET /api/v1/mods/lookup/{query}

Lookup Mod

Looks up a mod by name or mod ID. Returns an exact match if found, otherwise up to 10 close matches.

Parameters

query string required

Mod name or mod ID to search for (e.g., create, Thermal Expansion)

curl 'https://blocksitems.com/api/v1/mods/lookup/create'
const res = await fetch('https://blocksitems.com/api/v1/mods/lookup/create');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/mods/lookup/create')
print(resp.json())
Response
{
  "data": [
    { "mod_id": "create", "name": "Create" }
  ],
  "matched": true,
  "status": "ok"
}
Try it
GET /api/v1/mods/{mod_id}

Get Mod

Returns a single mod by its mod ID with item/block counts and metadata.

Parameters

mod_id string required

Mod ID (e.g., minecraft, create)

curl 'https://blocksitems.com/api/v1/mods/create'
const res = await fetch('https://blocksitems.com/api/v1/mods/create');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/mods/create')
print(resp.json())
Response
{
  "data": {
    "mod_id": "create",
    "name": "Create",
    "item_count": 245,
    "block_count": 120
  },
  "status": "ok"
}
Try it
GET /api/v1/modpacks

List Modpacks

Returns a paginated list of modpacks.

Parameters

search string optional

Search in modpack name and slug

page integer optional default: 1

Page number

limit integer optional default: 50

Modpacks per page (1-100)

curl 'https://blocksitems.com/api/v1/modpacks?limit=5'
const res = await fetch('https://blocksitems.com/api/v1/modpacks?limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/modpacks', params={'limit': 5})
print(resp.json())
Response
{
  "data": [
    { "slug": "atm10", "name": "All the Mods 10" }
  ],
  "page": 1,
  "total": 3,
  "status": "ok"
}
Try it
GET /api/v1/modpacks/{slug}

Get Modpack

Returns a single modpack by its slug with all versions.

Parameters

slug string required

Modpack slug (e.g., atm10)

curl 'https://blocksitems.com/api/v1/modpacks/atm10'
const res = await fetch('https://blocksitems.com/api/v1/modpacks/atm10');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/modpacks/atm10')
print(resp.json())
Response
{
  "data": { "slug": "atm10", "name": "All the Mods 10" },
  "versions": [
    { "version": "2.40", "minecraft_version": "1.21.1", "total_mods": 450 }
  ],
  "status": "ok"
}
Try it
GET /api/v1/modpacks/{modpack_id}/mods

Modpack Mods

Returns a list of mod IDs (namespaces) included in the modpack.

Parameters

modpack_id string required

Modpack ID (UUID)

curl 'https://blocksitems.com/api/v1/modpacks/{uuid}/mods'
const res = await fetch('https://blocksitems.com/api/v1/modpacks/{uuid}/mods');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/modpacks/{uuid}/mods')
print(resp.json())
Response
{
  "data": ["minecraft", "create", "ae2", "thermal"],
  "total": 450,
  "status": "ok"
}
Try it
GET /api/v1/stats

Global Stats

Returns global statistics about items, blocks, recipes, mods, modpacks, textures, and icons.

curl 'https://blocksitems.com/api/v1/stats'
const res = await fetch('https://blocksitems.com/api/v1/stats');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/stats')
print(resp.json())
Response
{
  "total_items": 59435,
  "total_blocks": 47200,
  "total_recipes": 36000,
  "total_mods": 515,
  "total_modpacks": 3,
  "total_textures": 36000,
  "total_icons": 36000,
  "status": "ok"
}
Try it
GET /api/v1/stats/mods

Mod Stats

Returns statistics for each mod (item and block counts), paginated.

Parameters

page integer optional default: 1

Page number

limit integer optional default: 20

Mods per page (1-100)

curl 'https://blocksitems.com/api/v1/stats/mods?limit=5'
const res = await fetch('https://blocksitems.com/api/v1/stats/mods?limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/stats/mods', params={'limit': 5})
print(resp.json())
Response
{
  "data": [
    { "mod_id": "minecraft", "name": "Minecraft", "item_count": 1200, "block_count": 800 }
  ],
  "page": 1,
  "total": 515,
  "status": "ok"
}
Try it
GET /api/v1/tags

List Tags

Returns a paginated list of item and block tags. Tags are groupings like minecraft:tools or minecraft:mineable/pickaxe.

Parameters

type string optional

Filter by tag type

itemblockall
namespace string optional

Filter by namespace (e.g., minecraft, c)

search string optional

Search in tag ID

page integer optional default: 1

Page number

limit integer optional default: 50

Tags per page (1-100)

curl 'https://blocksitems.com/api/v1/tags?type=item&search=tools&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/tags?type=item&search=tools&limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/tags', params={
    'type': 'item', 'search': 'tools', 'limit': 5
})
print(resp.json())
Response
{
  "data": [
    { "tag_id": "minecraft:tools", "type": "item", "member_count": 24 }
  ],
  "page": 1,
  "total": 5,
  "status": "ok"
}
Try it
GET /api/v1/tags/{tag_id}

Get Tag

Returns a single tag with its members (items or blocks that have this tag).

Parameters

tag_id string required

Full tag ID (e.g., minecraft:tools)

curl 'https://blocksitems.com/api/v1/tags/minecraft:tools'
const res = await fetch('https://blocksitems.com/api/v1/tags/minecraft:tools');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/tags/minecraft:tools')
print(resp.json())
Response
{
  "data": { "tag_id": "minecraft:tools", "type": "item" },
  "members": [
    { "full_id": "minecraft:diamond_pickaxe", "display_name": "Diamond Pickaxe" }
  ],
  "status": "ok"
}
Try it
GET /api/v1/search/suggest

Search Suggestions

Returns autocomplete suggestions for items, blocks, and mods. Results include icons and direct URLs.

Parameters

q string required

Search query (min 1 character)

limit integer optional default: 8

Maximum suggestions to return (1-20)

curl 'https://blocksitems.com/api/v1/search/suggest?q=dia&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/search/suggest?q=dia&limit=5');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/search/suggest', params={'q': 'dia', 'limit': 5})
print(resp.json())
Response
{
  "data": [
    { "type": "item", "full_id": "minecraft:diamond", "name": "Diamond" },
    { "type": "block", "full_id": "minecraft:diamond_block", "name": "Block of Diamond" }
  ]
}
Try it
GET /api/v1/images/{hash}

Get Image

Retrieves an image by its SHA256 hash at the specified size. Returns a PNG image. Cached for 1 year.

Parameters

hash string required

Image hash (SHA256)

size integer optional default: 64

Image size in pixels (16, 32, 64, 128, 256, 512)

type string optional

Image type hint

icontextureblock
curl -o image.png 'https://blocksitems.com/api/v1/images/{hash}?size=128'
// Display in an <img> tag
const img = document.createElement('img');
img.src = 'https://blocksitems.com/api/v1/images/{hash}?size=128';
document.body.appendChild(img);
import requests

resp = requests.get('https://blocksitems.com/api/v1/images/{hash}', params={'size': 128})
with open('image.png', 'wb') as f:
    f.write(resp.content)
Response
Binary PNG image data (Content-Type: image/png)
GET /api/v1/items/{full_id}/icon

Item Icon

Retrieves the icon for a specific item at the specified size. Returns a PNG image.

Parameters

full_id string required

Full item ID (e.g., minecraft:diamond_sword)

size integer optional default: 64

Image size in pixels (16-512)

curl -o icon.png 'https://blocksitems.com/api/v1/items/minecraft:diamond_sword/icon?size=128'
const img = document.createElement('img');
img.src = 'https://blocksitems.com/api/v1/items/minecraft:diamond_sword/icon?size=128';
import requests

resp = requests.get('https://blocksitems.com/api/v1/items/minecraft:diamond_sword/icon', params={'size': 128})
with open('icon.png', 'wb') as f:
    f.write(resp.content)
Response
Binary PNG image data (Content-Type: image/png)
GET /api/v1/blocks/{full_id}/icon

Block Icon

Retrieves the icon for a specific block at the specified size. Returns a PNG image.

Parameters

full_id string required

Full block ID (e.g., minecraft:stone)

size integer optional default: 64

Image size in pixels (16-512)

curl -o icon.png 'https://blocksitems.com/api/v1/blocks/minecraft:stone/icon?size=128'
const img = document.createElement('img');
img.src = 'https://blocksitems.com/api/v1/blocks/minecraft:stone/icon?size=128';
import requests

resp = requests.get('https://blocksitems.com/api/v1/blocks/minecraft:stone/icon', params={'size': 128})
with open('icon.png', 'wb') as f:
    f.write(resp.content)
Response
Binary PNG image data (Content-Type: image/png)
GET /api/v1/models/{id}

Get Model

Returns a 3D model by its UUID or hash, including the full model JSON data.

Parameters

id string required

Model UUID or hash

curl 'https://blocksitems.com/api/v1/models/{id}'
const res = await fetch('https://blocksitems.com/api/v1/models/{id}');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/models/{id}')
print(resp.json())
Response
{
  "data": {
    "id": "...",
    "hash": "abc123",
    "namespace": "minecraft",
    "path": "item/diamond_sword",
    "model_data": { "parent": "minecraft:item/handheld", "textures": {} }
  },
  "status": "ok"
}
Try it
GET /api/v1/blocks/{full_id}/model

Block Model

Returns the 3D model definition for a specific block.

Parameters

full_id string required

Full block ID (e.g., minecraft:stone)

curl 'https://blocksitems.com/api/v1/blocks/minecraft:stone/model'
const res = await fetch('https://blocksitems.com/api/v1/blocks/minecraft:stone/model');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/blocks/minecraft:stone/model')
print(resp.json())
Response
{
  "data": {
    "hash": "...",
    "namespace": "minecraft",
    "path": "block/stone",
    "model_data": { "parent": "minecraft:block/cube_all" }
  },
  "status": "ok"
}
Try it
GET /api/v1/items/{full_id}/model

Item Model

Returns the 3D model definition for a specific item.

Parameters

full_id string required

Full item ID (e.g., minecraft:diamond_sword)

curl 'https://blocksitems.com/api/v1/items/minecraft:diamond_sword/model'
const res = await fetch('https://blocksitems.com/api/v1/items/minecraft:diamond_sword/model');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/items/minecraft:diamond_sword/model')
print(resp.json())
Response
{
  "data": {
    "hash": "...",
    "namespace": "minecraft",
    "path": "item/diamond_sword",
    "model_data": { "parent": "minecraft:item/handheld" }
  },
  "status": "ok"
}
Try it
GET /api/v1/diff/items

Item Diff

Returns the diff of items between two modpack versions, showing added, removed, and modified items.

Parameters

from_version string optional

Starting modpack version (optional, omit to show all items as 'added')

to_version string required

Target modpack version

modpack string optional

Modpack slug (optional, defaults to first modpack)

page integer optional default: 1

Page number

limit integer optional default: 50

Results per page (max 100)

curl 'https://blocksitems.com/api/v1/diff/items?to_version=1.21.1&modpack=atm10'
const res = await fetch('https://blocksitems.com/api/v1/diff/items?to_version=1.21.1&modpack=atm10');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/diff/items', params={
    'to_version': '1.21.1', 'modpack': 'atm10'
})
print(resp.json())
Response
{
  "to_version": "1.21.1",
  "modpack": "atm10",
  "changes": [
    { "full_id": "minecraft:wind_charge", "change_type": "added" }
  ],
  "summary": { "added": 150, "removed": 10, "modified": 50 }
}
Try it
GET /api/v1/diff/blocks

Block Diff

Returns the diff of blocks between two modpack versions.

Parameters

from_version string optional

Starting modpack version (optional, omit to show all items as 'added')

to_version string required

Target modpack version

modpack string optional

Modpack slug (optional, defaults to first modpack)

page integer optional default: 1

Page number

limit integer optional default: 50

Results per page (max 100)

curl 'https://blocksitems.com/api/v1/diff/blocks?to_version=1.21.1&modpack=atm10'
const res = await fetch('https://blocksitems.com/api/v1/diff/blocks?to_version=1.21.1&modpack=atm10');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/diff/blocks', params={
    'to_version': '1.21.1', 'modpack': 'atm10'
})
print(resp.json())
Response
{
  "changes": [
    { "full_id": "minecraft:trial_spawner", "change_type": "added" }
  ],
  "summary": { "added": 80, "removed": 5, "modified": 20 }
}
Try it
GET /api/v1/diff/recipes

Recipe Diff

Returns the diff of recipes between two modpack versions.

Parameters

from_version string optional

Starting modpack version (optional, omit to show all items as 'added')

to_version string required

Target modpack version

modpack string optional

Modpack slug (optional, defaults to first modpack)

page integer optional default: 1

Page number

limit integer optional default: 50

Results per page (max 100)

curl 'https://blocksitems.com/api/v1/diff/recipes?to_version=1.21.1&modpack=atm10'
const res = await fetch('https://blocksitems.com/api/v1/diff/recipes?to_version=1.21.1&modpack=atm10');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/diff/recipes', params={
    'to_version': '1.21.1', 'modpack': 'atm10'
})
print(resp.json())
Response
{
  "changes": [
    { "recipe_id": "minecraft:wind_charge", "change_type": "added" }
  ],
  "summary": { "added": 200, "removed": 30, "modified": 100 }
}
Try it
GET /api/v1/diff/summary

Diff Summary

Returns a summary of all changes (items, blocks, recipes) between two modpack versions.

Parameters

from_version string optional

Starting modpack version (optional, omit to show all items as 'added')

to_version string required

Target modpack version

modpack string optional

Modpack slug (optional, defaults to first modpack)

page integer optional default: 1

Page number

limit integer optional default: 50

Results per page (max 100)

curl 'https://blocksitems.com/api/v1/diff/summary?to_version=1.21.1&modpack=atm10'
const res = await fetch('https://blocksitems.com/api/v1/diff/summary?to_version=1.21.1&modpack=atm10');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/diff/summary', params={
    'to_version': '1.21.1', 'modpack': 'atm10'
})
print(resp.json())
Response
{
  "items": { "added": 150, "removed": 10, "modified": 50 },
  "blocks": { "added": 80, "removed": 5, "modified": 20 },
  "recipes": { "added": 200, "removed": 30, "modified": 100 }
}
Try it
GET /api/v1/items/{full_id}/history

Item History

Returns the Minecraft versions where this item is present.

Parameters

full_id string required

Full item ID (e.g., minecraft:diamond)

curl 'https://blocksitems.com/api/v1/items/minecraft:diamond/history'
const res = await fetch('https://blocksitems.com/api/v1/items/minecraft:diamond/history');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/items/minecraft:diamond/history')
print(resp.json())
Response
{
  "full_id": "minecraft:diamond",
  "display_name": "Diamond",
  "history": [
    { "minecraft_version": "1.16.5", "status": "present" },
    { "minecraft_version": "1.18.2", "status": "present" },
    { "minecraft_version": "1.20.1", "status": "present" }
  ]
}
Try it
GET /api/v1/blocks/{full_id}/history

Block History

Returns the Minecraft versions where this block is present.

Parameters

full_id string required

Full block ID (e.g., minecraft:stone)

curl 'https://blocksitems.com/api/v1/blocks/minecraft:stone/history'
const res = await fetch('https://blocksitems.com/api/v1/blocks/minecraft:stone/history');
const data = await res.json();
console.log(data);
import requests

resp = requests.get('https://blocksitems.com/api/v1/blocks/minecraft:stone/history')
print(resp.json())
Response
{
  "full_id": "minecraft:stone",
  "display_name": "Stone",
  "history": [
    { "minecraft_version": "1.16.5", "status": "present" },
    { "minecraft_version": "1.18.2", "status": "present" }
  ]
}
Try it