{"id":"doc_rqiH2VPLimHbUNZ6dvl6TNVoR8bI","version":2,"filename":"spec.md","description":"The Tavern API provides a standard interface for adventuring parties to query tavern availability, menu options, room rates, and quest board postings ...","title":"Tavern API Specification","content":"# Tavern API Specification\n\n## Overview\n\nThe 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.\n\n## Base URL\n\n`https://api.questboard.io/v1/taverns`\n\n## Authentication\n\nAll 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.\n\n## Endpoints\n\n### GET /taverns\n\nReturns a list of taverns within a given radius.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| lat | float | yes | Latitude (in leagues from the World Tree) |\n| lng | float | yes | Longitude (in leagues from the World Tree) |\n| radius | integer | no | Search radius in miles. Default: 10. Max: 50. |\n| min_rating | integer | no | Minimum star rating (1-5). Default: 1. |\n| has_stables | boolean | no | Filter for taverns with stabling facilities |\n| no_undead | boolean | no | Exclude taverns in undead-controlled territories |\n| open_now | boolean | no | Only return taverns currently open (new in v1.5) |\n\n### GET /taverns/:id/menu\n\nReturns the current menu for a tavern.\n\n**Response fields:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| name | string | Item name |\n| price | integer | Price in copper |\n| category | string | \"food\", \"drink\", \"potion\" |\n| is_poisoned | boolean | Only populated if the tavern has a known poisoning history |\n| allergens | array | List of known allergens. Note: \"cursed\" is not an allergen but is listed anyway. |\n\n### GET /taverns/:id/rooms\n\nReturns room availability.\n\n**Response fields:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| type | string | \"single\", \"double\", \"party\" (sleeps 6), \"stable\" (for non-humanoid party members) |\n| price_per_night | integer | In copper |\n| haunted | boolean | Self-reported by tavern owner. Accuracy not guaranteed. |\n| floor | integer | Higher floors reduce risk of ground-floor break-ins but increase risk of window-based attacks |\n\n### GET /taverns/:id/reviews\n\nReturns reviews for a tavern. New in v1.5.\n\n**Response fields:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| author | string | Reviewer's guild name |\n| rating | integer | 1-5 stars |\n| text | string | Review text |\n| survived | boolean | Whether the reviewer survived their stay |\n| date | date | Date of review |\n\nReviews from deceased adventurers are marked with a small skull icon in the official client.\n\n### POST /taverns/:id/quests\n\nSubmit a new quest posting to a tavern's board.\n\n**Request body:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| title | string | yes | Quest title. Max 100 chars. |\n| description | string | yes | Quest description. Markdown supported. |\n| reward | integer | yes | Reward in gold. Must be > 0. |\n| danger_level | string | yes | \"trivial\", \"moderate\", \"dangerous\", \"suicidal\" |\n| deadline | date | no | Null means \"whenever.\" |\n\n**Note:** Quests rated \"suicidal\" require a 500 gold deposit from the poster, refundable upon quest completion or non-refundable upon total party kill.\n\n## Throttling\n\nRequests 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.\n\nPersistent abuse of rate limits will result in token suspension and a strongly worded letter from the Barkeepers Guild.\n\n## Error Codes\n\n| Code | Description |\n|------|-------------|\n| 400 | Bad request. Check your parameters. |\n| 401 | Invalid or expired guild token. |\n| 403 | Your guild has been banned from this tavern. |\n| 404 | Tavern not found. It may have been destroyed. |\n| 410 | Tavern existed but is now gone. Possibly dragon. |\n| 418 | The tavern is actually a teapot. This happens more often than you'd think. |\n| 429 | Throttled. See Retry-After header. |\n| 503 | Tavern is under siege. Try again later. |\n","url":"/questboard/tavern-api/spec.md.json","account":{"id":"acct_NYUSG6iQhfgLNpibnAMYgOE7chst","name":"QuestBoard","url":"/questboard.json","slug":"questboard"},"tags":[],"urls":{"diff":"/api/questboard/tavern-api/spec.md/diff","versions":"/api/questboard/tavern-api/spec.md/versions"},"project":{"id":"proj_IK6ta3bkToEfvfU9BkgQPfFxISJL","name":"Tavern API","url":"/questboard/tavern-api.json","slug":"tavern-api"},"version_count":2,"locked_at":null,"locked_by":null,"uploaded_by":{"id":"user_LKTkI9aj1hADquO1DmzjLJsAHXJY","username":"eri_questboard","display_name":"Eri Nightwind"},"uploaded_at":"2026-04-02T00:00:00Z"}