Quick Start

No account · No key · No setup

The XIV Dye Tools API is a public REST API serving the FFXIV dye database and color matching algorithms. Responses are JSON in one envelope.

Base URL

Every endpoint is prefixed with /v1.

Basehttps://data.xivdyetools.app/v1

Your first request

Fetch Snow White (stainID 1). This is the same console card every reference page uses — Send makes the request from your browser, and nothing is fetched until you tap it.

GET/v1/dyes/1One dye, by itemID or stainID — the range decides which.›

One dye, by itemID or stainID — the range decides which.

cURL$ curl https://data.xivdyetools.app/v1/dyes/1JavaScriptconst r = await fetch('https://data.xivdyetools.app/v1/dyes/1');
const { data } = await r.json();

GET /v1/dyes/1

STATUS · TIME · X-REQUEST-ID — after Send

// tap Send — nothing is fetched until you ask

itemIDintegerLegacy game item ID (equals stainID for future consolidated-only dyes)

stainIDintegerStain table ID (1–254)

idintegerSame as itemID

namestringEnglish dye name

localizedNamestring?Present only when locale ≠ en

hexstringHex color (#RRGGBB)

rgbobject{ r, g, b } — 0–255

hsvobject{ h, s, v } — hue 0–360, sat/val 0–100

categorystringBlues · Browns · Greens · Neutral · Purples · Reds · Special · Yellows

acquisitionstringDye Vendor · The Firmament · Cosmic Exploration · Venture Coffers

costintegerVendor price

currencystring | nullGil · Skybuilders Scrips · Cosmocredits · Venture Coffer (one per acquisition)

isMetallicbooleanMetallic sheen

isPastelbooleanPastel shade

isDarkbooleanDark shade

isCosmicbooleanFrom Cosmic Exploration

isIshgardianbooleanFrom Ishgardian Restoration

consolidationTypestring | nullPatch 7.5 group: A, B, C, or null

marketItemIDintegerItem ID for market-board lookups only (Universalis) — never a dye lookup key. 105 dyes share 52254 / 52255 / 52256 since Patch 7.5; GET /v1/dyes/:id rejects those with a hint pointing at /v1/dyes/consolidation-groups

Every /v1 response has the same { success, data, meta } envelope (meta.locale appears only when a non-English locale was requested). See Responses for the full spec.

ID auto-detection

Most ID endpoints accept any of three numeric ID types. The type is inferred by range:

Range	Type	Example
1 – 254	stainID (game stain table; 126+ reserved for future dyes)	1 = Snow White
≥ 5729	itemID (game item database)	5729 = Snow White
< 0	Legacy Facewear ID — explanatory 404 (no longer served as dyes)	-1629
255 – 5728	(invalid gap)	Returns 404

# All three resolve to Snow White
curl https://data.xivdyetools.app/v1/dyes/1       # stainID
curl https://data.xivdyetools.app/v1/dyes/5729    # itemID
curl https://data.xivdyetools.app/v1/dyes/stain/1 # explicit stainID

Localization

Add ?locale= to any dye endpoint to get localized names. Supported: en, ja, de, fr, ko, zh.

curl https://data.xivdyetools.app/v1/dyes/1?locale=ja

{
  "data": {
    "name": "Snow White",
    "localizedName": "スノウホワイト",
    ...
  }
}

Next: Reference

Section	Endpoints
Dyes	/v1/dyes/* — lookup, filtering, search, batch, consolidation groups
Color Matching	/v1/match/* — closest dye, dyes within a distance
Character Equipment	/v1/chara/* — .chara gear resolution and item icons
Harmony	/v1/wheels/*, /v1/harmony/* — the five colour wheels and a dye for every harmony slot

The Reference overview lists every endpoint, most with a live sample from the API.

Planned: community presets, and optional API keys for higher rate limits.

Rate limits

Anonymous requests: 60 per minute per IP. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. See Rate Limits.