{"openapi":"3.1.0","info":{"title":"FactorFib API","version":"0.1.0","description":"A fully local, playable number-theory quiz game: primality, factorization, Fibonacci, GCD/LCM, and perfect-number challenges, all computed with real number theory. Stateless: the caller holds the session state between calls.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://factorfib.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/factorfib/docs"},"termsOfService":"https://connectorbay.com/factorfib/terms"},"servers":[{"url":"https://factorfib.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/factorfib/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_session":{"post":{"operationId":"new_session","summary":"Start a new FactorFib session (resets score/streak) and generate its first challenge. Use for","description":"Start a new FactorFib session (resets score/streak) and generate its first challenge. Use for\n    \"let's play FactorFib\", \"start a number theory quiz on hard difficulty\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"difficulty":{"default":"easy","description":"'easy', 'medium', or 'hard' -- scales the size of numbers involved.","title":"Difficulty","type":"string"},"topics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Subset of ['is_prime','factorize','next_fibonacci','gcd_lcm','perfect_number'] to draw from; omit for all five.","title":"Topics"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional RNG seed for reproducible challenges (mainly for testing).","title":"Seed"}},"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":"Generate a fresh challenge (discarding any unanswered current one), keeping score/streak intact.","description":"Generate a fresh challenge (discarding any unanswered current one), keeping score/streak intact.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current session state, exactly as returned by a previous call.","title":"State","type":"object"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional RNG seed for reproducible challenges (mainly for testing).","title":"Seed"}},"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_answer":{"post":{"operationId":"submit_answer","summary":"Submit an answer to the current challenge; grades it against the real computed answer, updates","description":"Submit an answer to the current challenge; grades it against the real computed answer, updates\n    score/streak, and reports the explanation. Call new_round afterward for the next challenge.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current session state, exactly as returned by a previous call.","title":"State","type":"object"},"answer":{"description":"Your answer: yes/no for boolean challenges, a number for GCD/LCM/Fibonacci, or a list of prime factors (e.g. [2,2,3,7]) for factorize.","title":"Answer"}},"required":["state","answer"],"title":"submit_answerArguments","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":"Get a real, escalating hint for the current challenge (never the final answer). Each hint taken","description":"Get a real, escalating hint for the current challenge (never the final answer). Each hint taken\n    reduces the points earned if the round is later answered correctly.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current session 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/session_stats":{"post":{"operationId":"session_stats","summary":"Report score, streak, best streak, and exact accuracy percentage for this session.","description":"Report score, streak, best streak, and exact accuracy percentage for this session.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"Current session state, exactly as returned by a previous call.","title":"State","type":"object"}},"required":["state"],"title":"session_statsArguments","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/topic_info":{"post":{"operationId":"topic_info","summary":"List the five challenge topics and what each one tests.","description":"List the five challenge topics and what each one tests.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"topic_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 FactorFib's rules, topics, difficulty scaling, and exact scoring formula.","description":"Explain FactorFib's rules, topics, difficulty scaling, and exact scoring formula.","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}}}}