Mosaicary skins API

Minecraft skins from mosaicary.com, for launchers, mods and anything else that wants to list them, show them and put them on a player.

• Open. No key, no account, no cookie. Every answer is the same for everybody.
• Read only. GET and nothing else.
• Any origin. Every answer carries access-control-allow-origin: *, so a page or a webview can call it directly.
• Only what anybody can see on the site. Published skins that have not been taken down. Nothing marked 18+ is ever returned here. Skins found on players come only once the site has checked them for photos, nudity, gore and hate symbols.
• Cached. Lists and single skins are kept at the edge for 60 seconds; a newly published skin can take that long to show up.

Base address: https://mosaicary.com. This page is also at mosaicary.com/developers.

List skins

GET /api/skins

{
  "skins": [
    {
      "id": "9kPQ3TKUhrI8",
      "name": "Blue hoodie",
      "arms": "slim",
      "width": 64,
      "height": 64,
      "legacy": false,
      "hd": false,
      "png": "https://mosaicary.com/api/skins/9kPQ3TKUhrI8.png",
      "preview": "https://mosaicary.com/api/models/9kPQ3TKUhrI8/preview?v=2026-10-21T16%3A20%3A00.000Z",
      "front": "https://mosaicary.com/api/skins/9kPQ3TKUhrI8/front.png?v=1",
      "render": "https://mosaicary.com/api/skins/9kPQ3TKUhrI8/render.png?v=1.1",
      "live": null,
      "page": "https://mosaicary.com/models/9kPQ3TKUhrI8",
      "author": { "name": "Someone", "url": "https://example.com/someone" },
      "publisher": { "name": "MopicMP", "page": "https://mosaicary.com/u/AbCdEf123456" },
      "license": "cc-by",
      "category": "boys",
      "tags": ["hoodie", "blue"],
      "likes": 12,
      "downloads": 340,
      "published": "2026-10-21T16:20:00.000Z",
      "found": false,
      "wearer": null,
      "eyes": false
    }
  ],
  "page": 1,
  "per": 48,
  "total": 1,
  "pages": 1
}

The fields

New fields may be added. Existing ones keep their names and meanings.

The tags

GET /api/skins/tags

{ "tags": [{ "tag": "hoodie", "count": 41 }, { "tag": "blue", "count": 37 }] }

The tags the listed skins carry, the commonest first, at most 300, with how many skins carry each: what a tag filter offers. size=64 or size=hd counts only those skins, as in the list. Kept at the edge for ten minutes.

One skin

GET /api/skins/{id}

The same object as one entry of the list. 404 when there is no such public skin.

The skin file

GET /api/skins/{id}.png

image/png, served inline, open to any origin. Fetching it counts as a download on the site. If you only show the skin (a 3D preview in your own viewer, say), add ?for=view and it is not counted:

GET /api/skins/{id}.png?for=view

One address may download at most 50 skin files a day (UTC) and 30 files a minute. Past that the answer is 429 with retry-after: files_today for the day, too_often for the minute. Fetches with ?for=view do not count towards the day. A launcher downloads a skin when a player puts it on, so a player stays far below either. To download many skins at once, write to contact@mosaicary.com first.

The front picture

GET /api/skins/{id}/front.png

The skin's front, flat, as the figure stands facing you: base layer with the outer layer over it, 128×256 with a transparent background, each pixel of the skin an 8×8 square. Made from the file itself, so every skin has one. The address in front carries the file's version (?v=): the picture at that address never changes, and may be kept as long as you like. Scale it with nearest-neighbour (image-rendering: pixelated) to keep it sharp.

The render

GET /api/skins/{id}/render.png

The skin worn, as every card on the site's own shelf draws it: mid-stride, turned to show the figure's right side, seen from a little above without perspective, lit from above and in front, the outer layer standing a little off the body. 256×256 with a transparent background, edges smoothed. Made from the file itself, so every skin has one. Like front, the address in render carries a version (?v=) and the picture at it never changes. Show it at 256 pixels or less; scaled up it goes soft.

The live render

GET /api/skins/{id}/live.png

For a skin whose eyes come alive with Fresh Moves (eyes), the render with the eyes moving as the site's cards move them: every few seconds a blink, now and then two, or a look to one side and back. An animated PNG (APNG) that plays for ever, a round of about fifteen seconds; each skin moves its own way, and the same way every time. Only the few pixels around the eyes change from frame to frame, so it is a few kilobytes more than render. A viewer that does not play APNG shows the first frame, which is the still render. Kept for good like render. Someone who asked their system for less motion is better shown render.

Who wears a skin

GET /api/skins/{id}/wearers

{ "count": 3, "players": [{ "name": "Notch", "last": "2026-10-21T22:01:36.101Z" }] }

Minecraft players the site has seen wearing this skin (any file of the same drawing), the most recent first, at most 24 by name; count is all of them. last is when Mojang last said they wore it. Players who asked to be hidden are not counted.

A player and their skins

GET /api/players/{name}

{
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "name": "Notch",
  "seen": "2026-10-21T22:01:43.197Z",
  "checked": "2026-10-21T22:25:28.551Z",
  "current": "292009a4925b58f02c77dadc3ecef07ea4c7472f64e0fdc32ce5522489362680",
  "names": [{ "name": "Notch", "first": "…", "last": "…" }],
  "skins": [{ "texture": "292009a4…", "arms": "classic", "first": "…", "last": "…", "model": { "id": "…", "…": "…" } }]
}

What the site knows about a Java Edition player, by name, case not mattering: the skins seen on them, newest first, and the names they went by. current and each texture are Mojang's texture hash, the last part of the skin's address on textures.minecraft.net; a skin's model.id is the id to use with the endpoints above, and model is null while the file has not arrived. current is null for a player on a default skin.

The site learns of a player when somebody looks them up on the site, and checks known players again from time to time. A name it has no page for answers 404 with "no": "no_such_player" and a lookup field: pending (being looked up now), missing (Mojang has no such player), hidden (the player asked not to be shown), or null (nobody has looked yet). Looking a name up is the site's own page's business and not part of this API.

Putting a skin on a player

Mojang takes only 64×64 and 64×32 skins, so a launcher applying skins to Minecraft accounts should ask with size=64. The arms field is Mojang's variant, as is.

Download png and upload it to POST https://api.minecraftservices.com/minecraft/profile/skins as multipart/form-data with variant and file. This needs the player's Minecraft access token, which stays in the launcher.

The same endpoint used to take {"variant": "<arms>", "url": "<png>"} as JSON and fetch the picture itself. Since October 2026 Mojang's firewall refuses any JSON request there, with an HTML page and status 403 ("The request is blocked"); only the file upload goes through.

Credit

Show who made a skin wherever you show the skin: author if there is one, otherwise publisher, linked to page. Most licences on the site require it (every cc-by variant does), and it is how people find the rest of somebody's work.

Errors

A refusal is JSON with a code and a short English sentence:

{ "no": "odd_request", "error": "arms is classic or slim" }

Being kind to the server

Cache what you fetch, use render, preview or front rather than png for lists, and ask for the next page when somebody scrolls rather than for every page at once. The default order, sort=new, puts the newest skins first. If you are building something bigger on this, tell us: contact@mosaicary.com.