{"openapi":"3.1.0","info":{"title":"Word Ladder API","version":"0.1.0","description":"Real word-ladder puzzles with a BFS solver — stateless: the caller holds and passes the game state between calls.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://wordladder.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/wordladder/docs"},"termsOfService":"https://connectorbay.com/wordladder/terms"},"servers":[{"url":"https://wordladder.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/wordladder/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_puzzle":{"post":{"operationId":"new_puzzle","summary":"Generate a solvable word-ladder puzzle: a start word and a same-length target word connected by a","description":"Generate a solvable word-ladder puzzle: a start word and a same-length target word connected by a\n    real chain of single-letter changes. Returns the game `state` — hold onto it and pass it into every\n    other tool. Use for \"give me a word ladder puzzle\", \"give me a hard word ladder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"length":{"default":4,"description":"Word length for both start and target (3-8).","maximum":8,"minimum":3,"title":"Length","type":"integer"},"steps":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Target ladder length (optional difficulty knob) — best-effort.","title":"Steps"}},"title":"new_puzzleArguments","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_step":{"post":{"operationId":"submit_step","summary":"Try the next step in the ladder. Validates length, real-dictionary membership, that it's exactly","description":"Try the next step in the ladder. Validates length, real-dictionary membership, that it's exactly\n    one letter different from the current last word, and that it hasn't been used already. Returns the\n    updated `state` (pass THAT into the next call) and whether the target was reached.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The full puzzle state returned by new_puzzle or any other tool — pass it back in unchanged except for whatever the tool itself asks you to submit.","title":"State","type":"object"},"word":{"description":"The next word in the player's chain.","minLength":1,"title":"Word","type":"string"}},"required":["state","word"],"title":"submit_stepArguments","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":"The real shortest remaining distance (BFS) from the current chain position to the target, plus the","description":"The real shortest remaining distance (BFS) from the current chain position to the target, plus the\n    first letter of one valid next word — never the whole word.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The full puzzle state returned by new_puzzle or any other tool — pass it back in unchanged except for whatever the tool itself asks you to submit.","title":"State","type":"object"}},"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":"Standalone BFS solver: is there a word ladder between these two words, and if so what's the","description":"Standalone BFS solver: is there a word ladder between these two words, and if so what's the\n    shortest one? Independent of any puzzle state — pass any two same-length words. Use to check a puzzle\n    is solvable or to find the optimal number of steps.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_word":{"description":"Start word.","minLength":1,"title":"Start Word","type":"string"},"end_word":{"description":"End word — must be the same length as start_word.","minLength":1,"title":"End Word","type":"string"}},"required":["start_word","end_word"],"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":{"post":{"operationId":"render","summary":"A human-readable rendering of the chain so far and the target.","description":"A human-readable rendering of the chain so far and the target.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The full puzzle state returned by new_puzzle or any other tool — pass it back in unchanged except for whatever the tool itself asks you to submit.","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}}}}