{"openapi":"3.1.0","info":{"title":"Telugu Riddles API","version":"0.1.0","description":"A fully local, hand-curated reference of real Telugu riddles (పొడుపు కథలు) and tongue twisters in native script: 35 verified riddles across five categories plus a verified tongue twister, each with Telugu text, romanized transliteration, English translation and answer, plus search, category browsing, fuzzy answer-checking and wordplay explanations.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://teluguriddles.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/teluguriddles/docs"},"termsOfService":"https://connectorbay.com/teluguriddles/terms"},"servers":[{"url":"https://teluguriddles.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/teluguriddles/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 Telugu riddle picked deterministically for a date (today by default), with its full answer. Use","description":"One Telugu riddle picked deterministically for a date (today by default), with its full answer. Use\n    for \"give me a Telugu riddle of the day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"for_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO date (YYYY-MM-DD); omit for today.","title":"For Date"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optionally restrict to one category.","title":"Category"}},"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 Telugu riddle, with the answer included by default (set hide_answer=true to guess first).","description":"A random Telugu riddle, with the answer included by default (set hide_answer=true to guess first).\n    Use for \"give me a random Telugu riddle to solve\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"hide_answer":{"default":false,"description":"If true, the answer is left out 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 filed under one category. Use categories_list to see valid category names. Use for","description":"Every riddle filed under one category. Use categories_list to see valid category names. Use for\n    \"Telugu riddles about animals\", \"list every wordplay riddle you have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"Wordplay | Body & Life | Nature | Household Objects | Animals","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 Telugu text, transliteration, English translation, answer and","description":"Keyword search across every riddle's Telugu text, transliteration, English translation, answer and\n    category. Use for \"find a Telugu riddle about the moon\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"A keyword to search for.","examples":["moon","mirror","shadow"],"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":"The verified Telugu tongue twister(s) in this reference, with Telugu text, transliteration and","description":"The verified Telugu tongue twister(s) in this reference, with Telugu text, transliteration and\n    English meaning. Use for \"give me a Telugu tongue twister\".","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-matches a guessed answer against one riddle's real answer (in Telugu, transliteration, or","description":"Fuzzy-matches a guessed answer against one riddle's real answer (in Telugu, transliteration, or\n    English) and reports whether it's close enough to count as correct. Use for \"is 'mirror' the right \"\n    \"answer to this riddle\", \"check my guess for this podupu katha\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"The riddle's Telugu text, transliteration, or a keyword from it.","minLength":1,"title":"Riddle","type":"string"},"guess":{"description":"Your guessed answer, in Telugu, transliteration, 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 filed under it. Use for \"what categories of Telugu \"","description":"Every riddle category with how many riddles are filed under it. Use for \"what categories of Telugu \"\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":"Explains, in plain language, the pun, hidden word, or visual trick behind one riddle. Use for \"explain \"","description":"Explains, in plain language, the pun, hidden word, or visual trick behind one riddle. Use for \"explain \"\n    \"the wordplay in this Telugu riddle\", \"why is the answer to this riddle a clove\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"The riddle's Telugu text, transliteration, or a keyword from it.","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}}}}