Reference

API reference

Every AlloyMC API endpoint with its parameters and an example response, generated from the OpenAPI spec.

Updated 1 November 2026 · Markdown

Every endpoint, grouped by what it's about. Open one to see its parameters and an example answer. Endpoints marked token need a bearer token. The same information, machine-readable: openapi.json.

Status Users Me Minecraft Auth

Status

Is it up, and what's the newest Alloy.

GET/v1/launcher/releases/latestNewest Alloy release and its signed update files

200 The newest release

{
  "published": "2026-10-30T18:15:43Z",
  "updates": {
    "windows-x86_64": {
      "sha256": "…",
      "size": 5666631,
      "url": "https://github.com/…"
    }
  },
  "version": "0.2.1"
}

GET/v1/statusServer status

200 Up

{
  "launcher": "0.2.1",
  "ok": true,
  "version": "0.1.9"
}

Users

Public profiles and who follows whom.

GET/v1/users/{handle}A public profile

Parameter	In	About
`handle` required	path

200 The profile. Private profiles return only handle, displayName, avatarUrl and private: true.

GET/v1/users/{handle}/avatar.pngAvatar image

The linked Minecraft head or the person's sigil, as a crisp pixel PNG.

Parameter	In	About
`handle` required	path
`s`	query	Size in pixels, rounded down to a multiple of 8.

200 PNG

PUT/v1/users/{handle}/followFollow someonetoken

Parameter	In	About
`handle` required	path

204 Following (also if you already were)

DELETE/v1/users/{handle}/followUnfollow someonetoken

Parameter	In	About
`handle` required	path

204 Not following

GET/v1/users/{handle}/followersWho follows someone, newest first

Parameter	In	About
`handle` required	path
`before`	query	Cursor from the previous page's next.

200 Up to 50 people and a cursor

{
  "next": 0,
  "users": [
    {
      "accent": "lapis",
      "avatarUrl": "https://api.alloymc.dev/v1/users/someone/avatar.png",
      "displayName": "Someone",
      "handle": "someone"
    }
  ]
}

GET/v1/users/{handle}/followingWho someone follows, newest first

Parameter	In	About
`handle` required	path
`before`	query

200 Up to 50 people and a cursor

Me

The signed-in account. Needs a bearer token.

GET/v1/meYour accounttoken

200 You, including your email

PATCH/v1/meChange your profiletoken

Send only the fields to change: handle, displayName, bio, pronouns, links, accent, avatar ("sigil" or "minecraft:<uuid>"), private.

Request body

{
  "accent": "amethyst",
  "bio": "Builds castles. Breaks modpacks."
}

200 The updated account

GET/v1/me/sessionsWhere you're signed intoken

200 Sessions, most recently used first

DELETE/v1/me/sessions/{id}Sign one session outtoken

Parameter	In	About
`id` required	path

204 Signed out

Minecraft

Link a Minecraft account with Mojang's own proof, and its skin renders.

POST/v1/me/minecraftFinish linkingtoken

AlloyMC asks Mojang's hasJoined who joined with that server ID. The Minecraft token never reaches AlloyMC.

Request body

{
  "serverId": "alloymc1f3a9c0d2e7b4",
  "username": "Notch"
}

200 Linked

POST/v1/me/minecraft/challengeStart linking a Minecraft accounttoken

Returns a server ID valid for two minutes. Pass it to Mojang's POST https://sessionserver.mojang.com/session/minecraft/join with the player's own access token, exactly as when joining a server; then call POST /v1/me/minecraft.

200 A server ID

{
  "expiresIn": 120,
  "serverId": "alloymc1f3a9c0d2e7b4"
}

DELETE/v1/me/minecraft/{uuid}Unlink a Minecraft accounttoken

Parameter	In	About
`uuid` required	path

204 Unlinked

GET/v1/minecraft/{uuid}Find the AlloyMC profile behind a player

Looks up a Minecraft account by UUID (with or without dashes). Answers only when the player is linked to a public AlloyMC profile and shown on it; otherwise 404, so hidden links stay hidden.

Parameter	In	About
`uuid` required	path	Minecraft UUID, with or without dashes

200 The player and their AlloyMC profile

{
  "bodyUrl": "https://api.alloymc.dev/v1/minecraft/069a79f444e94726a5befca90e38aaf5/body.png",
  "headUrl": "https://api.alloymc.dev/v1/minecraft/069a79f444e94726a5befca90e38aaf5/head.png",
  "name": "Notch",
  "slim": false,
  "user": {
    "accent": "amethyst",
    "avatarUrl": "https://api.alloymc.dev/v1/users/kestrel/avatar.png?v=1a2b3c4d",
    "displayName": "Kestrel",
    "handle": "kestrel",
    "profileUrl": "https://alloymc.dev/@kestrel"
  },
  "uuid": "069a79f444e94726a5befca90e38aaf5"
}

GET/v1/minecraft/{uuid}/body.pngFull-body front render of a linked account

Parameter	In	About
`uuid` required	path
`s`	query	Width in pixels; the height is twice that.

200 PNG

GET/v1/minecraft/{uuid}/head.pngHead render of a linked account

Parameter	In	About
`uuid` required	path
`s`	query

200 PNG with the hat layer

Auth

How Alloy turns a browser sign-in into a token.

POST/v1/auth/tokenTrade a sign-in code for a token

Alloy opens https://alloymc.dev/auth/app?challenge=…&state=…&device=… in the browser (PKCE S256). After the person allows it, the browser returns to alloy://auth?code=…&state=…; Alloy posts the code and its verifier here. Codes last five minutes and work once.

Request body

{
  "code": "…",
  "verifier": "…"
}

200 A token, valid 90 days and renewed while used

{
  "token": "…",
  "tokenType": "Bearer",
  "user": {
    "handle": "elchi"
  }
}

DELETE/v1/auth/tokenSign this token outtoken

204 The token no longer works