{"openapi":"3.1.0","info":{"title":"Categories Game API","version":"0.1.0","description":"A real, stateless, playable Categories/Scattergories-style game session engine with a 160+ original category bank, real letter validation, genuine unique-answer scoring, and session-level no-repeat tracking for both letters and categories. Every tool call takes the full session 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://categoriesgame.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/categoriesgame/docs"},"termsOfService":"https://connectorbay.com/categoriesgame/terms"},"servers":[{"url":"https://categoriesgame.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/categoriesgame/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/list_category_bank":{"post":{"operationId":"list_category_bank","summary":"Lists every category in the bank. Use for \"what categories are available\".","description":"Lists every category in the bank. Use for \"what categories are available\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_category_bankArguments","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/new_session":{"post":{"operationId":"new_session","summary":"Starts a fresh Categories Game session with the given players. Use for \"let's play","description":"Starts a fresh Categories Game session with the given players. Use for \"let's play\n    categories with Alice and Bob\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"players":{"description":"Player names, at least one, all unique.","items":{"type":"string"},"title":"Players","type":"array"}},"required":["players"],"title":"new_sessionArguments","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/new_round":{"post":{"operationId":"new_round","summary":"Picks a fresh session-unused letter (unless `letter` is given) and a fresh set of","description":"Picks a fresh session-unused letter (unless `letter` is given) and a fresh set of\n    session-unused categories, starting a new round. Fails with bad_input once all 26 letters (or\n    enough unused categories) have been used this session. Use for \"give us a letter and\n    categories\", \"next round\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_session/new_round/submit_answers/score_round.","examples":[{"category_pool_used":["Animals"],"current_round":{"answers":{},"categories":["Animals"],"letter":"B"},"players":["Alice","Bob"],"rounds":[],"total_scores":{"Alice":0,"Bob":0},"used_letters":["B"]}],"title":"State","type":"object"},"num_categories":{"default":5,"description":"How many categories this round.","maximum":10,"minimum":1,"title":"Num Categories","type":"integer"},"letter":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Force a specific letter instead of a random unused one. Must not have been used yet this session.","title":"Letter"}},"required":["state"],"title":"new_roundArguments","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_answers":{"post":{"operationId":"submit_answers","summary":"Records one player's answers for the current round. Call once per player before","description":"Records one player's answers for the current round. Call once per player before\n    score_round. Use for \"Alice said 'Banana' for Fruits and 'Brazil' for Countries\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_session/new_round/submit_answers/score_round.","examples":[{"category_pool_used":["Animals"],"current_round":{"answers":{},"categories":["Animals"],"letter":"B"},"players":["Alice","Bob"],"rounds":[],"total_scores":{"Alice":0,"Bob":0},"used_letters":["B"]}],"title":"State","type":"object"},"player":{"description":"Which player these answers belong to.","title":"Player","type":"string"},"answers":{"additionalProperties":{"type":"string"},"description":"Maps a category (from the current round) to that player's answer text.","title":"Answers","type":"object"}},"required":["state","player","answers"],"title":"submit_answersArguments","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/score_round":{"post":{"operationId":"score_round","summary":"Scores the current round for real: an answer only counts if it starts with the round's","description":"Scores the current round for real: an answer only counts if it starts with the round's\n    letter (case-insensitive, whitespace-trimmed); among valid answers, one used by exactly one\n    player scores 10, one shared by two or more players scores 5 each, invalid/blank scores 0. Folds\n    the result into total_scores. Use for \"score this round\", \"we're all done answering\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_session/new_round/submit_answers/score_round.","examples":[{"category_pool_used":["Animals"],"current_round":{"answers":{},"categories":["Animals"],"letter":"B"},"players":["Alice","Bob"],"rounds":[],"total_scores":{"Alice":0,"Bob":0},"used_letters":["B"]}],"title":"State","type":"object"}},"required":["state"],"title":"score_roundArguments","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: the current round (if any), recent round results, and total","description":"A human-readable summary: the current round (if any), recent round results, and total\n    scores. Use for \"what's the score so far\", \"show the current round\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_session/new_round/submit_answers/score_round.","examples":[{"category_pool_used":["Animals"],"current_round":{"answers":{},"categories":["Animals"],"letter":"B"},"players":["Alice","Bob"],"rounds":[],"total_scores":{"Alice":0,"Bob":0},"used_letters":["B"]}],"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}}}}