Tavern API Specification

v1
Feb 22, 2026 · 3.3 KB · 2 min read · by Mira Stoneforge

Comparing v1 → v1

+0 additions -0 deletions
v1 → 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 Requests` with a `Retry-After` header 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. |