StyllarBeta
Start Building
Developers

The Styllar API

Pull the Styllar item library straight into your app (the same hand-drawn parts our builder uses) and let people (or your AI agents) build avatars with them.

ITEMS API · LIVE/api/v1

Open preview: the read endpoints are live and need no key. Avatar generation, keys and MCP are next.

the item library · live LIVE
GET https://…/api/v1/items?category=Head
{ }
TOYroll an avatar from the API
loading…
curlrun it yourself
curl /api/v1/items?category=Head&limit=3

Embed · the builder in your product

Give every user an avatar in two lines

Mount the full Styllar builder in your page. Your user composes an avatar; you receive a permanent 64-character hash to store — display it anywhere with the .png route, no compositing, no image storage on your side.

<script src="https://styllar.com/embed/v1.js"></script>
<script>
  Styllar.mount('#avatar-builder', {
    key: 'styllar_pk_...',                       // publishable key — safe in page source
    appearance: { accent: '#7C3AED', radius: 12 }, // match your brand
    onSave: (hash) => saveToYourBackend(hash),   // 64 chars, permanent
  });
</script>

Publishable keys are origin-locked and can only register avatars — request one via the Developers & API contact. Pass hash to preload an existing avatar for editing. Below: the real thing, mounted with our own SDK.

Live demo unavailable: set NEXT_PUBLIC_STYLLAR_PK (run scripts/seed-internal-key.mjs).

What you can build

Fetch the item libraryLive

Pull Styllar’s hand-drawn parts (hair, clothing, accessories, backgrounds and more) into your own app.

Render your own wayLive

Every item ships as layered art (z-index + PNG URLs). Stack them to draw an avatar however you like.

Filter by category & planLive

Query the catalog by category or free/premium plan, and page through with limit + offset.

Generate & customizeSoon

Create an avatar from a seed or a set of items, then equip and remove pieces.

MCP-readySoon

Let AI agents browse items and manage their own avatars through the Model Context Protocol.

WebhooksSoon

Subscribe to events (avatar created, updated) to keep your systems in sync.

Reference · the item library

Serve Styllar items to your app

Pull the catalog of hand-drawn parts and their layer artwork, so another app can let people build Styllar avatars with your items. Live now, no key required.

EndpointsLive
GET/api/v1/itemsList items (filter: category, plan, limit)
GET/api/v1/items/:idAn item + its layer artwork
GET/api/v1/categoriesThe category taxonomy

Conventions

Everything you can assume about every endpoint.

Base URL
/api/v1
Relative to this deployment. A vanity api.styllar.com base comes later.
Auth
none (preview)
Read endpoints are open, with no API key needed yet. Keys arrive with the write/avatar endpoints.
Format
application/json
List endpoints wrap results in { object, count, total?, data }. Single items return { object, data }.
Pagination
limit · offset
limit defaults to 100 (max 500); offset defaults to 0. total is the count before paging.
CORS
*
Access-Control-Allow-Origin: *. Call it from a browser on any origin.
Caching
~30s
Responses carry a short cache window; item art is served from a public bucket.

The Item object

Returned by the item endpoints.

id
string
Stable unique id (UUID). Use it with GET /items/:id.
name
string
Human-readable item name, e.g. “Cowgirl”.
category
string
Category name, one of GET /categories.
rarity
string
Common, Rare, Epic or Legendary.
plan
string
free or premium.
layers
Layer[]
Render layers, lowest z first.
conflictCategories
string[]?
“Cannot contain”: categories this item can’t be worn with (e.g. a mouth that includes the nose forbids Nose). Omitted when empty.
blockedBodyTypes
string[]?
Body types this item can’t sit on, e.g. ["human"]. Omitted when empty.
bodyType
string?
For Body items only: the body’s own type (human or monkey).

When composing an avatar, respect these: skip items whose blockedBodyTypes include the body you picked, and when an item lists conflictCategories, leave those categories out. (The roll toy above does exactly this.)

Layer

z
number
z-index. Stack ascending, so a higher z sits in front.
url
string
Public PNG URL. Paint it to fill a square frame.

To draw an item, or a whole avatar, gather every layer, sort by z ascending, and paint each url onto the same square canvas at full size.

GET/api/v1/itemsLive

List items, newest catalog first. Filter and page with the query parameters below.

Query parameters

category
string
Optional
Filter to one category (case-insensitive), e.g. Head.
plan
string
Optional
free or premium.
limit
integer
Optional
Max items to return. 1 to 500, default 100.
offset
integer
Optional
Items to skip, for paging. Default 0.

Request

GET /api/v1/items?category=Head&limit=1

Response

200application/json
{
  "object": "list",
  "count": 1,
  "total": 90,
  "data": [
    {
      "id": "75b33e85-9471-4fee-982e-f2c762f99540",
      "name": "Cowgirl",
      "category": "Head",
      "rarity": "Common",
      "plan": "free",
      "layers": [
        { "z": 10,  "url": "https://…/parts/head/…-back-…hair.png" },
        { "z": 110, "url": "https://…/parts/head/…hair.png" }
      ]
    }
  ]
}

GET/api/v1/items/:idLive

Fetch a single item and its layers by id.

Path parameters

id
string
Required
The item id from a list response.

Request

GET /api/v1/items/75b33e85-9471-4fee-982e-f2c762f99540

Not found

404application/json
{
  "error": {
    "type": "not_found",
    "message": "No item with id 'xyz'."
  }
}

Response

200application/json
{
  "object": "item",
  "data": {
    "id": "75b33e85-9471-4fee-982e-f2c762f99540",
    "name": "Cowgirl",
    "category": "Head",
    "rarity": "Common",
    "plan": "free",
    "layers": [
      { "z": 10,  "url": "https://…hair.png" },
      { "z": 110, "url": "https://…hair.png" }
    ]
  }
}

GET/api/v1/categoriesLive

The category taxonomy, with a live item count per category.

The Category object

name
string
Category name. Pass it as the category filter on GET /items.
baseZ
number
Base z-index items in this category render at.
count
number
Number of selectable items in the category.

Request

GET /api/v1/categories

Response

200application/json
{
  "object": "list",
  "count": 14,
  "data": [
    { "name": "Body", "baseZ": 50,  "count": 8 },
    { "name": "Eyes", "baseZ": 100, "count": 33 },
    { "name": "Head", "baseZ": 110, "count": 90 }
  ]
}

Errors

Failures return a non-2xx status and an error object with a stable type and a human-readable message.

404
not_found
No resource matches the id you requested.
500
internal_error
Something went wrong on our side; safe to retry.

Avatars

Generate, customize, retrieve

Create an avatar and manage it over its lifetime, from a random seed or a specific set of items. Today you can compose one client-side from the items API (see the roll toy above); managed avatars land next.

EndpointsSoon
POST/api/v1/avatarsGenerate a new avatar
PATCH/api/v1/avatars/:idCustomize (equip / remove items)
GET/api/v1/avatars/:idRetrieve: PNG · SVG · JSON

MCP

Native tools for AI agents

Styllar will be MCP-ready, so an AI agent can browse items and manage its own identity without glue code: the same catalog, exposed as tools.

ToolsSoon
MCPstyllar.list_items()Browse the item library
MCPstyllar.create_avatar()Generate an avatar
MCPstyllar.update_avatar()Equip / remove items

Building the rest with you

API keys, avatar generation, PNG/SVG rendering, webhooks and MCP are next. Building on the items API or have a use case? Tell us what you need and we’ll prioritize it.

Get in touch