You are viewing version 1. The latest version is 2. View latest
Tavern API Specification v1
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 |
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 |
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.
Rate Limits
- 100 requests per minute per guild token
- Exceeding the rate limit returns
429 Too Many Requestswith aRetry-Afterheader measured in "time until the barkeep calms down"
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 | Rate limited. |
| 503 | Tavern is under siege. Try again later. |