Comparing v1 → v2
+22 additions
-4 deletions
v1 → 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.
-## Rate Limits
+## Throttling
-- 100 requests per minute per guild token
-- Exceeding the rate limit returns `429 Too Many Requests` with a `Retry-After` header measured in "time until the barkeep calms down"
+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 | Rate limited. |
+| 429 | Throttled. See Retry-After header. |
| 503 | Tavern is under siege. Try again later. |