{"openapi":"3.1.0","info":{"title":"Bluff API","version":"0.1.0","description":"A fully local, hand-curated reference for bluffing and bidding game mechanics across genres: dice-bidding ladders, blind/sealed auctions, hidden-role social deduction, card-passing and reveal bluffs, poker-adjacent betting structure described at a mechanics level only, negotiation bluffs, and team/partnership signaling, with a cross-mechanic glossary, real game examples, generic tell-reading tips, game-design advice, group-size suggestions and a beginner shortlist. Game design and social-skill content only — never gambling, betting, or bankroll advice.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://bluff.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/bluff/docs"},"termsOfService":"https://connectorbay.com/bluff/terms"},"servers":[{"url":"https://bluff.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/bluff/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/mechanic_info":{"post":{"operationId":"mechanic_info","summary":"Full detail for one named bluffing/bidding mechanic: how it works step by step, the psychological","description":"Full detail for one named bluffing/bidding mechanic: how it works step by step, the psychological\n    tension driving it, its risk shape, typical player counts, generic behavioral tell signals, real game\n    examples, and design notes. If the name matches a category instead, lists every mechanic in it. If\n    neither matches, falls back to a keyword search. Use for \"how does the Skull bidding mechanic work\",\n    \"what is an all-pay auction\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A bluffing/bidding mechanic's name, alias, or a category name.","examples":["liar's dice bidding","all-pay auction","Coup-style challenge","Hidden-Role Social Deduction"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"mechanic_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":"Defines a bluffing/bidding term — bluff, tell, sealed bid, all-pay auction, semi-bluff, double","description":"Defines a bluffing/bidding term — bluff, tell, sealed bid, all-pay auction, semi-bluff, double\n    bluff, brinkmanship, information asymmetry, and more. Omit term to get the full glossary. Use for\n    \"what's a semi-bluff\", \"what does brinkmanship mean in a game\".","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 terms.","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/game_examples":{"post":{"operationId":"game_examples","summary":"Real game names cited as factual examples of one named mechanic, each with a one-line factual note","description":"Real game names cited as factual examples of one named mechanic, each with a one-line factual note\n    — never a reproduction of any game's proprietary rules text. Use for \"what real games use a\n    claim-and-challenge mechanic\", \"name a game built around sealed bidding\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mechanic":{"description":"A bluffing/bidding mechanic's name or alias.","examples":["dice-bid ladder","claimed-power challenge","escalating safe-reveal bid"],"minLength":1,"title":"Mechanic","type":"string"}},"required":["mechanic"],"title":"game_examplesArguments","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/tell_reading_tip":{"post":{"operationId":"tell_reading_tip","summary":"General psychological/behavioral tips for reading bluffs in a stated context, framed as a table-game","description":"General psychological/behavioral tips for reading bluffs in a stated context, framed as a table-game\n    skill — never real-money gambling or betting advice. Omit context for general-purpose tips that apply\n    to any bluffing game. Use for \"how do I read a bluff in a hidden-role game\", \"tips for spotting a bluff\n    over voice chat\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"context":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A play context to get tips for; omit for general tips.","examples":["dice or hidden-tally bidding","auction or blind bidding","hidden-role / social deduction","card-passing or claimed-power bluffs","remote or voice-only play"],"title":"Context"}},"title":"tell_reading_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/design_tip":{"post":{"operationId":"design_tip","summary":"Advice for designing your own bluffing or bidding game, by topic — sizing the cost of a wrong","description":"Advice for designing your own bluffing or bidding game, by topic — sizing the cost of a wrong\n    challenge, balancing public vs. private information, catch-up mechanics, escalation pacing, and more.\n    Omit topic to list every design tip. Use for \"how do I balance a bluffing game\", \"tips for designing a\n    hidden-role game's faction size\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A game-design topic to search for; omit to list all tips.","examples":["escalation pacing","catch-up mechanic","information balance","hidden-role player count"],"title":"Topic"}},"title":"design_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/find_game_for_group":{"post":{"operationId":"find_game_for_group","summary":"Suggests which bluffing/bidding mechanics suit a given player count, ranked by fit, plus a general","description":"Suggests which bluffing/bidding mechanics suit a given player count, ranked by fit, plus a general\n    sizing note for that group size. Use for \"what bluffing games work for 8 people\", \"best mechanic for\n    just 2 players\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player_count":{"description":"How many players will be in the group.","examples":[2,4,6,8,12],"maximum":30,"minimum":1,"title":"Player Count","type":"integer"}},"required":["player_count"],"title":"find_game_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/category_list":{"post":{"operationId":"category_list","summary":"Every bluffing/bidding mechanic category with how many mechanics are filed under it. Use for \"what","description":"Every bluffing/bidding mechanic category with how many mechanics are filed under it. Use for \"what\n    categories of bluffing mechanics 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 curated, ordered shortlist of the most useful starting advice for someone new to bluffing games in","description":"A curated, ordered shortlist of the most useful starting advice for someone new to bluffing games in\n    general, most essential first. Use for \"what should a beginner know about bluffing games\", \"give me\n    tips before I play a bluffing game for the first time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"count":{"default":5,"description":"How many tips to return.","maximum":8,"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}}}}