{"openapi":"3.1.0","info":{"title":"High-Low Card API","version":"0.1.0","description":"A real, stateless, playable higher/lower card-guessing game with genuine remaining-deck probability tracking. 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://highlowcard.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/highlowcard/docs"},"termsOfService":"https://connectorbay.com/highlowcard/terms"},"servers":[{"url":"https://highlowcard.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/highlowcard/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":"Shuffles a fresh deck and reveals the first card. Use for \"let's play higher or lower\",","description":"Shuffles a fresh deck and reveals the first card. Use for \"let's play higher or lower\",\n    \"new game\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"num_decks":{"default":1,"description":"How many 52-card decks to shuffle together.","maximum":8,"minimum":1,"title":"Num Decks","type":"integer"},"tie_rule":{"default":"push","description":"'push' (default: a tie is neither a win nor a loss) or 'loss' (a tie counts as incorrect).","title":"Tie Rule","type":"string"}},"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/get_probabilities":{"post":{"operationId":"get_probabilities","summary":"The EXACT current odds that the next card is higher, lower, or equal to the current card --","description":"The EXACT current odds that the next card is higher, lower, or equal to the current card --\n    computed from the real remaining deck (cards already seen are genuinely excluded), never a\n    theoretical full-deck estimate. Use for \"what are my odds\", \"how many cards would beat this\".","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.","examples":[{"best_streak":0,"current_card":"9S","deck":["7H","2C","KD"],"history":["9S"],"last_round":null,"rounds_played":0,"score":0,"status":"in_progress","tie_rule":"push"}],"title":"State","type":"object"}},"required":["state"],"title":"get_probabilitiesArguments","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":"Returns [\"higher\", \"lower\"] while the game is in progress, else an empty list. Use for","description":"Returns [\"higher\", \"lower\"] while the game is in progress, else an empty list. Use for\n    \"what can I guess\".","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.","examples":[{"best_streak":0,"current_card":"9S","deck":["7H","2C","KD"],"history":["9S"],"last_round":null,"rounds_played":0,"score":0,"status":"in_progress","tie_rule":"push"}],"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/guess":{"post":{"operationId":"guess","summary":"Reveals the next card and resolves the round. status is invalid_move, correct, incorrect,","description":"Reveals the next card and resolves the round. status is invalid_move, correct, incorrect,\n    push (tie under tie_rule='push'), or deck_exhausted (the game just ended -- see\n    state.score/state.best_streak for the final tally). Use for \"I'll guess higher\", \"lower\".","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.","examples":[{"best_streak":0,"current_card":"9S","deck":["7H","2C","KD"],"history":["9S"],"last_round":null,"rounds_played":0,"score":0,"status":"in_progress","tie_rule":"push"}],"title":"State","type":"object"},"direction":{"description":"'higher' or 'lower'.","title":"Direction","type":"string"}},"required":["state","direction"],"title":"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/ai_move":{"post":{"operationId":"ai_move","summary":"Recommends the mathematically better guess (higher or lower) given the true remaining-deck","description":"Recommends the mathematically better guess (higher or lower) given the true remaining-deck\n    odds right now, or 'either' on a genuine exact tie -- does not apply the guess itself, call\n    `guess` with the recommendation to actually play it. Use for \"what should I guess\", \"give me a\n    hint\".","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.","examples":[{"best_streak":0,"current_card":"9S","deck":["7H","2C","KD"],"history":["9S"],"last_round":null,"rounds_played":0,"score":0,"status":"in_progress","tie_rule":"push"}],"title":"State","type":"object"}},"required":["state"],"title":"ai_moveArguments","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 summary: current card, deck size, score and best streak, the live odds, and","description":"A human-readable summary: current card, deck size, score and best streak, the live odds, and\n    the last round played. Use for \"show me my streak\", \"what's the state of the game\".","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.","examples":[{"best_streak":0,"current_card":"9S","deck":["7H","2C","KD"],"history":["9S"],"last_round":null,"rounds_played":0,"score":0,"status":"in_progress","tie_rule":"push"}],"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/rules":{"post":{"operationId":"rules","summary":"Plain-language rules: how a round resolves, the tie rule, and how probability and the AI's","description":"Plain-language rules: how a round resolves, the tie rule, and how probability and the AI's\n    recommendation are computed. Use for \"how does this work\", \"how is the probability calculated\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/guess.","examples":[{"best_streak":0,"current_card":"9S","deck":["7H","2C","KD"],"history":["9S"],"last_round":null,"rounds_played":0,"score":0,"status":"in_progress","tie_rule":"push"}],"type":"object"},{"type":"null"}],"default":null,"title":"State"}},"title":"rulesArguments","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}}}}