{"openapi":"3.1.0","info":{"title":"Punjabi Riddles API","version":"0.1.0","description":"A fully local, hand-curated reference of traditional Punjabi (Gurmukhi-script) folk riddles and alliterative wordplay, each verified against a real source: riddle of the day, random riddle, category browsing, keyword search, 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://punjabiriddles.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/punjabiriddles/docs"},"termsOfService":"https://connectorbay.com/punjabiriddles/terms"},"servers":[{"url":"https://punjabiriddles.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/punjabiriddles/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 Punjabi riddle, deterministically chosen by today's date so it's the same for everyone all day. The","description":"One Punjabi riddle, deterministically chosen by today's date so it's the same for everyone all day. The\n    answer is included — use random_riddle if you want to guess first. Use for \"Punjabi riddle 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 randomly chosen Punjabi riddle, answer included. Use for \"give me a random Punjabi riddle\", \"surprise me","description":"A randomly chosen Punjabi riddle, answer included. Use for \"give me a random Punjabi riddle\", \"surprise me\n    with a riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional seed for reproducible randomness.","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 in one category. Use categories_list to see valid category names. Use for \"Punjabi riddles","description":"Every riddle in one category. Use categories_list to see valid category names. Use for \"Punjabi riddles\n    about animals\", \"self-answering Punjabi riddle-poems\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"A category name.","examples":["Nature & Sky","Animals","Mukri (Self-Answering)"],"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 Gurmukhi text, romanization, English hint, answer and category. Use","description":"Keyword search across every riddle's Gurmukhi text, romanization, English hint, answer and category. Use\n    for \"Punjabi riddle about the moon\", \"riddle with answer comb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for.","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":"Short alliterative and reduplicative wordplay phrases drawn from the Punjabi oral riddle tradition — prized","description":"Short alliterative and reduplicative wordplay phrases drawn from the Punjabi oral riddle tradition — prized\n    for their sound play (repeated consonants, rhyming doubled words) rather than attested as a separate canonical\n    tongue-twister genre. Use for \"Punjabi tongue twisters\", \"alliterative Punjabi phrases\".","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 a riddle's real answer — close wording, partial words, or a","description":"Fuzzy-matches a guessed answer against a riddle's real answer — close wording, partial words, or a\n    plausible synonym still count as correct. Use for \"is 'lamp' the right answer to this riddle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"riddle_id":{"description":"A riddle's id (from a search or category result).","minLength":1,"title":"Riddle Id","type":"string"},"guess":{"description":"Your guessed answer, in English or romanized Punjabi.","minLength":1,"title":"Guess","type":"string"}},"required":["riddle_id","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 tagged under it. Use for \"what categories of Punjabi","description":"Every riddle category with how many riddles are tagged under it. Use for \"what categories of Punjabi\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 the sound pattern — alliteration, reduplication, or rhyme — behind one wordplay phrase, and which","description":"Explains the sound pattern — alliteration, reduplication, or rhyme — behind one wordplay phrase, and which\n    riddle it comes from. Use for \"explain the wordplay in this Punjabi phrase\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"wordplay_id":{"description":"A wordplay phrase's id (from the tongue_twisters result).","minLength":1,"title":"Wordplay Id","type":"string"}},"required":["wordplay_id"],"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}}}}