Items API

About

The items API exposes the game's item prototype data over HTTP. It uses the GET method, returns JSON, and is read-only. There are no write operations. The HTML pages under /items render the same data for browsing; this API is the interface for programmatic access.

The API is unversioned and served under /api. Responses may gain fields over time. Existing fields are not renamed or removed without notice; clients should ignore fields they do not recognize.

Authentication

None. All endpoints are public and read-only. No key, token, or session is required.

URI structure

Resource URIs have the form:

https://theforsakenlands.com/api/items/{resource}

Requests

All requests are GET over HTTPS. Parameters are supplied in the query string and, unless stated otherwise, are optional. Reserved characters in parameter values must be percent-encoded. Request bodies are ignored.

Parameters documented as csv take a comma-separated list, for example affects=hitroll,damroll.

Responses

Responses are JSON with Content-Type: application/json; charset=utf-8, indented with two spaces. Fields whose value is empty or zero may be omitted. Collection endpoints wrap their results in an envelope; single-item endpoints return the item object directly.

Pagination

The /api/items collection is paged at 50 items per page. The page parameter selects the page and is 1-indexed. The response envelope reports the paging state:

{
  "items": [ ... ],
  "page": 1,
  "total_pages": 3,
  "total": 118
}

total is the number of matches across all pages; total_pages is total divided by 50, rounded up.

Ordering

sort selects the field: name, level, type, or area. It defaults to level. order selects the direction, asc or desc, defaulting to asc.

Rate limiting

Requests to /api/items endpoints are limited per client address to 120 per minute (2 per second), with a burst allowance of 30. Requests over the limit receive 429 Too Many Requests with a Retry-After header in seconds and the body:

{
  "error": "rate limit exceeded",
  "retry_after_seconds": 3
}

Successful responses set Cache-Control: 60 seconds for searches, 300 for item detail, 600 for enums. Identical requests within that window may be served from cache without reaching the origin.

Errors

Errors return a JSON body of the form { "error": "message" } with the status code below. The 429 body additionally carries retry_after_seconds.

Resources

{
  "items": [
    {
      "vnum": 3021,
      "name": "sword long",
      "short_desc": "a long sword",
      "item_type": "weapon",
      "item_type_num": 5,
      "level": 18,
      "weight": 120,
      "cost": 500,
      "condition_pct": 100,
      "wear_flags": "take wield",
      "area_name": "Midgaard",
      "value1": 5, "value2": 3, "value3": 6,
      "weapon_class": "sword",
      "damage_noun": "slash"
    }
  ],
  "page": 1,
  "total_pages": 3,
  "total": 118
}

{
  "vnum": 3021,
  "name": "sword long",
  "short_desc": "a long sword",
  "item_type": "weapon",
  "level": 18,
  "weight": 120,
  "cost": 500,
  "area_name": "Midgaard",
  "affects": [
    { "apply_type": "hitroll", "modifier": 2, "where": 0 },
    { "apply_type": "damroll", "modifier": 2, "where": 0 }
  ],
  "resets": [
    {
      "reset_type": "give",
      "mob_vnum": 3005,
      "mob_name": "a city guard",
      "area_name": "Midgaard"
    }
  ],
  "progs": []
}

{
  "vnum": 3021,
  "name": "sword long",
  "short_desc": "a long sword",
  "item_type": "weapon",
  "level": 18
}

{
  "item_types": ["armor", "weapon", "potion", "wand"],
  "affect_types": ["hitroll", "damroll", "strength"],
  "weapon_classes": ["sword", "axe", "mace"],
  "weapon_flags": ["flaming", "sharp"],
  "damage_nouns": ["slash", "pierce", "pound"],
  "areas": ["Midgaard", "The Frost Giant Vault"],
  "extra_flags": ["glow", "hum", "magic"],
  "class_restrictions": [],
  "race_restrictions": []
}

Item fields

Fields present on an item object. Empty or zero values may be omitted.