Items
GET /v2/items
GET /v2/items/{id}
GET /v2/items/{id}/tooltip
Item definitions — over 2,400 rows from the game's design data. Patch-aware (see Patches).
List
curl 'https://api.darkerdb.com/v2/items?limit=25&rarity=rare&archetype=helmetbarbuta'
Query parameters
Identity / categorization:
| Name | Mode | Description |
|---|---|---|
id | exact | id.item.<slug> or raw Id_Item_<Name> |
archetype | exact | e.g. helmetbarbuta, swordoldlong |
name | substring | matches anywhere in the display name |
rarity | exact | poor, common, uncommon, rare, epic, legendary, unique, artifact |
type | exact | top-level item category |
armor_type | exact | for armor pieces |
hand_type | exact | for weapons |
misc_type | exact | for utility / misc |
slot_type | exact | equipment slot |
utility_type | exact | for utility items |
required_class | exact | class gate |
Range filters (integer):
| Name | Description |
|---|---|
min_required_knowledge, max_required_knowledge | knowledge gate |
min_gear_score, max_gear_score | gear score |
min_vendor_price, max_vendor_price | base merchant price |
min_adventure_points, max_adventure_points | AP yield |
min_experience, max_experience | XP yield |
min_max_stack_size, max_max_stack_size | stack cap |
min_primary_attributes, max_primary_attributes | primary attribute slot count |
min_secondary_attributes, max_secondary_attributes | secondary attribute slot count |
Behavior toggles:
| Name | Type | Description |
|---|---|---|
has_effect | bool | item has an on-use effect (true/false) |
patch | id|version|current | replay against a different patch |
Pagination: page (default 1), limit (default 25, max 250).
Response
{
"pagination": { "count": 25, "limit": 25, "page": 1, "num_pages": 14, "total": 342, "next": "..." },
"body": [
{
"id": "id.item.helmet_barbutashade",
"cursor": 1,
"archetype": "helmetbarbuta",
"name": "Barbuta Shade Helmet",
"rarity": "rare",
"patch_id": 9
}
]
}
Null fields are stripped from each row — the underlying table has 350+ columns, most are null for any given item.
Get
curl 'https://api.darkerdb.com/v2/items/id.item.helmet_barbutashade'
Same per-item shape, returned at body. Accepts the canonical envelope or the raw upstream key (Id_Item_Helmet_BarbutaShade). 404 on unknown id.
Tooltip
curl 'https://api.darkerdb.com/v2/items/id.item.helmet_barbutashade/tooltip?secondary[strength]=3:Ruby&found_by=Skullee' \
-H 'X-Api-Key: kf_xxxx_xxxxxxxxxxxxxxxxxxxx'
Display-shaped payload for the DDB tooltip library. Same id resolution as GET /v2/items/{id}, but the response is narrowed to just the columns the renderer needs — and the primary / secondary attribute ranges are pre-formatted as display strings ("Armor Rating 75", "+3 Strength").
Requires an API key (X-Api-Key header) with the tooltips scope. Origin-restricted keys check the caller's Origin against the allow-list registered on the dashboard.
Query parameters — instance overrides
Every parameter is optional. Use them to render a specific instance of an item rather than the base template.
| Name | Description |
|---|---|
primary[<attr>] | Override the displayed value for a primary attribute. <attr> is the snake-case attribute field (strength, armor_rating, move_speed, cooldown_reduction_bonus, …). |
secondary[<attr>] | Override the secondary roll. Append :GemName to attach a gem socket (e.g. secondary[strength]=3:Ruby). |
quantity | Stack size; rendered as ×N next to the name when greater than 1. |
found_by | Character who looted this instance. |
loot_state | Looted, Identified, Handled, … |
class | Class currently equipping the item. |
is_tradeable | true / false — toggles Tradeable / Bound footer. |
amount | Gold value for coin-pouch items. |
at_patch | Patch version to read the item template at. |
branch | Codex branch (default main). |
Response
{
"id": "id.item.helmet_barbutashade",
"name": "Barbuta Shade Helmet",
"rarity": "rare",
"archetype": "helmetbarbuta",
"slot_type": "Chest",
"armor_type": "Plate",
"gear_score": 224,
"description": "...",
"required_class": [ "Fighter", "Cleric" ],
"primary": [ "Armor Rating 75", "Magic Resistance 20", "Will 6" ],
"secondary": [
[ "+3 Strength", "Ruby" ],
[ "+2 Resourcefulness" ]
],
"found_by": "Skullee",
"is_tradeable": true
}
401 / 403 if the API key is missing, invalid, or its origins allow-list doesn't include the caller's Origin. 404 on unknown id.