{"openapi":"3.1.0","info":{"title":"Scavenger API","version":"0.1.0","description":"A fully local, hand-curated scavenger-hunt & treasure-hunt design reference for parties, team-building, weddings and birthdays: clue-writing formats with writing craft tips, occasion-fit suggestions, indoor/outdoor venue considerations, a term glossary, beginner tips, and a genuine clue-count/pacing planner. Keyless; fully local; zero upstream calls.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://scavenger.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/scavenger/docs"},"termsOfService":"https://connectorbay.com/scavenger/terms"},"servers":[{"url":"https://scavenger.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/scavenger/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 clue-writing format: category, how it works, difficulty to write and to solve, best","description":"Full detail for one clue-writing format: category, how it works, difficulty to write and to solve, best\n    occasions, materials needed, whether tech is required, pros and cons, and an original example clue. Use for\n    \"how does a photo-based clue work\", \"what do I need for a QR-code hunt station\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A clue-writing format's name or alias.","examples":["riddle-based","photo-based","QR-code-based","location-based","cipher"],"minLength":1,"title":"Name","type":"string"}},"required":["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/clue_writing_tip":{"post":{"operationId":"clue_writing_tip","summary":"Craft-level guidance for writing a good clue of a named format: specific writing tips, common mistakes","description":"Craft-level guidance for writing a good clue of a named format: specific writing tips, common mistakes\n    to avoid, and a strong-vs-weak example. Use for \"tips for writing a good riddle clue\", \"what mistakes should\n    I avoid with a cipher clue\", \"how do I write a good photo clue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"clue_type":{"description":"A clue-writing format's name or alias to get craft-level writing guidance for.","examples":["riddle-based","cipher","trivia-question","item checklist"],"minLength":1,"title":"Clue Type","type":"string"}},"required":["clue_type"],"title":"clue_writing_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/hunt_planner":{"post":{"operationId":"hunt_planner","summary":"Genuine clue-count and pacing math for a scavenger/treasure hunt: given total duration, team count, and","description":"Genuine clue-count and pacing math for a scavenger/treasure hunt: given total duration, team count, and\n    difficulty, computes a recommended clue count, an easy/medium/hard difficulty mix that ramps harder toward\n    the finish, estimated solving and total time, a suggested hint threshold, and (for 2+ teams) staggered-\n    start guidance to avoid checkpoint bottlenecks. This is a documented planning heuristic, not a guarantee —\n    always test-run your own clues before the real event. Use for \"how many clues for a 60 minute hunt with 4\n    teams\", \"pacing plan for a hard 90 minute hunt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"duration_minutes":{"description":"Total time available for the hunt, including briefing and wrap-up, in minutes.","examples":[45,60,90],"maximum":480,"minimum":10,"title":"Duration Minutes","type":"integer"},"num_teams":{"description":"How many teams (or solo participants) will be hunting.","examples":[1,4,10],"maximum":100,"minimum":1,"title":"Num Teams","type":"integer"},"difficulty":{"default":"medium","description":"Overall difficulty level.","examples":["easy","medium","hard","beginner","advanced"],"minLength":1,"title":"Difficulty","type":"string"}},"required":["duration_minutes","num_teams"],"title":"hunt_plannerArguments","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 scavenger/treasure-hunt vocabulary — clue chain, hub-and-spoke, red herring, decoy","description":"Definitions of common scavenger/treasure-hunt vocabulary — clue chain, hub-and-spoke, red herring, decoy\n    clue, checkpoint, game master, difficulty curve, meta-puzzle, and more. Use for \"what does 'hub-and-spoke'\n    mean\", \"define red herring in a scavenger hunt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","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/venue_consideration":{"post":{"operationId":"venue_consideration","summary":"Planning considerations, safety notes, permission/permit notes, weather notes, accessibility notes, and","description":"Planning considerations, safety notes, permission/permit notes, weather notes, accessibility notes, and\n    recommended clue formats for a named venue type, indoor or outdoor. Use for \"what should I consider for an\n    outdoor park hunt\", \"is a museum a good venue for a scavenger hunt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"venue_type":{"description":"A venue type.","examples":["backyard","public park","office","beach","wedding venue","virtual"],"minLength":1,"title":"Venue Type","type":"string"}},"required":["venue_type"],"title":"venue_considerationArguments","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_format_for_occasion":{"post":{"operationId":"find_format_for_occasion","summary":"Suggests which clue formats and hunt-design choices fit a stated occasion: typical group size and","description":"Suggests which clue formats and hunt-design choices fit a stated occasion: typical group size and\n    duration, recommended difficulty, whether team or individual format suits it best, recommended clue\n    formats, and occasion-specific tips. Use for \"what clue formats work well for a wedding\", \"how should I run\n    a hunt for a corporate team-building event\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"occasion":{"description":"An occasion, in plain language.","examples":["kids' birthday party","wedding","corporate team-building","bachelorette party"],"minLength":1,"title":"Occasion","type":"string"}},"required":["occasion"],"title":"find_format_for_occasionArguments","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/category_list":{"post":{"operationId":"category_list","summary":"Every clue-format category with how many formats are in it (Wordplay & Riddles, Visual & Photo, Location","description":"Every clue-format category with how many formats are in it (Wordplay & Riddles, Visual & Photo, Location\n    & Navigation, Tech-Assisted, Physical & Sensory, Hybrid & Combination). Use for \"what categories of clue\n    formats do you cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"category_listArguments","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 ranked shortlist of general tips for planning a first scavenger or treasure hunt — testing clues in","description":"A ranked shortlist of general tips for planning a first scavenger or treasure hunt — testing clues in\n    advance, backup plans for tech-dependent clues, briefing safety, hint systems, and more. Use for \"give me\n    tips for planning my first scavenger hunt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"count":{"default":5,"description":"How many tips to return.","maximum":14,"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}}}}