Items API

A public, read-only HTTP API for anybody building on Animal Jam. It lists the game's clothing, den items and pets as the game's own def packs describe them. It gives you each item's colours, and it draws a PNG of any item in any colour. You don't need a key or an account, and CORS is open, so a page on any site can call it.

Every address on this page starts at https://api.phantm.site.

Attribution

Animal Jam item names and art © WildWorks. Phantom isn't affiliated with, endorsed by or connected to Animal Jam or WildWorks. Every JSON answer carries this line as attribution, and every picture carries it in the x-art-credit header. Show it wherever you show the art.

Endpoints

Endpoint	What it answers
`GET /v1/items`	A search over every item's English name, a page at a time.
`GET /v1/items/:kind/:defId`	One item, whole: its colours (clothing) or its versions (den items).
`GET /v1/items/:kind/:defId/image.png`	The item's picture, as a PNG, in any colour, version and size.
`GET /v1/items/palette`	The game palette: every colour a packed game colour can name, as `#rrggbb`.
`GET /v1/items/colours/:colourId`	A Phantom private server custom colour: its four layers and its den tint.

:kind is clothing, den-item or pet. A def id alone doesn't name an item: 1 is a Bean Bag Chair as a den item and a Pet Kitty as a pet.

JSON comes in Phantom's envelope: { "data": ... } on success, and { "error": { "code", "message" } } on a refusal, with the HTTP status to match.

Searching

GET /v1/items

Query	What it does
`q`	Words that must all be in the English name. The exact name comes first, then names starting with it.
`kind`	`clothing`, `den-item` or `pet`. Leave it out for all three.
`limit`	1 to 100 a page. 48 if you leave it out.
`cursor`	The `nextCursor` of the page before.
`page`	A page number, from 1, if you'd rather count pages than follow cursors.

Without q, the newest items (the highest def ids) come first.

Shell

curl 'https://api.phantm.site/v1/items?q=spiked%20collar&kind=clothing&limit=2'

JSON

{
  "data": {
    "items": [
      {
        "kind": "clothing",
        "defId": 634,
        "name": "Spiked Collar",
        "membersOnly": true,
        "slot": "neck",
        "layer": 7,
        "world": "land",
        "flags": { "new": false, "onSale": false, "giftable": true, "reward": null },
        "price": { "amount": 2000, "currency": "gems" },
        "image": "/v1/items/clothing/634/image.png"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 2,
    "nextCursor": null,
    "attribution": "Animal Jam item names and art © WildWorks. ..."
  }
}

Field	What it is
`slot`	Where a piece of clothing is worn: `head`, `neck`, `back`, `legs` or `tail`. `null` for anything else.
`layer`	The drawing layer the def pack puts it in. `null` for a pet.
`world`	`land`, `ocean` or `both`. `null` where the pack doesn't say.
`flags`	The shop's own badges, "new" and "on sale". `giftable` (clothing) and `reward` (pets) are `null` for other kinds. The packs have no rarity of their own.
`price`	What the shop charges, in `gems`, `diamonds` or `other`. `null` for no price.
`image`	The picture's path, in the item's default colour.

One item

GET /v1/items/:kind/:defId answers everything above, and also:

colours: for clothing, every colour the game offers it in, in the order its def lists them. Each colour has its packed value, the same number as hex, its four palette indexes, each layer as #rrggbb in layers, and the image of the item in that colour.
versions: for den items, the versions its art draws (the den shop's colour button steps through them). Each version has its number and its image.
availability: when the shop sells it, as ISO times. Both are null for an item with no window.

Shell

curl https://api.phantm.site/v1/items/clothing/634
curl https://api.phantm.site/v1/items/den-item/1

Pictures

GET /v1/items/:kind/:defId/image.png

Query	What it does
`colour`	Any colour, in any of the formats below. Leave it out for the item's default.
`version`	A den item's version, from its `versions`. Leave it out for its first.
`size`	The side of the square, 16 to 512. 192 if you leave it out. Art smaller than half the square is enlarged a whole number of times, so it stays crisp.

Shell

curl -o collar.png 'https://api.phantm.site/v1/items/clothing/634/image.png?colour=0x23370000'
curl -o collar.png 'https://api.phantm.site/v1/items/clothing/634/image.png?colour=7b2ff7,f72f8a,2fd0f7,ffffff&size=384'
curl -o chair.png 'https://api.phantm.site/v1/items/den-item/1/image.png?colour=3fa7ff'

How each kind is drawn:

Clothing is painted on request, the same way the game paints it. The icon is palette indexes, and the game's own rules build its palette from four colours. Any combination works, not only the colours the item is sold in.
Den items come from Phantom's item pictures, which hold each item in its first version. A den item in a custom colour or a rrggbb colour is tinted the way the game tints one. Asking for any other version answers 404 NO_PICTURE until a picture of that version exists.
Pets come from Phantom's item pictures, in one colour.

The palette

GET /v1/items/palette answers { size, colours }. colours[i] is palette entry i as #rrggbb. A packed game colour is four of these indexes, so with the palette you can draw any combination yourself.

Custom colours

GET /v1/items/colours/:colourId takes a Phantom private server custom colour's number, written in decimal or as 0x and eight hex digits.

Shell

curl https://api.phantm.site/v1/items/colours/0xfd000001

JSON

{
  "data": {
    "id": 4244635649,
    "hex": "0xfd000001",
    "layers": ["#ff0000", "#00ff00", "#0000ff", "#ffffff"],
    "tint": {
      "blend": "tint",
      "strength": 100,
      "hue": 0,
      "saturation": 0,
      "brightness": 0
    }
  }
}

It answers a colour's four layers and how a den item takes it (tint: a blend, a strength of 0 to 100, and a hue, saturation and brightness adjustment of the art). It never says who made the colour.

Colour formats

?colour= accepts three formats:

Format	Example	What it is
Packed game colour	`0x23370000` or `590807040`	Four game palette indexes in one number, one a layer, top byte first: layer 1 is index `0x23`, layer 2 is `0x37`. This is what a def pack's `colors` and a player's clothing carry. Clothing only.
Custom colour id	`0xfd000001` or `4244635649`	A Phantom private server custom colour (top byte `0xFD`): four colours of its own and a den tint.
Your own colours	`ff0000` or `ff0000,00ff00,0000ff,ffffff`	One `rrggbb` for all four layers, or four, comma separated. A `#` before each is allowed, written `%23` in a URL. A den item is tinted by the first.

A den item takes no packed game colour, because its versions are its own drawings, so ask for a version instead. A pet takes no colour.

In JavaScript

JavaScript

const API = 'https://api.phantm.site';

const { data } = await fetch(`${API}/v1/items?q=collar&kind=clothing`).then((r) =>
  r.json()
);
for (const item of data.items) {
  const img = document.createElement('img');
  img.src = `${API}${item.image}?size=96`;
  img.alt = item.name;
  document.body.append(img);
}

const collar = await fetch(`${API}/v1/items/clothing/634`).then((r) => r.json());
const swatches = collar.data.colours.map((colour) => ({
  layers: colour.layers,
  picture: `${API}${colour.image}`,
}));

Phantom's own code uses @phantom/api-client/items, which gives you list, item, palette, customColour and imageUrl(client, kind, defId, { colour, version, size }).

Caching

Pictures have an address that names everything they show, so they never change: Cache-Control: public, max-age=31536000, immutable, with an ETag. Send If-None-Match and a copy you already hold is answered 304 without being drawn again. The API keeps every picture it draws in memory too, so asking for a popular one is cheap. x-cache: hit says it was kept.
JSON may be kept for an hour (public, max-age=3600). A custom colour may be kept for a day.
Refusals are never cached (no-store).

Nothing of Animal Jam's is stored by Phantom. The def packs, the palette and the clothing icons are fetched from Animal Jam's content network when they're needed and kept in memory only. The den item and pet pictures are the same public files Phantom's website shows.

Limits

From one address:

JSON: 120 requests a minute.
Pictures: 600 a minute. Only 30 of those may be pictures the API hasn't drawn yet. A picture it already holds never counts against the 30.

Past a limit, you get 429 with error.code RATE_LIMITED. Wait for the minute to turn over before asking again.

Errors

Status	`error.code`	When
400	`FST_ERR_VALIDATION`	A query or path the route doesn't take: a `limit` over 100, an unknown `kind`.
400	`BAD_COLOUR`	A colour none of the formats reads, or one the item can't take.
400	`BAD_VERSION`	A `version` on an item that isn't a den item.
400	`BAD_CURSOR`	A `cursor` this API didn't hand out.
404	`UNKNOWN_ITEM`	Animal Jam has no such item of that kind.
404	`UNKNOWN_VERSION`	The den item doesn't come in that version.
404	`UNKNOWN_COLOUR`	Nobody has made that custom colour.
404	`NO_PICTURE`	There's no picture of it yet: clothing with no icon, or a den version nobody has drawn.
429	`RATE_LIMITED`	Past a limit above.
503	`ITEMS_UNAVAILABLE`	Animal Jam's files couldn't be reached just now. Try again soon.

What isn't here

There's nothing about any player or account. The private server's own custom items aren't listed, whether they're published or still in review. Custom colours appear only as their colours.

Items API ​

Endpoints ​

Searching ​

One item ​

Pictures ​

The palette ​

Custom colours ​

Colour formats ​

In JavaScript ​

Caching ​

Limits ​

Errors ​

What isn't here ​

Items API

Endpoints

Searching

One item

Pictures

The palette

Custom colours

Colour formats

In JavaScript

Caching

Limits

Errors

What isn't here