API Documentation

The HyAssets API is a free, public, read-only REST API serving metadata and CDN URLs for 4,293 Hytale item assets. No authentication, no rate limits, permissive CORS — built for tools, mods and bots.

Swagger UI ReDoc OpenAPI schema

Base URL

All endpoints are relative to this origin:

Base URL

https://hyassets.dev/api/v1

Endpoints

Method	Endpoint	Description
GET	/api/v1/items	List & search. Params: q, category, quality, craftable, min_level, max_level, format, sort, page, limit.
GET	/api/v1/items/{id}	Full metadata for one item incl. rarity, level & crafting recipe.
GET	/api/v1/categories	All categories with item counts.
GET	/api/v1/random?count=12	A random selection of items.
GET	/api/v1/players/{username}	Look up a player's skin, avatar render & cosmetics.
GET	/api/v1/mobs	Browse Hytale mobs / creatures (category, q).
GET	/api/v1/cosmetics	Browse character cosmetics (slot, q). Each has a self-hosted preview render.
GET	/api/v1/render	Render a custom character from cosmetic slot params (the builder). Returns PNG.
GET	/api/v1/stats	Catalog totals (items, categories, size, formats).
GET	/api/v1/health	Service & catalog health probe.

Examples

Fetch the second page of weapons, 24 per page:

curl "https://hyassets.dev/api/v1/items?category=weapon&page=2&limit=24"

Search by name:

curl "https://hyassets.dev/api/v1/items?q=sword"

Get one item and read its CDN URL (JavaScript):

const res = await fetch("https://hyassets.dev/api/v1/items/arcade-machine");
const item = await res.json();
console.log(item.cdn_url);   // full-resolution PNG on the CDN
console.log(item.thumb_url); // WebP thumbnail

Filter by rarity and craftability, sort by item level:

curl "https://hyassets.dev/api/v1/items?quality=Legendary&craftable=true&sort=-level"

A single item includes its crafting recipe & rarity:

curl "https://hyassets.dev/api/v1/items/arcade-machine"
# → { display_name, quality, item_level, recipe: { inputs:[{name, quantity, id, thumb_url}], bench, time_seconds }, used_in: [...] }

Look up a player's skin by username:

curl "https://hyassets.dev/api/v1/players/Simon"
# → { uuid, renders: { avatar, bust, body }, skin: { haircut, cape, … } }

Using the CDN

Every item is served directly from the edge CDN with long-livedimmutablecaching and open CORS. Embed an item anywhere:

<img src="https://hyassets.dev/cdn/<category>/<id>.png" alt="Hytale item" />

Item icons are 64×64 pixel art — scale them up withimage-rendering: pixelatedto keep crisp edges.

Item response shape

{
  "id": "arcade-machine",
  "name": "Iron Sword",
  "category": "weapon",
  "format": "PNG",
  "width": 64,
  "height": 64,
  "aspect_ratio": 1.0,
  "size_bytes": 3840,
  "tags": ["weapon", "sword", "iron"],
  "cdn_url": "https://hyassets.dev/cdn/weapon/arcade-machine.png",
  "thumb_url": "https://hyassets.dev/thumbs/arcade-machine.webp",
  "api_url": "https://hyassets.dev/api/v1/items/arcade-machine"
}