{"openapi":"3.1.0","info":{"title":"Hidden Word API","version":"0.1.0","description":"A fully local, stateless word-search grid game — generate a grid, submit found words for validation, get hints, or solve.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://hiddenword.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/hiddenword/docs"},"termsOfService":"https://connectorbay.com/hiddenword/terms"},"servers":[{"url":"https://hiddenword.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/hiddenword/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":"Generates a new word-search grid and returns the full game state (including the solution — see the","description":"Generates a new word-search grid and returns the full game state (including the solution — see the\n    server's trust note) plus a hidden-style render for showing the player. Use for \"start a word search\",\n    \"new hidden word game with space words\", \"give me a hard 12x12 puzzle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"width":{"default":10,"description":"Grid width in columns.","maximum":20,"minimum":5,"title":"Width","type":"integer"},"height":{"default":10,"description":"Grid height in rows.","maximum":20,"minimum":5,"title":"Height","type":"integer"},"word_count":{"default":8,"description":"How many words to place.","maximum":20,"minimum":3,"title":"Word Count","type":"integer"},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"\"easy\", \"medium\", or \"hard\" — overrides width/height/word_count when given.","title":"Difficulty"},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Word categories to draw from; omit for all. See category_list.","title":"Categories"},"allow_diagonal":{"default":true,"description":"Allow diagonal placements in addition to horizontal/vertical.","title":"Allow Diagonal","type":"boolean"},"allow_backward":{"default":false,"description":"Allow words placed right-to-left / bottom-to-top (reversed reading direction).","title":"Allow Backward","type":"boolean"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional RNG seed for a reproducible grid.","title":"Seed"}},"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/submit_word":{"post":{"operationId":"submit_word","summary":"Validates a claimed find against the grid itself (straight line, either reading direction) and moves it","description":"Validates a claimed find against the grid itself (straight line, either reading direction) and moves it\n    from remaining to found. Returns the updated state. Use for \"I found OTTER from (2,1) to (2,5)\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The full game state object as previously returned by new_game or a gameplay tool. Pass it back unmodified except through this API.","title":"State","type":"object"},"word":{"description":"The word you believe you found.","minLength":1,"title":"Word","type":"string"},"start_row":{"description":"0-indexed row of the word's first letter as you're reading it.","minimum":0,"title":"Start Row","type":"integer"},"start_col":{"description":"0-indexed column of the word's first letter.","minimum":0,"title":"Start Col","type":"integer"},"end_row":{"description":"0-indexed row of the word's last letter.","minimum":0,"title":"End Row","type":"integer"},"end_col":{"description":"0-indexed column of the word's last letter.","minimum":0,"title":"End Col","type":"integer"}},"required":["state","word","start_row","start_col","end_row","end_col"],"title":"submit_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_hint":{"post":{"operationId":"get_hint","summary":"Reveals one remaining word's length, starting cell, and direction (not its end cell) via a real grid","description":"Reveals one remaining word's length, starting cell, and direction (not its end cell) via a real grid\n    search. Use for \"give me a hint\", \"hint me on the animal word\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The full game state object as previously returned by new_game or a gameplay tool. Pass it back unmodified except through this API.","title":"State","type":"object"},"word":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific remaining word to hint; omit for a random one.","title":"Word"}},"required":["state"],"title":"get_hintArguments","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/solve":{"post":{"operationId":"solve","summary":"Runs a genuine fresh 8-direction grid search for every word's location directly against state['grid'] —","description":"Runs a genuine fresh 8-direction grid search for every word's location directly against state['grid'] —\n    it does not read any stored answer key. Use for \"solve the puzzle\", \"where are all the words\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The full game state object as previously returned by new_game or a gameplay tool. Pass it back unmodified except through this API.","title":"State","type":"object"},"only_remaining":{"default":false,"description":"If true, only solve words not yet found.","title":"Only Remaining","type":"boolean"}},"required":["state"],"title":"solveArguments","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_grid":{"post":{"operationId":"render_grid","summary":"Plain-text rendering of the current grid plus found/remaining word lists. Use for \"show me the grid\".","description":"Plain-text rendering of the current grid plus found/remaining word lists. Use for \"show me the grid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The full game state object as previously returned by new_game or a gameplay tool. Pass it back unmodified except through this API.","title":"State","type":"object"},"reveal_remaining":{"default":false,"description":"If true, show remaining words' text instead of blanks (spoils the puzzle).","title":"Reveal Remaining","type":"boolean"}},"required":["state"],"title":"render_gridArguments","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":"Lists the built-in word categories and how many words each has. Use for \"what word categories do you have\".","description":"Lists the built-in word categories and how many words each has. Use for \"what word categories do you have\".","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}}}}