Atlas CDN

Minecraft Modpack Item Image & Metadata API

https://atlas.playcdu.co

📌 Every Image Response Includes X-Display-Name

Every image served by Atlas CDN attaches an X-Display-Name response header containing the URL-encoded human-readable name of the item (e.g. Diamond%20Sword). This applies to direct /img/ requests and any request that redirects to an image (/search/, /random).

Decode it with decodeURIComponent(header) in JS or urllib.parse.unquote(header) in Python. The header is also listed in CORS Access-Control-Expose-Headers so it's accessible from browser fetch() calls.

Get Item Image

GET /img/{modpack}/{namespace}/{itemName}/{variant?}

Retrieve an item's PNG image directly. The variant is optional and defaults to 0.

Parameter	Required	Description
`modpack`	Yes	Modpack / cluster ID, e.g. `atm9`
`namespace`	Yes	Item namespace, e.g. `minecraft`
`itemName`	Yes	Item name, e.g. `diamond_sword`
`variant`	No	Variant number. Defaults to `0`

Example

GET /img/atm9/minecraft/diamond_sword/0

Response

Header	Value
`Content-Type`	`image/png`
`X-Display-Name`	URL-encoded display name, e.g. `Diamond%20Sword`
`ETag`	Entity tag for caching

The X-Display-Name header is present on every image response. Use it to show the item's human-readable name without an extra API call.

Search by Item ID

GET /search/first/{namespace}/{itemName}

Search across all modpacks for an item and redirect to the first match's image.

Parameter	Required	Description
`namespace`	Yes	Item namespace, e.g. `minecraft`
`itemName`	Yes	Item name, e.g. `diamond_pickaxe`

Example

GET /search/first/minecraft/diamond_pickaxe
# → 302 redirect to /img/atm9/minecraft/diamond_pickaxe/0

Great for when you don't know which modpack contains an item. The browser / HTTP client follows the redirect automatically. The final image response includes the X-Display-Name header.

Search by Display Name

GET /search/display/{query}

Search by human-readable display name and redirect to the first match's image. The query is URL-decoded automatically.

Parameter	Required	Description
`query`	Yes	Display name to search for, e.g. `Diamond%20Sword`

Example

GET /search/display/Diamond%20Sword
# → 302 redirect to the first matching item image

Following the redirect returns the image with the X-Display-Name header.

Random Item

GET /random

Get a random item image from any modpack. Redirects to the image URL. The final response includes the X-Display-Name header.

Example

GET /random
# → 302 redirect to a random item image

Random Minecraft Item

GET /random/minecraft

Get a random vanilla Minecraft item image. Redirects to the image URL. The final response includes the X-Display-Name header.

Example

GET /random/minecraft
# → 302 redirect to a random minecraft item image

Get Modpack Manifest

GET /{modpack}/manifest

Retrieve the complete item manifest for a modpack. Returns a JSON array of every item.

Parameter	Required	Description
`modpack`	Yes	Modpack ID, e.g. `atm9`

Example

GET /atm9/manifest

Response body

[
  { "name": "minecraft:diamond_sword", "display_name": "Diamond Sword", "variant": 0 },
  { "name": "minecraft:diamond_pickaxe", "display_name": "Diamond Pickaxe", "variant": 0 }
]

Get Item Metadata

GET /{modpack}/meta/{namespace}/{itemName}/{variant?}

Retrieve JSON metadata for a specific item.

Parameter	Required	Description
`modpack`	Yes	Modpack ID
`namespace`	Yes	Item namespace
`itemName`	Yes	Item name
`variant`	No	Variant number (defaults to `0`)

Example

GET /atm9/meta/minecraft/diamond_sword/0

Upload Item AUTH

POST /api/{modpack}/upload

Upload an item image and metadata to a modpack. Requires Bearer token authentication.

Field	Type	Required	Description
`itemName`	string	Yes	Item ID, e.g. `minecraft:diamond_sword`
`displayName`	string	Yes	Human-readable name, e.g. `Diamond Sword`
`variant`	string	Yes	Variant number, e.g. `0`
`image`	file	Yes	PNG image file
`meta`	file	Yes	JSON metadata file
`namespace`	string	No	Namespace (if not in itemName)

cURL example

curl -X POST https://atlas.playcdu.co/api/atm9/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "itemName=minecraft:diamond_sword" \
  -F "displayName=Diamond Sword" \
  -F "variant=0" \
  -F "image=@diamond_sword.png" \
  -F "meta=@meta.json"

Success response

{ "success": true, "message": "Successfully uploaded minecraft:diamond_sword v0" }

Publish Modpack AUTH

POST /api/{modpack}/publish

Generate and publish the manifest for a modpack. Run this after uploading items to make them discoverable.

cURL example

curl -X POST https://atlas.playcdu.co/api/atm9/publish \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response

{ "success": true, "message": "Successfully published manifest for atm9 with 15234 items." }

Modpack Status AUTH

GET /api/{modpack}/status

Check a modpack's status including last update timestamp.

cURL example

curl https://atlas.playcdu.co/api/atm9/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{ "name": "atm9", "last_updated": "2025-01-15 10:30:45" }

Authentication

All /api/* endpoints require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Public endpoints (/img, /search, /random, manifests, metadata) require no authentication.

Error Handling

All errors return JSON in a consistent format:

{
  "error": "Short error description",
  "message": "Detailed info (optional)"
}

Status Codes

Code	Meaning	Common Cause
`200`	OK	Request succeeded
`302`	Redirect	Search endpoints redirect to image URL
`400`	Bad Request	Invalid modpack name or missing fields
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Image, manifest, or modpack doesn't exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal processing failure

CORS

All endpoints are fully CORS-enabled:

Header	Value
Allowed Origins	`*` (all origins)
Exposed Headers	`X-Display-Name`

Response Headers

Header	Present On	Description
X-Display-Name	Every image response	URL-encoded human-readable item name, e.g. `Diamond%20Sword`
ETag	Images, manifests, metadata	Entity tag for HTTP caching / conditional requests
Content-Type	All responses	`image/png` for images, `application/json` for data

Using X-Display-Name

Every image served by Atlas includes X-Display-Name — this is the easiest way to get an item's readable name alongside its image in a single request.

JavaScript

const r = await fetch(imageUrl);
const raw = r.headers.get("X-Display-Name");
const name = decodeURIComponent(raw || "");
// "Diamond Sword"

Python

from urllib.parse import unquote
r = requests.get(image_url)
name = unquote(r.headers["X-Display-Name"])
# "Diamond Sword"

This header is exposed via CORS (Access-Control-Expose-Headers), so it's readable from browser fetch() and XMLHttpRequest calls on any origin.

Quick Examples

cURL

# Fetch an image
curl https://atlas.playcdu.co/img/atm9/minecraft/diamond_sword/0 -o sword.png

# Search for an item across all modpacks
curl -L https://atlas.playcdu.co/search/first/minecraft/diamond_sword -o sword.png

# Search by display name
curl -L https://atlas.playcdu.co/search/display/Diamond%20Sword -o sword.png

# Get a random item
curl -L https://atlas.playcdu.co/random -o random.png

# Download a modpack manifest
curl https://atlas.playcdu.co/atm9/manifest -o manifest.json

JavaScript

// Direct image fetch
const res = await fetch("https://atlas.playcdu.co/img/atm9/minecraft/diamond_sword/0");
const blob = await res.blob();
const name = decodeURIComponent(res.headers.get("X-Display-Name") || "");

// Search (follows redirect automatically)
const img = await fetch("https://atlas.playcdu.co/search/first/minecraft/diamond_sword");

// Use in an <img> tag
// <img src="https://atlas.playcdu.co/img/atm9/minecraft/diamond_sword/0" />

Python

import requests
from urllib.parse import unquote

# Direct fetch
r = requests.get("https://atlas.playcdu.co/img/atm9/minecraft/diamond_sword/0")
display_name = unquote(r.headers.get("X-Display-Name", ""))

with open("sword.png", "wb") as f:
    f.write(r.content)

# Search across all modpacks
r = requests.get("https://atlas.playcdu.co/search/first/minecraft/diamond_sword")
# requests follows the 302 redirect automatically

HTML Embed

<!-- Direct image (fastest) -->
<img src="https://atlas.playcdu.co/img/atm9/minecraft/diamond_sword/0" alt="Diamond Sword" />

<!-- Search-based (auto-redirects, use when modpack is unknown) -->
<img src="https://atlas.playcdu.co/search/first/minecraft/diamond_sword" alt="Diamond Sword" />

Complete Upload Workflow

To add items to a modpack, follow these three steps:

# 1. Upload items (repeat for each item)
curl -X POST https://atlas.playcdu.co/api/atm9/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "itemName=minecraft:diamond_sword" \
  -F "displayName=Diamond Sword" \
  -F "variant=0" \
  -F "image=@diamond_sword.png" \
  -F "meta=@meta.json"

# 2. Publish the modpack manifest (makes items discoverable)
curl -X POST https://atlas.playcdu.co/api/atm9/publish \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Verify
curl https://atlas.playcdu.co/api/atm9/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Interactive Docs & OpenAPI Spec

GET /docs

Swagger UI — interactive browser for all endpoints.

GET /docs/openapi.json

Raw OpenAPI 3.0 specification in JSON format. Useful for code generation or importing into tools like Postman.

Open /docs in your browser to explore endpoints interactively, or fetch /docs/openapi.json for the machine-readable spec.