Returns the wearable slots for a gender with counts.

{ "data": [ { "slot": "Hat", "count": 29 }, { "slot": "Shirt", "count": 23 }, … ] }

Without query params, returns the full catalog grouped by gender → category, plus a branding object (your app's saved Wardrobe theme). With gender (and optional category) returns a flat array of assets instead.

Every asset carries pooled — true when it sits in a pool (locked by default; needs a per-avatar unlock before it can be worn). Owned + enabled premium/epic assets are merged in too, additionally flagged premium:true.

pooled is app-level (“this asset needs an unlock”). To tell whether a specific avatar may wear it, combine it with that avatar's unlocks: locked = pooled:true and the id is not in GET /v1/avatars/:id/unlocks.

{ "data": [ {
  "id": "glb/Adult/Adlult_Male/Adult_Male_Hat_01.glb",   // use this in a recipe
  "name": "Hat_01", "slot": "Hat", "gender": "male",
  "url": "/assets/glb/Adult/Adlult_Male/Adult_Male_Hat_01.glb",
  "thumbnail": "/assets/thumbnails/…webp",
  "pooled": false,                                       // true → in a pool, needs a per-avatar unlock
  "draws": 1, "tris": 420, "size": 18342
} ] }

The clip library. Clips drive the 44-bone humanoid skeleton; they apply to rigged avatars and are played at runtime by the SDK/viewer. The set is platform-configurable, so custom clips may appear alongside the built-ins.

{ "data": [ { "id":"walk","name":"Walk","type":"mixamo","loop":true,"inPlace":true,"file":"Walking.fbx" }, … ] }

Every enabled clip merged into a single binary glTF: one shared humanoid skeleton + each clip as a named animation. Load this one file instead of fetching the list and each clip separately. Revalidated by ETag — it updates automatically whenever the app's enabled clips change.

GET /v1/animations.glb   →   model/gltf-binary   (one GLB, N named animations)

201 Created
{ "data": { "id":"…","gender":"male","recipe":{…},"status":"draft","currentBuildId":null,
            "portraitUrl":"https://…/portraits/….webp" } }

portraitUrl is rendered server-side on create; it is null if the render failed (never fatal).

Generate a randomised avatar. Every result has a complete base outfit — Body, Face, Hair, Shirt, Pants, Shoes — plus a few random accessories (Glasses, Beard, Mustache, Gloves, Mask, Belt, Bracelet, Necklace, Chain, Watch, each ~40%). Honours the layering rules: no conflicting items are added (no Hat over Hair, no extra top over the Shirt, no extra bottom over the Pants). Picks only from assets enabled for your app, and excludes pooled (locked‑by‑default) assets — a new avatar has no unlocks, so random never equips an item it couldn't build. Creates a draft (1 credit) — call build to render the GLB.

201 Created
{ "data": { "id":"…","gender":"female","recipe":{ "Body":"…","Face":"…","Hair":"…","Shirt":"…","Pants":"…","Shoes":"…","Glasses":"…" },
            "status":"draft","currentBuildId":null,"portraitUrl":"https://…/portraits/….webp" } }

Returns 422 insufficient_assets if a required slot has no enabled, non‑pooled assets for the app.

The raw avatar record (recipe, status, current build id).

The resolved current config: each slot with its full asset detail, the rig type, and the current GLB. This is what a game client reads to render or equip the avatar.

{ "data": {
  "avatarId":"…","gender":"male","rig":"humanoid-static","status":"published",
  "recipe":{ "Body":"…","Shirt":"…" },
  "slots":[ { "slot":"Body","assetId":"…","asset":{ "name":"Body_01","url":"…","thumbnail":"…" } } ],
  "glbUrl":"http://localhost:8787/builds/….glb"
} }

All avatars for your app, newest first.

Change the recipe, name or metadata. Re-build to produce a new GLB.

Removes the avatar and its builds.

Each publish saves a revertable version (recipe + build + portrait).

{ "data": [ { "id":"…","version":3,"recipe":{…},"gender":"male","name":"…","buildId":"…","glbUrl":"…","portraitUrl":"…","createdAt":1720000000000,"isCurrent":true }, … ] }

Restore a previous version as the current one (its recipe, build and portrait).

Assembles the recipe's parts, merges by material, compresses textures (WebP) and geometry (Draco) → one optimised GLB at a stable URL. Identical recipes are de-duplicated (returns the existing build with reused:true).

{ "data": {
  "id":"…","status":"completed","url":"http://localhost:8787/builds/….glb",
  "drawsBefore":6,"drawsAfter":3,"sizeOut":52160,"animations":[],"animationMode":"none"
}, "reused": false }

Build history for the avatar (newest first).

Convenience: 302-redirects to the avatar's current GLB. If no build exists yet, it builds one on demand. Point your loader straight at this URL.

const gltf = await new GLTFLoader().loadAsync(
  `http://localhost:8787/v1/avatars/${id}/glb?` + new URLSearchParams({}), // send x-api-key via fetch loader
);

Set the avatar's thumbnail (portraitUrl) yourself. Create, random and a recipe update already render one server-side and return it on the response — POST here only to override that with your own capture (e.g. a face crop from your game camera). Build does not re-render one. Keyed to the current build, so each published version keeps its own face.

{ "data": { "portraitUrl": "https://…/portraits/….webp" } }

List this app's pools and their asset ids. Only enabled assets are returned — a disabled free asset or inactive premium/epic is omitted, so it is never offered to unlock.

{ "data": [ { "id":"…", "name":"Season 1", "items":[ "glb/Adult/…/Hat.glb", "premium/<uuid>.glb" ] } ] }

The asset ids currently unlocked for this avatar.

{ "data": [ "premium/<uuid>.glb" ] }

Unlock one or many pooled assets for this avatar so its user can wear them. Idempotent — re-unlocking is a no-op.

curl "$BASE/v1/avatars/$AV/unlocks" -X POST -H "x-api-key: $KEY" \
  -H "content-type: application/json" \
  -d '{ "assetIds": ["glb/Adult/…/Hat.glb", "premium/<uuid>.glb"] }'

{ "data": { "avatarId":"…", "unlocked":[ "glb/Adult/…/Hat.glb", "premium/<uuid>.glb" ] } }

Re-lock assets for this avatar. Same body shape (assetIds or assetId).

{ "data": { "avatarId":"…", "relocked":[ "premium/<uuid>.glb" ] } }

Unlocks this avatar's user has not been shown yet. Each item is returned once and then marked seen, so you can drive a “new item!” badge without tracking state yourself.

{ "data": [ { "id":"premium/<uuid>.glb", "name":"Crown", "thumbnail":"/premium/thumbnails/….webp" } ] }

How many enabled items the pool holds. Pair it with the avatar's unlocks to show “7 / 20 collected”.

{ "data": { "poolId": "…", "total": 20 } }

Unlocks one random un-owned item from the pool for this avatar.

{ "data": {
  "granted": { "id":"premium/<uuid>.glb", "name":"Crown", "thumbnail":"…", "category":"Hat", "gender":"male" },
  "exhausted": false,
  "poolTotal": 20
} }

exhausted:true with granted:null means the avatar already owns every enabled item in the pool. Unknown pool, or a pool belonging to another app, returns 404 not_found.

Mint a 15-minute, single-avatar edit token (server-to-server). Hand it to the browser/Wardrobe.

{ "data": { "token":"eyJ…","expiresIn":900,"sessionStart":1782…,"avatarId":"…" } }

Refresh before expiry. Enforced absolute session cap: 8 hours — after that, re-mint with sk_.

Apply a look with a valid edit token and rebuild. Used by the Wardrobe; you can call it directly too. The request must come from a whitelisted origin.

{ "data": { "avatarId":"…", "build": { "id":"…","url":"…","status":"completed" } } }

Fails with 403 assets_locked if the look contains a pooled item this avatar has not unlocked, and 422 not_decent if it is missing required clothing.

The token avatar's version history — the same payload as GET /v1/avatars/:id/versions, but readable from the browser with a publishable key + edit token instead of an sk_.

Revert the token avatar to one of its versions from the browser. Same effect as the sk_ revert; no rebuild is downloaded.