{"openapi":"3.1.0","info":{"title":"Bulls and Cows API","version":"0.1.0","description":"A fully local, playable Bulls and Cows digit-guessing game, with an optional solver mode where the engine guesses your secret using real consistency filtering and Knuth-style minimax. Stateless: the caller holds 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://bullscows.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/bullscows/docs"},"termsOfService":"https://connectorbay.com/bullscows/terms"},"servers":[{"url":"https://bullscows.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/bullscows/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":"Start a new Bulls and Cows game. 'guesser' mode generates a secret the engine holds for you to","description":"Start a new Bulls and Cows game. 'guesser' mode generates a secret the engine holds for you to\n    guess; 'solver' mode expects YOU to hold a secret for the engine to guess. Use for \"let's play bulls\n    and cows\", \"start a digit-guessing game with 5 digits\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mode":{"default":"guesser","description":"'guesser' (engine holds the secret) or 'solver' (you hold the secret).","title":"Mode","type":"string"},"code_length":{"default":4,"description":"Number of digit positions in the code.","maximum":6,"minimum":2,"title":"Code Length","type":"integer"},"digit_range":{"default":10,"description":"Number of distinct digit values, numbered 0..digit_range-1.","maximum":10,"minimum":2,"title":"Digit Range","type":"integer"},"allow_repeats":{"default":false,"description":"Whether a digit may appear more than once in the code (classic game: False).","title":"Allow Repeats","type":"boolean"},"max_guesses":{"default":10,"description":"Maximum number of guesses allowed.","maximum":20,"minimum":1,"title":"Max Guesses","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/submit_guess":{"post":{"operationId":"submit_guess","summary":"Guesser mode only: submit a guess against the engine's secret and get real bulls/cows feedback.","description":"Guesser mode only: submit a guess against the engine's secret and get real bulls/cows feedback.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"},"guess":{"description":"Your guess: a list of digits (integers), one per position.","items":{"type":"integer"},"title":"Guess","type":"array"}},"required":["state","guess"],"title":"submit_guessArguments","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/solver_guess":{"post":{"operationId":"solver_guess","summary":"Solver mode only: compute the engine's next guess against the human-held secret, using real","description":"Solver mode only: compute the engine's next guess against the human-held secret, using real\n    consistency filtering and (once few enough candidates remain) real Knuth-style minimax. Show the\n    returned guess to the human, collect their bulls/cows count, and call provide_feedback with it.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"solver_guessArguments","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/provide_feedback":{"post":{"operationId":"provide_feedback","summary":"Solver mode only: record the human's bulls/cows feedback for the engine's most recent guess, and","description":"Solver mode only: record the human's bulls/cows feedback for the engine's most recent guess, and\n    report whether the engine solved it, ran out of guesses, or should guess again.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"},"bulls":{"description":"Number of bulls (right digit, right position) for the engine's last guess.","minimum":0,"title":"Bulls","type":"integer"},"cows":{"description":"Number of cows (right digit, wrong position) for the engine's last guess.","minimum":0,"title":"Cows","type":"integer"}},"required":["state","bulls","cows"],"title":"provide_feedbackArguments","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":"Guesser mode: reports how many codes remain logically consistent with your own guesses and their","description":"Guesser mode: reports how many codes remain logically consistent with your own guesses and their\n    real feedback so far -- a genuine strategic signal, not a peek at the secret.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","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/render_board":{"post":{"operationId":"render_board","summary":"Render the guess history as human-readable text. Never reveals the secret.","description":"Render the guess history as human-readable text. Never reveals the secret.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"render_boardArguments","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/reveal_secret":{"post":{"operationId":"reveal_secret","summary":"Reveal the secret code for a 'guesser'-mode game -- use for a clean end-of-game reveal, or if the","description":"Reveal the secret code for a 'guesser'-mode game -- use for a clean end-of-game reveal, or if the\n    human wants to give up. Not applicable to 'solver' mode (the human already knows their own secret).","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"reveal_secretArguments","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_info":{"post":{"operationId":"game_info","summary":"Report guesses used/remaining, guess count, and (in solver mode) how many codes are still","description":"Report guesses used/remaining, guess count, and (in solver mode) how many codes are still\n    logically consistent with feedback so far.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current game state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"game_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/rules_info":{"post":{"operationId":"rules_info","summary":"Explain the rules of Bulls and Cows, both modes, and the solver's minimax strategy.","description":"Explain the rules of Bulls and Cows, both modes, and the solver's minimax strategy.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"rules_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}}}}