# 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. |