{"openapi":"3.1.0","info":{"title":"Puzzlehunt API","version":"0.1.0","description":"A fully local, hand-curated puzzle-hunt event reference: hunt formats from MIT Mystery Hunt-style marathons to escape rooms, scavenger hunts, and DASH-style same-day events; puzzle categories (wordplay, light cryptography, visual/spatial, meta-puzzles, and more); a hunt-jargon glossary; team-role suggestions by team size; a difficulty-progression explainer; a format finder for a given group size and experience level; and hosting guidance for running your own small hunt.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://puzzlehunt.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/puzzlehunt/docs"},"termsOfService":"https://connectorbay.com/puzzlehunt/terms"},"servers":[{"url":"https://puzzlehunt.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/puzzlehunt/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/format_info":{"post":{"operationId":"format_info","summary":"Full detail for one puzzle-hunt format: team size, duration, setting, typical structure, who it's","description":"Full detail for one puzzle-hunt format: team size, duration, setting, typical structure, who it's\n    good for, and difficulty tier. Omit name to list every format with a one-line summary. Use for \"how\n    does a Mystery Hunt-style event work\", \"what is a DASH-style hunt\", \"list puzzle hunt formats\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A hunt format's name or alias; omit to list every format.","examples":["MIT Mystery Hunt-style","escape room","DASH-style hunt","scavenger hunt"],"title":"Name"}},"title":"format_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/puzzle_category_info":{"post":{"operationId":"puzzle_category_info","summary":"Explains one puzzle category commonly found inside a hunt, with example techniques and a solving","description":"Explains one puzzle category commonly found inside a hunt, with example techniques and a solving\n    tip. Omit name to list every category. Use for \"what is a meta-puzzle\", \"what counts as a cryptic\n    clue\", \"list puzzle categories\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A puzzle category's name or alias; omit to list every category.","examples":["wordplay","light cryptography","meta-puzzles","cryptic clues"],"title":"Name"}},"title":"puzzle_category_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/term_glossary":{"post":{"operationId":"term_glossary","summary":"Definitions of common puzzle-hunt jargon — meta-puzzle, feeder puzzle, runaround, gatekeeper","description":"Definitions of common puzzle-hunt jargon — meta-puzzle, feeder puzzle, runaround, gatekeeper\n    puzzle, backsolve, hunt HQ, wrangler, red herring, and more. Omit term to list the full glossary. Use\n    for \"what does backsolve mean\", \"what's a runaround in a puzzle hunt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific hunt-jargon term to look up; omit to list all.","examples":["meta-puzzle","runaround","backsolve","hunt HQ"],"title":"Term"}},"title":"term_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/team_role_suggestion":{"post":{"operationId":"team_role_suggestion","summary":"Suggests a role breakdown and coordination tips for a hunting team of a given size, from solo","description":"Suggests a role breakdown and coordination tips for a hunting team of a given size, from solo\n    solving up through very large teams of 16 or more. Use for \"what roles should a team of 6 have\",\n    \"how should a 20-person team organize for a mystery hunt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_size":{"description":"How many people are on the hunting team.","examples":[1,3,6,12,25],"maximum":500,"minimum":1,"title":"Team Size","type":"integer"}},"required":["team_size"],"title":"team_role_suggestionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/hosting_tip":{"post":{"operationId":"hosting_tip","summary":"Practical guidance for one aspect of running your own small puzzle hunt: venue, puzzle writing,","description":"Practical guidance for one aspect of running your own small puzzle hunt: venue, puzzle writing,\n    testing, time budgeting, hint systems, difficulty curve, prizes, logistics/tech, safety, budget,\n    accessibility, staffing, or wrap-up. Omit topic to list every topic covered. Use for \"how do I host a\n    puzzle hunt for my office\", \"tips for a hunt hint system\", \"how much should I budget for a hunt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A hosting topic; omit to list every topic covered.","examples":["venue","hint system","testing","safety","prizes"],"title":"Topic"}},"title":"hosting_tipArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/difficulty_progression_explainer":{"post":{"operationId":"difficulty_progression_explainer","summary":"Explains how puzzle hunts typically shape their difficulty curve, from an easy onramp through","description":"Explains how puzzle hunts typically shape their difficulty curve, from an easy onramp through\n    escalating rounds and round metas to a final endgame/runaround. Use for \"how do hunt puzzles get\n    harder over time\", \"what's the usual structure of a puzzle hunt's difficulty\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"difficulty_progression_explainerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_hunt_style_for_group":{"post":{"operationId":"find_hunt_style_for_group","summary":"Suggests 2-4 hunt formats that fit a stated group size and experience level, ranked by fit. Use for","description":"Suggests 2-4 hunt formats that fit a stated group size and experience level, ranked by fit. Use for\n    \"what puzzle hunt format fits 20 total beginners\", \"best hunt style for a small experienced team\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_size":{"description":"How many people will take part.","examples":[2,8,20,60],"maximum":1000,"minimum":1,"title":"Group Size","type":"integer"},"experience_level":{"description":"How experienced the group is with puzzle hunts.","examples":["first-timers","some experience","experienced","mixed"],"minLength":1,"title":"Experience Level","type":"string"}},"required":["group_size","experience_level"],"title":"find_hunt_style_for_groupArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/beginner_tips":{"post":{"operationId":"beginner_tips","summary":"A curated, ranked list of tips for people new to puzzle hunts, from reading flavor text closely to","description":"A curated, ranked list of tips for people new to puzzle hunts, from reading flavor text closely to\n    using the hint system without shame. Use for \"give me tips for my first puzzle hunt\", \"how do I get\n    better at solving hunt puzzles\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"count":{"default":5,"description":"How many tips to return.","maximum":20,"minimum":1,"title":"Count","type":"integer"}},"title":"beginner_tipsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}