JSON API

Updated 24 October 2026

The data behind these pages, for bots, launchers and community sites. Free to use; no key needed.

Ground rules

Plain GET requests, JSON responses (UTF-8, non-ASCII escaped), Access-Control-Allow-Origin: *.
Caching. Live data is rebuilt at most every 5 seconds and /api/stats at most every 60 seconds; asking more often returns the same data. Polling every 15-30 seconds is plenty.
Rate limit. About 2 requests per second per address with bursts of 60; beyond that you get 429 Too Many Requests with Retry-After.
Public data only. Nicknames, game names, map, mode, version and counts, and the heroes in the party vault. No IP addresses, e-mails, account ids or anything else that identifies a player beyond the nickname they chose to show in the game.
Strings come from players: treat them as untrusted and escape them when you display them.
Times are Unix timestamps (seconds, UTC).

`GET /api/status`

Service health and headline counts.

{"server": "use1.dsii.uk", "time": 1792700000, "all_up": true,
 "services": [{"name": "Chat (peerchat)", "protocol": "TCP", "port": 6667, "up": true}, ...],
 "players": {"chat": 5, "signed_in": 2, "in_games": 4},
 "games": 2,
 "lobbies": {"portals_in_use": 2, "staging_rooms": 1},
 "relay": {"hosts": 1, "connections": 2}}

players.chat: nicknames connected to the chat server (everyone in Internet or GameSpy mode).
players.signed_in: GameSpy-mode account logins.
players.in_games: the sum of the player counts the hosted games report.
relay: hosts registered with the relay and joiner connections going through it.

`GET /api/games`

Games in the server list, most players first.

{"time": 1792700000, "games": [
  {"name": "Friday co-op", "map": "ds2_world", "state": "playing", "mode": "4x1", "mode_name": "",
   "heroes_per_player": 1, "players": 2, "max_players": 4, "password": false,
   "version": "2.30.0.4277", "edition": "Broken World", "portal": "Agarrus", "network": "Internet"}]}

state: staging (waiting in the staging room), playing, or unknown.
mode: players × heroes each, e.g. 4x1, 3x2, 8x1 (mode_name "Old School Mode"), 6x2 ("Couples Mode++").
edition: Broken World when the game reports Broken World's version 2.30.0.4277, Dungeon Siege II for other versions, unknown before the host has reported one.
network: Internet or GameSpy, the mode whose portal the game was hosted from.

`GET /api/lobbies`

Who is where.

{"time": 1792700000, "chat_users": ["Arden", "Valdis"],
 "portals": [{"name": "Agarrus", "network": "Internet", "groupid": 1, "players": ["Arden"], "games": 1}, ...],
 "staging_rooms": [{"players": ["Arden", "Valdis"]}],
 "other_rooms": {"rooms": 0, "players": 0}}

Staging rooms are listed without their names (the names encode the host's addresses). Other chat rooms are only counted.

`GET /api/stats?range=24h|7d|30d`

Totals, peaks and history. range defaults to 24h.

{"time": 1792700000, "range": "24h", "bucket_seconds": 900, "recording_since": 1792600000,
 "totals": {"accounts": 9, "profiles": 9, "vault_profiles": 9,
            "parties": {"ds2": 3, "broken_world": 1},
            "stats_records": {"newgame": 0, "updgame": 0},
            "games_hosted": {"total": 12, "last_24h": 3, "last_7d": 12, "last_30d": 12,
                             "by_edition": {"Dungeon Siege II": 10, "Broken World": 2},
                             "by_mode": {"4x1": 11, "8x1": 1}}},
 "peaks": {"chat": {"value": 7, "time": 1792650000}, ...},
 "series": {"chat": [[1792613700, 2], [1792614600, null], ...], "signed_in": [...], "in_games": [...],
            "games": [...], "relay_hosts": [...], "relay_conns": [...]}}

series: one point per bucket (bucket_seconds: 15 minutes for 24h, 2 hours for 7d, 6 hours for 30d) with the highest minute sample in that bucket; null where nothing was recorded (server down).
games_hosted: each game in the server list counted once, when it first reports its version (a server restart can count a running game twice).
parties: the party counts in the accounts' vault indexes.
stats_records: game-stats reports received from hosts (the game sends these only if its host stats reporting is enabled, which has not been observed so far).

`GET /api/armory/characters`

The heroes in the online party vault (the Armory), highest level first. Rebuilt from the vault at most once a minute. Optional parameters: q (part of a character, party or player name), class (e.g. Sorceress), edition (ds2 or bw), min_level, max_level, sort (level, name or updated), page, per_page (up to 200, default 50).

{"time": 1792700000, "total": 16, "page": 1, "per_page": 50, "characters": [
  {"id": "e5w5so6zxrferq6h-0", "name": "Alanna", "class": "Sorceress", "level": 39, "party": "Alanna",
   "party_id": "e5w5so6zxrferq6h", "edition": "Broken World", "world": "Dungeon Siege II",
   "difficulty": "Mercenary", "player": "Arden", "updated": 1792690000}, ...]}

id: the character's page is /armory/character/<id>. Ids stay the same while the party keeps its vault slot; they cannot be turned back into account data.
player: the in-game nickname of the account that uploaded the party. updated: when the party was last uploaded.

`GET /api/armory/character/<id>`

Everything on a character page: level, class, attributes (Strength, Dexterity, Intelligence), skills (Melee, Ranged, Combat Magic, Nature Magic), powers_and_skills, gold, health and mana at the last save, location, equipment (slot and item: name, base, level, quality, modifiers with their effects), spellbook, inventory (items with a count), teleporters per difficulty, and party with its members and progress per difficulty (unlocked, completed, quests, furthest act, places discovered, monsterbook entries). Unknown ids answer 404 with {"error": "not found"}.