{"openapi":"3.1.0","info":{"title":"Urdu Riddles API","version":"0.1.0","description":"A fully local, hand-curated reference to Urdu riddles (paheliyan) and tongue twisters: 39 riddles plus 6 tongue twisters, each in real Urdu (Perso-Arabic Nastaliq) script with a romanized transliteration, English hint and, for wordplay riddles, a linguistic pun explanation.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://urduriddles.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/urduriddles/docs"},"termsOfService":"https://connectorbay.com/urduriddles/terms"},"servers":[{"url":"https://urduriddles.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/urduriddles/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 riddle, the same for everyone on a given calendar day. Use for \"Urdu riddle of the day\".","description":"One riddle, the same for everyone on a given calendar day. Use for \"Urdu riddle of the day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"reveal_answer":{"default":true,"description":"Set false to get the riddle without its answer, for guessing.","title":"Reveal Answer","type":"boolean"}},"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 riddle (different each call). Use for \"give me a random Urdu riddle to guess\".","description":"A randomly chosen riddle (different each call). Use for \"give me a random Urdu riddle to guess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"reveal_answer":{"default":true,"description":"Set false to get the riddle without its answer, for guessing.","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 (or tongue twister) in one category. Use categories_list for valid names. Use for \"list","description":"Every riddle (or tongue twister) in one category. Use categories_list for valid names. Use for \"list\n    Urdu wordplay riddles\", \"logic riddles in Urdu\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A category name.","examples":["Wordplay & Wit","Nature & Objects","Tongue Twisters"],"title":"Category","type":"string"},"reveal_answer":{"default":true,"description":"Set false to hide answers.","title":"Reveal Answer","type":"boolean"}},"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, hint and category. Use for \"Urdu riddle about","description":"Keyword search across every riddle's question, answer, hint and category. Use for \"Urdu riddle about\n    the moon\", \"any paheli with the answer clock\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword — English or romanized Urdu.","examples":["moon","clock","shirt"],"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 tongue twister (zabaan paich), each with a romanized transliteration, English translation and","description":"Every tongue twister (zabaan paich), each with a romanized transliteration, English translation and\n    a note on what makes it hard to say. Use for \"give me an Urdu 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 — a close or partial guess (a typo, a","description":"Fuzzy-matches a guessed answer against one riddle's real answer — a close or partial guess (a typo, a\n    partial word, English instead of Urdu) still counts as correct. Use for \"is 'car' the right answer to\n    this riddle\", \"check my guess for the moon riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"The riddle's id or a distinctive word from its question.","minLength":1,"title":"Riddle","type":"string"},"guess":{"description":"The guessed answer, in English or romanized Urdu.","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 category (including Tongue Twisters) with how many entries it has. Use for \"what kinds of","description":"Every category (including Tongue Twisters) with how many entries it has. Use for \"what kinds of\n    Urdu 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 linguistic explanation of the pun or wordplay behind one riddle or tongue twister (many riddles","description":"The linguistic explanation of the pun or wordplay behind one riddle or tongue twister (many riddles\n    are plain object riddles with no pun — this says so clearly rather than inventing one). Use for \"explain\n    the wordplay in the shirt riddle\", \"why is the tongue twister about nazar hard to say\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle":{"description":"A riddle's id or a distinctive word from its question, or a tongue twister's id.","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}}}}