API Manual
A read-only JSON API over the game's items and materials. No key is needed, and any website may call it.
Basics
- Base URL:
- Every response is JSON. The data comes from the latest game export, so it changes when a new export is uploaded.
- Responses are cached for up to a minute.
- The limit is 600 requests per minute across all callers. Requests beyond that get
429. - Names and descriptions are in English.
Collections
| Collection | Contents | Entries now |
|---|---|---|
items | Every item in the game. | |
materials | The fabrics, leathers, metals and woods that customizable items are made from. |
GET /api lists the collections that exist.
Endpoints
Search a collection
GET /api/{collection}
Returns the total number of matches and one page of results. Each result has id, slug, name, type, tag and rarity.
{
"total": 42,
"results": [
{ "id": "…", "name": "Bandages", "type": "ConsumableTemplate", "tag": "Consumable", "rarity": "Common" }
]
}
Get one entry
GET /api/{collection}/{id}
Returns the full record: the fields above plus slug, description and data, which holds all the details.
The id can be the entry's id or its slug, a readable name such as barbute. Entries that share a name get a short id added to the slug, like barbute-6a68. The id never changes, but a slug follows the name, so link to the id if you need a permanent link.
Filter values
GET /api/{collection}/facets
Returns every distinct tag, rarity, type and stat bonus (modifier) in the collection.
Id to name lookup
GET /api/{collection}/names
Returns an object that maps every id to its name. Recipes and other records refer to items by id, so this is how you turn those into names.
Search parameters
| Parameter | Meaning |
|---|---|
q | Words to look for in the name and description. Every word must match, in any order. |
tag, rarity, type | Exact match, ignoring case. Repeat the parameter to allow several values: rarity=Rare&rarity=Epic. |
min_<field>, max_<field> | A number range on any numeric field, for example min_value=100 or max_mass=2. |
<field> | Any other top-level field of data works as an exact match, for example width=2. |
modifier | Items that give a stat bonus, for example modifier=MaxHealth. The values are listed by the facets endpoint. |
ingredient | Items crafted from a given item. Use the item's name or id. |
sort | The field to sort by. The default is name. Entries without that field come last. |
order | asc (default) or desc. |
limit | Results per page. The default is 50 and the maximum is 200. |
offset | How many results to skip, for the next page. |
since | Only entries added or changed after this revision. See Tracking changes. |
Anything that isn't a whole number in limit or offset gives 400. An unknown collection or id gives 404.
Examples
Data version
GET /api/meta
Returns the game version the data was exported from, the date it was exported (exportedAt) and the current revision.
Tracking changes
The data can be updated several times per game version, so version alone is not enough to detect changes. Instead, every update that adds, changes or removes an entry raises a single counter, the revision. Entries keep the revision they last changed in.
GET /api/meta poll this, it is tiny
GET /api/items?since=41 only items added or changed after revision 41
GET /api/materials?since=41
Remember the revision from /api/meta. When it is higher than yours, ask each collection for since=<your revision> and store the new number. Nothing is returned for entries that did not change, so nobody has to read the whole database.
Every entry also has introduced (the game version it first appeared in), updated (the game version it last changed in) and revision. To list what a version added: ?introduced=0.5.2. Removed entries are not listed, they simply disappear. Tracking started with the first export after this feature, so everything older shows that version as introduced.
Item records
| Field | Meaning |
|---|---|
id | Stable id of the item. |
slug | A readable id made from the name, such as barbute. It follows the name if the item is renamed. |
name, description | Display name and tooltip text. |
type | The kind of item, such as ConsumableTemplate or AttireTemplate. |
tag | The item's category, such as Consumable or Helmet. |
rarity | Common, Notable, Rare, Epic or Legendary. It is Varies for items whose rarity depends on their material or parts. |
configurable | true when the item is built from a material or from parts, so its real stats depend on those. |
materialCategory | Only on customizable items: Fabric, Leather, Metal or Wood. It tells you which materials the item can be made from. |
data | The details: size, mass, value, durability, stat bonuses (modifiers), recipes, recycling and anything specific to the kind of item. |
The contents of data mirror the game's own item data. They differ per item type and may change between game versions, so treat the field names there as unstable.
Material records
| Field | Meaning |
|---|---|
id, slug, name, description | As for items. |
type, tag | Both are the kind of material: Fabric, Leather, Metal or Wood. Items name the kind they use in materialCategory. |
rarity | The material's rarity. Items made from it take this rarity. |
data.valueMultiplier | Multiplies the base value of an item made from the material. |
data.modifiers | Stat bonuses the material gives. |
data.resistances | Damage multipliers, where 0.8 takes 20% off that damage type. |
data.entries, data.tools | The base requirements to craft one unit of the material's items. |
data.recycleEntries | What an item made from it returns when recycled. |
other data fields | Properties specific to the kind, such as hardness or padding. |
Values you can filter by
These lists come straight from the live data, so they are always current.
Materials and rarity
Customizable items such as armour, shields and weapon parts have no fixed rarity. Their rarity, value, bonuses and resistances come from the material they are made from. The item records give the base values, and a material record changes them like this:
- Rarity is the material's
rarity. - Value is the item's base
valuemultiplied by the material'sdata.valueMultiplier. - Bonuses from the material's
data.modifiersare added to the item's own. - Resistances in
data.resistancesmatter for armour. Each entry'smultiplierscales incoming damage of that type, so0.8is 20% resistance.
The item database page has a preview selector that does this calculation for you, and the materials page lists every material with its bonuses.
Using it from a website
const response = await fetch("/api/items?q=bandage");
const { total, results } = await response.json();