{"openapi":"3.1.0","info":{"title":"Tamil Riddles API","version":"0.1.0","description":"A fully local, hand-curated collection of traditional Tamil riddles and tongue twisters: Tamil script, romanization, translation, answer and wordplay explanation for each riddle, plus a tongue-twister collection.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://tamilriddles.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/tamilriddles/docs"},"termsOfService":"https://connectorbay.com/tamilriddles/terms"},"servers":[{"url":"https://tamilriddles.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/tamilriddles/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":"One featured Tamil riddle (with its answer), rotating daily. Use for \"give me a Tamil riddle","description":"One featured Tamil riddle (with its answer), rotating daily. Use for \"give me a Tamil riddle\n    of the day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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 Tamil riddle. Set hide_answer to play a guessing game, then use check_answer. Use for","description":"A random Tamil riddle. Set hide_answer to play a guessing game, then use check_answer. Use for\n    \"give me a random Tamil riddle to guess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"hide_answer":{"default":false,"description":"If true, omits the answer fields so you can guess first.","title":"Hide Answer","type":"boolean"}},"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 in one category (nature, animals, food, household, objects, body, wordplay). Use","description":"Every riddle in one category (nature, animals, food, household, objects, body, wordplay). Use\n    categories_list to see valid names. Use for \"list Tamil animal riddles\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A category name.","examples":["nature","animals","household"],"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 Tamil text, romanization, English translation and answer.","description":"Keyword search across every riddle's Tamil text, romanization, English translation and answer.\n    Use for \"find a Tamil riddle about the moon\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for.","examples":["moon","coconut","snail"],"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 Tamil tongue twister in this collection, with a note on what sounds each one drills. Use","description":"Every Tamil tongue twister in this collection, with a note on what sounds each one drills. Use\n    for \"give me a Tamil tongue twister\", \"hard Tamil sentences to practice saying fast\".","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 guessed answer against one riddle's real answer (Tamil, romanized or English all","description":"Fuzzy-checks a guessed answer against one riddle's real answer (Tamil, romanized or English all\n    accepted) and reports whether it's close enough to count as correct. Use for \"is 'thengaai' the\n    right answer to this riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"A riddle's id or its Tamil/romanized text.","minLength":1,"title":"Riddle","type":"string"},"guess":{"description":"Your guessed answer, in Tamil, romanized, or English.","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 in it. Use for \"what categories of Tamil","description":"Every riddle category with how many riddles are in it. Use for \"what categories of Tamil\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":"Just the wordplay/imagery explanation for one riddle, without repeating its full entry. Use for","description":"Just the wordplay/imagery explanation for one riddle, without repeating its full entry. Use for\n    \"why is the answer to this riddle a mirror\", \"explain the trick in this Tamil riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"A riddle's id or its Tamil/romanized text.","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}}}}