Minecraft UUID lookup

One GET turns a username into a UUID, or a UUID into the current username. JSON, open to browser code, with the skin and cape hashes in the same answer.

Notch

069a79f444e94726a5befca90e38aaf5

texture:292009a4925b…

The endpoint

GET https://skinrender.dev/api/profile/Notch

{
  "uuid": "069a79f444e94726a5befca90e38aaf5",
  "name": "Notch",
  "model": "classic",
  "skinUrl": "https://textures.minecraft.net/texture/292009a4925b58f02c77dadc3ecef07ea4c7472f64e0fdc32ce5522489362680",
  "skinHash": "292009a4925b58f02c77dadc3ecef07ea4c7472f64e0fdc32ce5522489362680",
  "capeUrl": null,
  "capeHash": null
}

That is the whole API. GET /api/profile/<username or uuid>, no key, no login, no query parameters to learn. HEAD works if you only want the status, and OPTIONS answers the browser’s preflight.

What goes in the path

A username (1–16 letters, digits or underscores) or a UUID, dashed or not — 069a79f444e94726a5befca90e38aaf5 and the hyphenated form are the same request. Case does not matter going in, and the name that comes back is the profile’s own capitalisation, which is the one to display: ask for dinnerbone and you are told Dinnerbone.

The steve, alex and texture:… identifiers that the render API accepts are not profiles and answer 400 here — there is no account behind a default skin or a bare texture. Everything else about the fields: model is classic or slim (the three-pixel arms) exactly as Mojang’s profile records it, which is not always what a render draws — a body render uses slim anyway when the texture is a slim one — and skinUrl, skinHash, capeUrl and capeHash are null for a player who has never set one.

Calling it from a browser

Every response sends Access-Control-Allow-Origin: *, so page JavaScript can call this directly. That is worth spelling out, because it is the usual reason a name lookup ends up behind a proxy of your own. Mojang’s own profile service sends no Access-Control-Allow-Origin header at all, so a browser refuses to hand the response to your code, and people write a tiny backend whose only job is to forward the request. You do not need one.

async function uuidOf(name) {
  const r = await fetch(`https://skinrender.dev/api/profile/${name}`);
  if (r.status === 404) return null;
  if (!r.ok) throw new Error(await r.text());
  return (await r.json()).uuid;
}

Errors are plain text with an honest status: 400 for something that is not a username or a UUID (the message says what was expected), 404 for a name nobody owns, 502 when Mojang is unreachable. Never a 200 with an error inside it.

From a hash to a URL that never changes

The reason the hashes are in the answer: they turn a render URL into a permanent one. A render addressed by UUID follows the player, so the image changes the day they change their skin — usually what you want on a live profile card. A render addressed by texture:<hash> is pinned to that exact texture, skips the profile lookup entirely and is served with Cache-Control: immutable, which is what you want for a leaderboard snapshot, a forum post or anything archived.

const { uuid, skinHash } = await fetch("https://skinrender.dev/api/profile/jeb_").then((r) => r.json());

// follows the player: changes the day they change their skin
const live = `https://skinrender.dev/render/${uuid}/body?size=256`;

// pinned to this exact texture, cached as immutable, safe to hotlink forever
const pinned = `https://skinrender.dev/render/texture:${skinHash}/body?size=256`;

Caching and rate limits

Mojang limits how often a name can be resolved, and every third-party skin service shares that ceiling, so the answer is cached at three levels: the name-to-UUID result for an hour, the profile behind it for 15 minutes, and the HTTP response itself with Cache-Control: public, max-age=600. A page that looks up the same handful of players repeatedly never leaves the cache. If you are resolving hundreds of names in a loop, store the UUIDs once — they are permanent, which is the entire point of them — and stop asking.

The caching and limits page has the rest, including what a first, uncached request costs.

What this is not

It is a profile lookup, not a Mojang mirror. There is no name history (Mojang retired that endpoint in 2022, so nobody has it), no bulk endpoint that takes a list of names, no authentication, no writes. If you need the rendered player rather than the JSON, the render API takes the very same identifiers and hands back a PNG: faces, heads, bodies and the raw skin file.