Source: https://dsii.uk/api

# JSON API

Updated 23 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. 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).