{"id":"doc_rqiH2VPLimHbUNZ6dvl6TNVoR8bI","version":1,"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\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### 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## Rate Limits\n\n- 100 requests per minute per guild token\n- Exceeding the rate limit returns `429 Too Many Requests` with a `Retry-After` header measured in \"time until the barkeep calms down\"\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 | Rate limited. |\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":[],"project":{"id":"proj_IK6ta3bkToEfvfU9BkgQPfFxISJL","name":"Tavern API","url":"/questboard/tavern-api.json","slug":"tavern-api"},"locked_at":null,"locked_by":null,"uploaded_by":{"id":"user_WEt0R8kibZP3uPb2va8vh9ThPcMd","username":"mira_questboard","display_name":"Mira Stoneforge"},"uploaded_at":"2026-02-22T00:00:00Z"}