API Information

Technical Details

Everything you need to know about integrating the Minecraft Item API into your project.

Base URL

https://api.minecraftitems.xyz

All API endpoints are relative to this base URL. HTTPS is required for all requests.

Authentication

Most endpoints work without authentication. However, some features require an API key:

Creating shareable links
Uploading custom resource packs
Using custom resource packs in renders
Higher rate limits

To get an API key, make a POST request to /api/setup with your username. Your API key will only be shown once, so save it immediately.

Pass your API key as a query parameter:

/api/item/diamond_sword?apiKey=YOUR_API_KEY

Or in the request body for POST requests:

{ "apiKey": "YOUR_API_KEY", ... }

Rate Limits

Tier	Requests	Window
No API Key	60 requests	per minute
With API Key	300 requests	per minute
GIF Generation	10 requests	per minute

Rate limit headers are included in all responses. If you exceed the limit, you'll receive a 429 status code.

Response Formats

Image Responses

Item, GUI, tooltip, and player list endpoints return PNG images directly. GIF endpoints return GIF images. The Content-Type header indicates the format.

image/png — Static item renders, GUIs, tooltips
image/gif — Animated rotating items

JSON Responses

Share endpoints, setup endpoints, and stats endpoints return JSON.

{
  "success": true,
  "url": "https://api.minecraftitems.xyz/api/share/abc123",
  "expiresAt": "2024-01-01T00:00:00.000Z"
}

Error Responses

Errors return JSON with an error message and appropriate HTTP status code.

{
  "error": "Item not found",
  "message": "The item 'invalid_item' does not exist"
}

HTTP Status Codes

Code	Meaning
200	Success — Image or JSON returned
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid or missing API key
404	Not Found — Item or resource doesn't exist
429	Too Many Requests — Rate limit exceeded
500	Server Error — Something went wrong

Caching

Rendered images are cached server-side to improve response times. Identical requests will return cached results when available.

Static item renders are cached for 24 hours
GIF renders are cached for 1 hour
Shareable links expire 1 hour after last access
Resource pack renders are cached separately per pack

Cache headers (Cache-Control, ETag) are included in responses for client-side caching.

Supported Content

The API supports all items and blocks from Minecraft Java Edition, updated to the latest version.

Item Names

Use the Minecraft internal item ID (e.g., diamond_sword, netherite_pickaxe). Names are case-insensitive and underscores can be replaced with hyphens.

Color Codes

Tooltips and display names support Minecraft color codes using the § symbol:

§0 Black§1 Dark Blue§2 Dark Green§3 Dark Aqua§4 Dark Red§5 Purple§6 Gold§7 Gray§8 Dark Gray§9 Blue§a Green§b Aqua§c Red§d Pink§e Yellow§f White

§l Bold§o Italic§n Underline§m Strikethrough§r Reset formatting

Resource Packs

Upload custom Minecraft resource packs to render items with your own textures and models. Perfect for servers with custom items using CustomModelData.

Requirements

Valid Minecraft resource pack format (.zip)
Maximum file size: 50MB
Must contain valid pack.mcmeta
API key required for upload

Using Resource Packs

After uploading, use the rp query parameter with your pack ID:

/api/item/diamond_sword?rp=pack_abc123&apiKey=YOUR_KEY

Custom Model Data

Use the cmd parameter to specify CustomModelData values:

/api/item/diamond_sword?rp=pack_abc123&cmd=1&apiKey=YOUR_KEY

CORS Policy

The API supports Cross-Origin Resource Sharing (CORS) for all origins. You can make requests from any domain, including browser-based JavaScript applications.

For image endpoints, you can also use the URLs directly in <img> tags without any CORS issues.

Language Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.minecraftitems.xyz/api/item/diamond_sword/size=4'
);
const imageBlob = await response.blob();

Python

import requests

response = requests.get(
    'https://api.minecraftitems.xyz/api/item/diamond_sword/size=4'
)
with open('sword.png', 'wb') as f:
    f.write(response.content)

cURL

curl -o sword.png \
  'https://api.minecraftitems.xyz/api/item/diamond_sword/size=4'

HTML (Direct Embed)

<img
  src="https://api.minecraftitems.xyz/api/item/diamond_sword/size=4"
  alt="Diamond Sword"
/>

Ready to Start?

Try the API in the Playground, or check out the full documentation for detailed endpoint references.