{"openapi":"3.1.0","info":{"title":"Malayalam Riddles API","version":"0.1.0","description":"A hand-curated reference of Malayalam riddles (kadamkathakal) and tongue twisters: real Malayalam script verified against a published collection, romanized transliteration, and English meaning/answer for each. Riddle of the day, random riddle (with an optional hidden answer for a guessing game), browsing by category, keyword search, tongue twisters, fuzzy answer-checking, and a wordplay explainer.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://malayalamriddles.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/malayalamriddles/docs"},"termsOfService":"https://connectorbay.com/malayalamriddles/terms"},"servers":[{"url":"https://malayalamriddles.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/malayalamriddles/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_of_the_day":{"post":{"operationId":"riddle_of_the_day","summary":"A deterministic 'riddle of the day' — the same Malayalam riddle, with its answer and explanation, for","description":"A deterministic 'riddle of the day' — the same Malayalam riddle, with its answer and explanation, for\n    everyone who asks on a given date. Use for \"give me today's Malayalam riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO date (YYYY-MM-DD) to pick for; omit for today. Same date always gives the same riddle.","title":"Date"}},"title":"riddle_of_the_dayArguments","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":"A random Malayalam riddle, optionally limited to one category, with the answer optionally hidden for a","description":"A random Malayalam riddle, optionally limited to one category, with the answer optionally hidden for a\n    guessing game (pair with check_answer). Use for \"give me a random Malayalam riddle to solve\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one category; omit for any riddle.","title":"Category"},"hide_answer":{"default":false,"description":"If true, the answer and explanation are left out — useful for a guessing game.","title":"Hide Answer","type":"boolean"},"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional seed for a reproducible pick.","title":"Seed"}},"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/riddles_by_category":{"post":{"operationId":"riddles_by_category","summary":"Every riddle filed under one category. Use categories_list to see valid category names. Use for \"list","description":"Every riddle filed under one category. Use categories_list to see valid category names. Use for \"list\n    Malayalam riddles about animals\", \"show me riddles about food and plants\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A category name — see categories_list.","examples":["Animals & Insects","Nature & Sky","Body Parts"],"minLength":1,"title":"Category","type":"string"}},"required":["category"],"title":"riddles_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/search_riddles":{"post":{"operationId":"search_riddles","summary":"Keyword search across every riddle's text, transliteration, English gloss, answer and category. Use for","description":"Keyword search across every riddle's text, transliteration, English gloss, answer and category. Use for\n    \"find a Malayalam riddle about the moon\", \"riddles whose answer is an egg\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for, in English or transliterated Malayalam.","examples":["moon","elephant","egg","coconut"],"minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"search_riddlesArguments","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/tongue_twisters":{"post":{"operationId":"tongue_twisters","summary":"Every Malayalam tongue twister in this reference, each with its Malayalam script, transliteration, and","description":"Every Malayalam tongue twister in this reference, each with its Malayalam script, transliteration, and\n    English translation. Use for \"give me a Malayalam tongue twister\", \"something hard to say fast in\n    Malayalam\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"tongue_twistersArguments","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/check_answer":{"post":{"operationId":"check_answer","summary":"Fuzzy-checks a free-text guess (English or Malayalam, exact or approximate) against a riddle's real","description":"Fuzzy-checks a free-text guess (English or Malayalam, exact or approximate) against a riddle's real\n    answer, returning whether it counts as correct and a similarity score. Use for \"does 'nose' answer this\n    riddle\", \"check my guess for this kadamkatha\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"A riddle's id, Malayalam text, or transliteration.","minLength":1,"title":"Riddle","type":"string"},"guess":{"description":"A free-text guess at the answer, in English or Malayalam.","minLength":1,"title":"Guess","type":"string"}},"required":["riddle","guess"],"title":"check_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/categories_list":{"post":{"operationId":"categories_list","summary":"Every riddle category with how many riddles are filed under each. Use for \"what categories of Malayalam","description":"Every riddle category with how many riddles are filed under each. Use for \"what categories of Malayalam\n    riddles do you have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"categories_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}},"/v1/tools/explain_wordplay":{"post":{"operationId":"explain_wordplay","summary":"The full breakdown of one riddle: its Malayalam text, transliteration, English gloss, answer, and an","description":"The full breakdown of one riddle: its Malayalam text, transliteration, English gloss, answer, and an\n    explanation of the metaphor or wordplay that makes it work. Use for \"explain this Malayalam riddle\", \"why is\n    the answer to this kadamkatha what it is\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"A riddle's id, Malayalam text, or transliteration.","minLength":1,"title":"Riddle","type":"string"}},"required":["riddle"],"title":"explain_wordplayArguments","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}}}}