Public API

Read-only JSON over the public cosmetics catalog: the same items any client on the network can already draw. Nothing private, nothing per player, no storage locations.

open: no key neededcached at the edge for 5 minutes, revalidated in the backgrounda descriptive User-Agent is required

User-Agent

Every request must name your tool and a way to reach you, or it is refused with 400:

http

User-Agent: mytool/1.0 (+https://example.com)
User-Agent: skinviewer/2.3.1 ([email protected])

Generic agents (browsers, curl, python-requests, default HTTP libraries) are refused. Set your own.

Limits

120 requests per minute per address; past that you get 429 with retry-after.
Responses carry an etag. Send it back as If-None-Match and an unchanged catalog costs you a 304.
Files are content-addressed and never change: cache them forever.
Need a higher limit for a real project? Email [email protected] with what you are building and the volume you expect.

Endpoints

[GET]/api/v1/cosmeticsevery public cosmetic

json

{
  "data": [
    {
      "client": "example",
      "id": "dusk-cape",
      "name": "Dusk",
      "slot": "cape",
      "render": "texture",
      "version": 2,
      "params": {},
      "files": [
        {
          "role": "texture",
          "media_type": "image/png",
          "size": 5939,
          "hash": "b78344dbc7c4…",
          "url": "https://asphodel.wtf/assets/b78344dbc7c4…"
        }
      ]
    }
  ],
  "count": 1
}

[GET]/api/v1/cosmetics/:client/:idone cosmetic

{ "data": { … } }, or 404 when it does not exist or is not public.

[GET]/api/v1/statscounts over the public catalog

Totals plus breakdowns by client, slot and render kind.

json

{
  "data": {
    "items": 42,
    "clients": 4,
    "files": 57,
    "bytes": 1048576,
    "byClient": [{ "key": "example", "count": 12 }],
    "bySlot": [{ "key": "cape", "count": 20 }],
    "byRender": [{ "key": "texture", "count": 30 }]
  }
}

[GET]/assets/:hasha file, by its BLAKE3 hash

Only files that belong to a listed public cosmetic are served. Guessing hashes gets you 404. Sounds are never served or listed here; clients load them from their own hosts.

Errors

status	meaning
`400`	bad User-Agent or bad filter; the body says which
`404`	no such cosmetic, or the API is off on this instance
`429`	slow down; see `retry-after`
`503`	the catalog is unreachable right now

Errors are { "error": "…" }.

Fine print

Using the API means accepting the terms. Cosmetics belong to the clients that publish them; ask them before reusing artwork. Asphodel is independent of the clients on its network.