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

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

Private preview

Developer access is invite-only.

The Styllar API is in private preview. Request access and we’ll reach out when your keys are ready.