{"openapi":"3.1.0","info":{"title":"Riddle Duel API","version":"0.1.0","description":"A fully local, playable riddle game session over 100+ original, hand-authored riddles, with real fuzzy answer matching and exact hint-penalty scoring. 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://riddleduel.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/riddleduel/docs"},"termsOfService":"https://connectorbay.com/riddleduel/terms"},"servers":[{"url":"https://riddleduel.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/riddleduel/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 Riddle Duel session: build a shuffled, no-repeat pool of riddles (optionally filtered","description":"Start a new Riddle Duel session: build a shuffled, no-repeat pool of riddles (optionally filtered\n    by category/difficulty) and serve the first one. Use for \"let's play a riddle game\", \"give me a hard\n    math riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Restrict to one category: wordplay, object, nature, body, tech, math, tricky. Omit for all.","title":"Category"},"difficulty":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Restrict to 'easy', 'medium', or 'hard'. Omit for all.","title":"Difficulty"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional RNG seed for a reproducible pool order (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/next_riddle":{"post":{"operationId":"next_riddle","summary":"Serve the next riddle from the pool (any unresolved current riddle is counted as skipped). Reports","description":"Serve the next riddle from the pool (any unresolved current riddle is counted as skipped). Reports\n    when the pool is exhausted instead of repeating a riddle.","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":"next_riddleArguments","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":"Check a guess against the current riddle's answer using real fuzzy matching. Scores it (with a","description":"Check a guess against the current riddle's answer using real fuzzy matching. Scores it (with a\n    hint penalty) if correct; wrong guesses can be retried.","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"},"guess":{"description":"Your answer to the current riddle.","title":"Guess","type":"string"}},"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/get_hint":{"post":{"operationId":"get_hint","summary":"Reveal the next of up to 2 escalating hints for the current riddle. Costs points if the riddle is","description":"Reveal the next of up to 2 escalating hints for the current riddle. Costs points if the riddle is\n    later solved.","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/give_up":{"post":{"operationId":"give_up","summary":"Give up on the current riddle and reveal its answer (scores 0 for this riddle).","description":"Give up on the current riddle and reveal its answer (scores 0 for this riddle).","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":"give_upArguments","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 the session tally: riddles seen, solved, skipped, given up on, score, and pool remaining.","description":"Report the session tally: riddles seen, solved, skipped, given up on, score, and pool remaining.","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/list_categories":{"post":{"operationId":"list_categories","summary":"List riddle categories with a difficulty breakdown and counts.","description":"List riddle categories with a difficulty breakdown and counts.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_categoriesArguments","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 Riddle Duel's rules: pooling, fuzzy matching, and exact scoring.","description":"Explain Riddle Duel's rules: pooling, fuzzy matching, and exact scoring.","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}}}}