{"openapi":"3.1.0","info":{"title":"Hindi Riddles API","version":"0.1.0","description":"A fully local, hand-curated reference of 26 Hindi riddles (paheliyan) and 24 tongue twisters in Devanagari script, each with a romanized transliteration, English meaning, and a wordplay explanation. Search by keyword or category, get a riddle of the day, fuzzy-check a guessed answer, browse tongue twisters, and get a wordplay explanation for any entry.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://hindiriddles.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/hindiriddles/docs"},"termsOfService":"https://connectorbay.com/hindiriddles/terms"},"servers":[{"url":"https://hindiriddles.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/hindiriddles/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 Hindi riddle (paheli), deterministically chosen for a given date (or today), answer","description":"One Hindi riddle (paheli), deterministically chosen for a given date (or today), answer\n    included. Use for \"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.","examples":["2026-09-25"],"title":"For 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 randomly chosen Hindi riddle. Set reveal_answer=false to get only the question, so you can","description":"A randomly chosen Hindi riddle. Set reveal_answer=false to get only the question, so you can\n    quiz someone else and check their guess with check_answer. Use for \"give me a Hindi riddle to\n    guess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seed":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional seed for a reproducible pick.","title":"Seed"},"reveal_answer":{"default":true,"description":"Set false to get just the question, e.g. to quiz someone else.","title":"Reveal 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 whose answer falls in one category. Use categories_list for valid names. Use for","description":"Every riddle whose answer falls in one category. Use categories_list for valid names. Use for\n    \"Hindi riddles about animals\", \"food riddles in Hindi\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A category name.","examples":["animals","food","logic & wit"],"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 question, answer and category, in Hindi or English. Use","description":"Keyword search across every riddle's question, answer and category, in Hindi or English. Use\n    for \"riddle about a moustache\", \"Hindi riddle with the answer coal\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for, in Hindi or English.","examples":["moustache","पानी","wheel"],"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":"Lists Hindi tongue twisters (Devanagari, transliteration, English gloss, and the sound pattern","description":"Lists Hindi tongue twisters (Devanagari, transliteration, English gloss, and the sound pattern\n    that makes each one hard to say fast), optionally filtered by keyword. Use for \"give me a Hindi\n    tongue twister\", \"hard Hindi tongue twisters with ch sounds\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional keyword to filter by; omit to list all.","title":"Query"}},"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, tolerant of small spelling or spacing","description":"Fuzzy-checks a guessed answer against one riddle, tolerant of small spelling or spacing\n    differences, and always returns the real answer. Use for \"is 'mendhak' the right answer to this\n    riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"A riddle's id or its Devanagari question text.","minLength":1,"title":"Riddle","type":"string"},"guess":{"description":"The guessed answer, in Hindi, 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 each (by what the answer is —","description":"Every riddle category with how many riddles are filed under each (by what the answer is —\n    animals, food, household objects, and so on). Use for \"what riddle categories do you cover\".","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 the metaphor, pun, or sound pattern behind a riddle or a tongue twister. Use for \"why","description":"Explains the metaphor, pun, or sound pattern behind a riddle or a tongue twister. Use for \"why\n    does this riddle work\", \"what makes this tongue twister hard to say\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item":{"description":"A riddle's id/question, or a tongue twister's id/text.","minLength":1,"title":"Item","type":"string"}},"required":["item"],"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}}}}