Avatars
Image endpoints for player avatars, plus the icon catalog that powers the picker. To update the current user's avatar selection, see PATCH /v1/users/@me/avatar. For the full avatar model, see Avatars (platform).
Rendering
GET /v1/players/{id}/avatar
Render a player's avatar as SVG, or 302 to the provider CDN if the player uses a linked provider's image. Falls back to the auto-generated icon on provider failure.
- Auth: Public
Path params
| Field | Constraints |
|---|---|
id | integer. Player ID. |
Query params
| Field | Constraints |
|---|---|
size | integer, clamped to [16, 512], default 128. |
fallback | boolean. Preview the auto-generated icon regardless of the chosen source. |
v | any. Opaque cache-buster (ignored server-side; echoed in the canonical avatar_url on every player payload). |
Response — 200 OK (image/svg+xml) or 302 redirect.
Errors
| Code | Meaning |
|---|---|
404 | Player not found. |
GET /v1/avatars/icons/{slug}
Preview a specific game-icon with arbitrary colors. Deterministic for a given (slug, color, bg, size, border, shape) tuple and heavily cacheable. Used by the picker grid.
The icon author is metadata, not part of the URL — the slug is globally unique across the catalog. Fetch the available slug list via GET /v1/avatars/available.
- Auth: Public
Path params
| Field | Constraints |
|---|---|
slug | string, [a-z0-9._-]+. Icon ID from the manifest. |
Query params
| Field | Constraints |
|---|---|
color | optional. Palette key for the foreground glyph. See palettes.colors from /avatars/available. |
bg | optional. Palette key for the background fill. See palettes.bgs. |
border | optional. Palette key for an outer border ring. See palettes.borders. Empty string = no border. |
shape | optional. rect (default) or circle. |
size | integer, default 128. |
Response — 200 OK (image/svg+xml).
Errors
| Code | Meaning |
|---|---|
400 | color, bg, border, or shape not in a valid palette / not a known shape. |
404 | Icon not found. |
Catalog
GET /v1/avatars/available
Catalog for the picker. Returns the full icon manifest minus icons that other players have claimed, plus palette options. If mine is supplied, the caller's own icon is kept in the list (even though it's "claimed").
- Auth: Public
- Cache:
private, max-age=30
Query params
| Field | Constraints |
|---|---|
mine | integer (player id). Optional. |
Response — 200 OK
{
"icons": [
{ "author": "lorc", "slug": "dragon-head", "tags": [ "creature", "fantasy" ] }
],
"total": 4096,
"taken_count": 118,
"palettes": {
"colors": [ "crimson", "cyan", "amber", "emerald" ],
"bgs": [ "slate", "midnight", "cream" ]
}
}