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.
Base URL:
/api/v1All responses return JSON with a consistent structure. List endpoints include pagination metadata. The OpenAPI spec is also available.
curl '/api/v1/items?search=diamond&limit=5'
{
"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
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
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)
{
"data": [...],
"page": 2,
"limit": 50,
"total": 59435,
"pages": 1189,
"status": "ok"
}
/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())
{
"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
/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())
{
"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
/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())
{
"data": {
"full_id": "minecraft:diamond",
"display_name": "Diamond",
"icon_url": "https://blocksitems.com/api/v1/images/abc123"
},
"found": true,
"status": "ok"
}
Try it
/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())
{
"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"
}
/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())
{
"data": [
{ "full_id": "create:brass_ingot", "display_name": "Brass Ingot" }
],
"page": 1,
"limit": 5,
"total": 245,
"status": "ok"
}
Try it
/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())
{
"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
/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())
{
"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
/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())
{
"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
/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())
{
"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"
}
/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())
{
"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
/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())
{
"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
/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())
{
"data": {
"id": "...",
"type": "minecraft:crafting_shaped",
"pattern": ["###", " | ", " | "],
"ingredients": [...],
"result": { "item_id": "minecraft:diamond_pickaxe", "count": 1 }
},
"status": "ok"
}
Try it
/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())
{
"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
/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())
{
"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"
}
/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())
{
"gradient": [[...], [...]],
"size": 5,
"colors": ["#FF0000", "#00FF00", "#0000FF"],
"status": "ok"
}
/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())
{
"gradient": [[...], [...]],
"width": 5,
"height": 5,
"status": "ok"
}
/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())
{
"short_code": "aBcDeF12",
"url": "https://blocksitems.com/colors/gradient/aBcDeF12",
"status": "ok"
}
/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())
{
"gradient_type": "linear",
"color1": "#FF0000",
"color2": "#0000FF",
"size": 10,
"view_count": 5,
"status": "ok"
}
Try it
/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())
{
"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"
}
/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())
{
"id": "aBcDeF12",
"width": 128,
"height": 128,
"palette": [...],
"grid": [0, 1, 0, 2, ...],
"material_list": [...],
"status": "ok"
}
Try it
/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)
Binary .schem file (Content-Type: application/octet-stream)
/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)
Binary .litematic file (Content-Type: application/octet-stream)
/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)
Binary .nbt file (Content-Type: application/octet-stream)
/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())
{
"data": [
{
"mod_id": "create",
"name": "Create",
"item_count": 245,
"block_count": 120
}
],
"page": 1,
"total": 1,
"status": "ok"
}
Try it
/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())
{
"data": [
{ "mod_id": "create", "name": "Create" }
],
"matched": true,
"status": "ok"
}
Try it
/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())
{
"data": {
"mod_id": "create",
"name": "Create",
"item_count": 245,
"block_count": 120
},
"status": "ok"
}
Try it
/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())
{
"data": [
{ "slug": "atm10", "name": "All the Mods 10" }
],
"page": 1,
"total": 3,
"status": "ok"
}
Try it
/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())
{
"data": { "slug": "atm10", "name": "All the Mods 10" },
"versions": [
{ "version": "2.40", "minecraft_version": "1.21.1", "total_mods": 450 }
],
"status": "ok"
}
Try it
/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())
{
"data": ["minecraft", "create", "ae2", "thermal"],
"total": 450,
"status": "ok"
}
Try it
/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())
{
"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
/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())
{
"data": [
{ "mod_id": "minecraft", "name": "Minecraft", "item_count": 1200, "block_count": 800 }
],
"page": 1,
"total": 515,
"status": "ok"
}
Try it
/api/v1/stats/popular
Popular Items
Returns the most viewed items and blocks by view count.
Parameters
period
string
optional
Time period for popularity
dayweekmonthall
type
string
optional
Type to filter
itemblockall
limit
integer
optional
default: 20
Number of items (1-100)
curl 'https://blocksitems.com/api/v1/stats/popular?period=week&type=item&limit=5'
const res = await fetch('https://blocksitems.com/api/v1/stats/popular?period=week&type=item&limit=5');
const data = await res.json();
console.log(data);
import requests
resp = requests.get('https://blocksitems.com/api/v1/stats/popular', params={
'period': 'week', 'type': 'item', 'limit': 5
})
print(resp.json())
{
"data": [
{ "full_id": "minecraft:diamond", "display_name": "Diamond", "view_count": 1234 }
],
"status": "ok"
}
Try it
/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())
{
"data": [
{ "tag_id": "minecraft:tools", "type": "item", "member_count": 24 }
],
"page": 1,
"total": 5,
"status": "ok"
}
Try it
/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())
{
"data": { "tag_id": "minecraft:tools", "type": "item" },
"members": [
{ "full_id": "minecraft:diamond_pickaxe", "display_name": "Diamond Pickaxe" }
],
"status": "ok"
}
Try it
/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())
{
"data": [
{ "type": "item", "full_id": "minecraft:diamond", "name": "Diamond" },
{ "type": "block", "full_id": "minecraft:diamond_block", "name": "Block of Diamond" }
]
}
Try it
/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)
Binary PNG image data (Content-Type: image/png)
/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)
Binary PNG image data (Content-Type: image/png)
/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)
Binary PNG image data (Content-Type: image/png)
/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())
{
"data": {
"id": "...",
"hash": "abc123",
"namespace": "minecraft",
"path": "item/diamond_sword",
"model_data": { "parent": "minecraft:item/handheld", "textures": {} }
},
"status": "ok"
}
Try it
/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())
{
"data": {
"hash": "...",
"namespace": "minecraft",
"path": "block/stone",
"model_data": { "parent": "minecraft:block/cube_all" }
},
"status": "ok"
}
Try it
/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())
{
"data": {
"hash": "...",
"namespace": "minecraft",
"path": "item/diamond_sword",
"model_data": { "parent": "minecraft:item/handheld" }
},
"status": "ok"
}
Try it
/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())
{
"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
/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())
{
"changes": [
{ "full_id": "minecraft:trial_spawner", "change_type": "added" }
],
"summary": { "added": 80, "removed": 5, "modified": 20 }
}
Try it
/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())
{
"changes": [
{ "recipe_id": "minecraft:wind_charge", "change_type": "added" }
],
"summary": { "added": 200, "removed": 30, "modified": 100 }
}
Try it
/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())
{
"items": { "added": 150, "removed": 10, "modified": 50 },
"blocks": { "added": 80, "removed": 5, "modified": 20 },
"recipes": { "added": 200, "removed": 30, "modified": 100 }
}
Try it
/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())
{
"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
/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())
{
"full_id": "minecraft:stone",
"display_name": "Stone",
"history": [
{ "minecraft_version": "1.16.5", "status": "present" },
{ "minecraft_version": "1.18.2", "status": "present" }
]
}