Tavern API Specification v2
Tavern API Specification
Overview
The Tavern API provides a standard interface for adventuring parties to query tavern availability, menu options, room rates, and quest board postings across the realm. All taverns participating in the Questboard network expose this API.
Base URL
https://api.questboard.io/v1/taverns
Authentication
All requests require a valid adventuring guild token in the X-Guild-Token header. Tokens expire after 30 days or upon party death, whichever comes first.
Endpoints
GET /taverns
Returns a list of taverns within a given radius.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | float | yes | Latitude (in leagues from the World Tree) |
| lng | float | yes | Longitude (in leagues from the World Tree) |
| radius | integer | no | Search radius in miles. Default: 10. Max: 50. |
| min_rating | integer | no | Minimum star rating (1-5). Default: 1. |
| has_stables | boolean | no | Filter for taverns with stabling facilities |
| no_undead | boolean | no | Exclude taverns in undead-controlled territories |
| open_now | boolean | no | Only return taverns currently open (new in v1.5) |
GET /taverns/:id/menu
Returns the current menu for a tavern.
Response fields:
| Field | Type | Description |
|---|---|---|
| name | string | Item name |
| price | integer | Price in copper |
| category | string | "food", "drink", "potion" |
| is_poisoned | boolean | Only populated if the tavern has a known poisoning history |
| allergens | array | List of known allergens. Note: "cursed" is not an allergen but is listed anyway. |
GET /taverns/:id/rooms
Returns room availability.
Response fields:
| Field | Type | Description |
|---|---|---|
| type | string | "single", "double", "party" (sleeps 6), "stable" (for non-humanoid party members) |
| price_per_night | integer | In copper |
| haunted | boolean | Self-reported by tavern owner. Accuracy not guaranteed. |
| floor | integer | Higher floors reduce risk of ground-floor break-ins but increase risk of window-based attacks |
GET /taverns/:id/reviews
Returns reviews for a tavern. New in v1.5.
Response fields:
| Field | Type | Description |
|---|---|---|
| author | string | Reviewer's guild name |
| rating | integer | 1-5 stars |
| text | string | Review text |
| survived | boolean | Whether the reviewer survived their stay |
| date | date | Date of review |
Reviews from deceased adventurers are marked with a small skull icon in the official client.
POST /taverns/:id/quests
Submit a new quest posting to a tavern's board.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | yes | Quest title. Max 100 chars. |
| description | string | yes | Quest description. Markdown supported. |
| reward | integer | yes | Reward in gold. Must be > 0. |
| danger_level | string | yes | "trivial", "moderate", "dangerous", "suicidal" |
| deadline | date | no | Null means "whenever." |
Note: Quests rated "suicidal" require a 500 gold deposit from the poster, refundable upon quest completion or non-refundable upon total party kill.
Throttling
Requests are limited to 100 per minute per guild token. Exceeding this limit returns 429 Too Many Requests. The Retry-After header indicates when you may try again, measured in seconds.
Persistent abuse of rate limits will result in token suspension and a strongly worded letter from the Barkeepers Guild.
Error Codes
| Code | Description |
|---|---|
| 400 | Bad request. Check your parameters. |
| 401 | Invalid or expired guild token. |
| 403 | Your guild has been banned from this tavern. |
| 404 | Tavern not found. It may have been destroyed. |
| 410 | Tavern existed but is now gone. Possibly dragon. |
| 418 | The tavern is actually a teapot. This happens more often than you'd think. |
| 429 | Throttled. See Retry-After header. |
| 503 | Tavern is under siege. Try again later. |