{"openapi":"3.1.0","info":{"title":"Riddle API","version":"0.1.0","description":"A fully local, hand-curated riddle and brain-teaser reference: 50+ riddles across wordplay, logic, lateral-thinking, classic/traditional and math categories, each with a difficulty rating, a stored answer, an optional hint and a short explanation, plus a fuzzy-matched guess checker and a riddle/puzzle-terms glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://riddle.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/riddle/docs"},"termsOfService":"https://connectorbay.com/riddle/terms"},"servers":[{"url":"https://riddle.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/riddle/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/riddle_by_category":{"post":{"operationId":"riddle_by_category","summary":"Every riddle in one category, as plain riddle text with its id, difficulty, and whether it has a hint —","description":"Every riddle in one category, as plain riddle text with its id, difficulty, and whether it has a hint —\n    never the answer, so browsing a category doesn't spoil anything. Use riddle_answer or submit_guess once\n    you've picked one. Use category_list to see valid category names. Use for \"give me all the logic riddles\",\n    \"list your math riddles\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A category name.","examples":["wordplay","logic","lateral-thinking","classic","math"],"minLength":1,"title":"Category","type":"string"}},"required":["category"],"title":"riddle_by_categoryArguments","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/random_riddle":{"post":{"operationId":"random_riddle","summary":"Returns one riddle at random, optionally restricted to a category — as plain riddle text with its id,","description":"Returns one riddle at random, optionally restricted to a category — as plain riddle text with its id,\n    difficulty, and whether it has a hint, never the answer. Use riddle_answer or submit_guess afterward. Use\n    for \"give me a riddle\", \"tell me a random brain teaser\", \"give me a hard math riddle\" (pair with\n    difficulty_level, or just ask again for a different random pick).","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Restrict to one category; omit for any category.","examples":["wordplay","logic","classic"],"title":"Category"}},"title":"random_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/riddle_answer":{"post":{"operationId":"riddle_answer","summary":"Reveals one riddle's answer, its explanation, and its origin note (public-domain/traditional vs.","description":"Reveals one riddle's answer, its explanation, and its origin note (public-domain/traditional vs.\n    original). Use once you're ready to see the solution, or to check your own reasoning after solving it. Use\n    for \"what's the answer to this riddle\", \"reveal the solution\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle_id":{"description":"A riddle's id, as returned by riddle_by_category or random_riddle.","examples":["sphinx_riddle","keys_no_locks"],"minLength":1,"title":"Riddle Id","type":"string"}},"required":["riddle_id"],"title":"riddle_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/riddle_hint":{"post":{"operationId":"riddle_hint","summary":"Reveals one riddle's hint, without giving away the answer itself. Not every riddle has a hint on file;","description":"Reveals one riddle's hint, without giving away the answer itself. Not every riddle has a hint on file;\n    when one doesn't, this says so instead of guessing at one. Use for \"give me a hint\", \"I'm stuck, help a\n    little\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle_id":{"description":"A riddle's id, as returned by riddle_by_category or random_riddle.","examples":["sphinx_riddle","the_queue"],"minLength":1,"title":"Riddle Id","type":"string"}},"required":["riddle_id"],"title":"riddle_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/submit_guess":{"post":{"operationId":"submit_guess","summary":"Checks a free-text guess against a riddle's stored answer, using fuzzy matching so small differences in","description":"Checks a free-text guess against a riddle's stored answer, using fuzzy matching so small differences in\n    wording, articles ('a'/'the'), or spelling don't count against you. Never reveals the correct answer on a\n    wrong guess — use riddle_answer for that. On a correct guess, also returns the explanation. Use for \"is\n    'a shoe' the right answer\", \"check my guess for this riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle_id":{"description":"A riddle's id, as returned by riddle_by_category or random_riddle.","examples":["keys_no_locks"],"minLength":1,"title":"Riddle Id","type":"string"},"guess":{"description":"Your free-text guess at the answer.","examples":["a keyboard","keyboard"],"minLength":1,"title":"Guess","type":"string"}},"required":["riddle_id","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/difficulty_level":{"post":{"operationId":"difficulty_level","summary":"Reports one riddle's difficulty rating (1 = easiest, 5 = hardest), its qualitative label (easy/medium/","description":"Reports one riddle's difficulty rating (1 = easiest, 5 = hardest), its qualitative label (easy/medium/\n    hard), and a short description of what that rating means in practice. Use for \"how hard is this riddle\",\n    \"is this an easy one\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle_id":{"description":"A riddle's id, as returned by riddle_by_category or random_riddle.","examples":["reversed_digits_36"],"minLength":1,"title":"Riddle Id","type":"string"}},"required":["riddle_id"],"title":"difficulty_levelArguments","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/term_glossary":{"post":{"operationId":"term_glossary","summary":"Definitions of common riddle/brain-teaser terms — lateral thinking, red herring, pun, homophone,","description":"Definitions of common riddle/brain-teaser terms — lateral thinking, red herring, pun, homophone,\n    palindrome, anagram, knights and knaves, trick question, and more. Use for \"what does 'lateral thinking'\n    mean\", \"what's a red herring in a riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"term_glossaryArguments","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/category_list":{"post":{"operationId":"category_list","summary":"Every riddle category (Wordplay, Logic, Lateral Thinking, Classic & Traditional, Math) with how many","description":"Every riddle category (Wordplay, Logic, Lateral Thinking, Classic & Traditional, Math) with how many\n    riddles are in each. Use for \"what kinds of riddles do you have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"category_listArguments","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}}}}