Overview
How other software reads data from the hub - keys, categories and limits.
Everything outside the web app reads the hub through its read-only REST API. The API is
pull-only: poll /snapshot for current state and follow the /events cursor for new events. There
are no webhooks.
OSRS Guild Map
A live map of every online guild member. Self-hosted with Docker, fed by a service key.
Build your own
Poll the snapshot and follow events from a script or a Discord bot.
Home Assistant
Sensors and automations from your OSRS account.
Which key?
| Personal key | Integration (service) key | |
|---|---|---|
| Created by | any member, on API keys | an admin, on Admin → Integrations |
| Reads | what its creator can see | what the guild audience sees |
| Stops working | when revoked or expired, or when its creator leaves | only when revoked or expired |
| Requests per minute | 120 | 600 by default (1–6000) |
| Accounts per bulk request | 10 | 50 |
account_hash | no | yes |
| Good for | your own scripts, your own Home Assistant | a live map or bot the whole guild uses |
Both look like ohub_<prefix>_<secret> and go in the Authorization: Bearer header. See
API keys and Integration keys.
Categories
Give a key only the categories its integration needs.
| Category | Covers |
|---|---|
stats | skills, XP history, gains, levels |
events | loot, level-ups, deaths, collection log, diaries, combat tasks, superiors |
activity | online status, world, sessions and playtime, HP, prayer, spellbook |
location_live | current coordinates (for a live map) |
location_history | the 30-day trail |
equipment | current gear and its change log |
inventory | current inventory and wealth history |
A key can't see what the account's owner doesn't share. With a service key, that means only categories shared with the whole guild. Equipment, inventory and location history are private by default, so players have to share them before a guild service can show them.
Suggested keys
| Integration | Endpoints | Categories |
|---|---|---|
| Live map | /snapshot?since=, /events, /leaderboards/loot, /xp, /locations | activity, location_live, plus stats, equipment, inventory, events, location_history for profiles and trails |
| Discord bot | /events?cursor=, /leaderboards/gains, /accounts?online=true | events, stats, activity |
| Home Assistant | /snapshot with If-None-Match, /events?cursor= | stats, events, activity, optionally location_live |