{"openapi":"3.1.0","info":{"title":"Hangman API","version":"0.1.0","description":"A real, stateless, playable hangman word-guessing engine with hand-curated word banks by category and difficulty. Every tool call takes the full game state and returns the new state; nothing is stored server-side.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://hangmanplay.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/hangmanplay/docs"},"termsOfService":"https://connectorbay.com/hangmanplay/terms"},"servers":[{"url":"https://hangmanplay.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/hangmanplay/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/new_game":{"post":{"operationId":"new_game","summary":"Starts a fresh hangman game and returns its initial state (do not show state.word to the","description":"Starts a fresh hangman game and returns its initial state (do not show state.word to the\n    player). Use for \"let's play hangman\", \"hangman about science on hard\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"One of ['animals', 'food', 'countries', 'science', 'sports', 'movies_and_tv']. Omit for a random category.","title":"Category"},"difficulty":{"default":"medium","description":"easy, medium, or hard.","title":"Difficulty","type":"string"},"max_wrong":{"default":6,"description":"Wrong attempts allowed before a loss.","maximum":10,"minimum":1,"title":"Max Wrong","type":"integer"}},"title":"new_gameArguments","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/guess_letter":{"post":{"operationId":"guess_letter","summary":"Guesses one letter. status is invalid_move (already guessed / not a letter — state","description":"Guesses one letter. status is invalid_move (already guessed / not a letter — state\n    unchanged), in_progress, win, or loss. Use for \"guess the letter E\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/guess_letter/guess_word. Contains the secret word — never show it to the player; use render()'s masked_word instead.","examples":[{"category":"animals","difficulty":"medium","extra_wrong_attempts":0,"guessed_letters":["E","A"],"max_wrong":6,"word":"ELEPHANT","wrong_letters":["Z"]}],"title":"State","type":"object"},"letter":{"description":"A single letter A-Z.","maxLength":1,"minLength":1,"title":"Letter","type":"string"}},"required":["state","letter"],"title":"guess_letterArguments","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/guess_word":{"post":{"operationId":"guess_word","summary":"Guesses the entire word. A correct guess wins immediately; an incorrect one costs one","description":"Guesses the entire word. A correct guess wins immediately; an incorrect one costs one\n    attempt, same as a wrong letter. Use for \"I think the word is ELEPHANT\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/guess_letter/guess_word. Contains the secret word — never show it to the player; use render()'s masked_word instead.","examples":[{"category":"animals","difficulty":"medium","extra_wrong_attempts":0,"guessed_letters":["E","A"],"max_wrong":6,"word":"ELEPHANT","wrong_letters":["Z"]}],"title":"State","type":"object"},"word":{"description":"A full-word guess.","minLength":1,"title":"Word","type":"string"}},"required":["state","word"],"title":"guess_wordArguments","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/get_valid_moves":{"post":{"operationId":"get_valid_moves","summary":"Lists letters (A-Z) not yet guessed or tried; empty once the game has ended. Use for \"what","description":"Lists letters (A-Z) not yet guessed or tried; empty once the game has ended. Use for \"what\n    letters haven't I tried\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/guess_letter/guess_word. Contains the secret word — never show it to the player; use render()'s masked_word instead.","examples":[{"category":"animals","difficulty":"medium","extra_wrong_attempts":0,"guessed_letters":["E","A"],"max_wrong":6,"word":"ELEPHANT","wrong_letters":["Z"]}],"title":"State","type":"object"}},"required":["state"],"title":"get_valid_movesArguments","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/render":{"post":{"operationId":"render","summary":"The player-safe view: masked_word (underscores for unguessed letters), the progressive","description":"The player-safe view: masked_word (underscores for unguessed letters), the progressive\n    ASCII gallows figure, guessed/wrong letters, and attempts remaining. Always show the player\n    this, never the raw state. Use for \"show me the board\", \"how many guesses do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/guess_letter/guess_word. Contains the secret word — never show it to the player; use render()'s masked_word instead.","examples":[{"category":"animals","difficulty":"medium","extra_wrong_attempts":0,"guessed_letters":["E","A"],"max_wrong":6,"word":"ELEPHANT","wrong_letters":["Z"]}],"title":"State","type":"object"}},"required":["state"],"title":"renderArguments","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/list_categories":{"post":{"operationId":"list_categories","summary":"Lists every category and difficulty with word counts. Use for \"what categories can I pick","description":"Lists every category and difficulty with word counts. Use for \"what categories can I pick\n    from\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_categoriesArguments","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}}}}