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