{"openapi":"3.1.0","info":{"title":"Amthal (Proverb) API","version":"0.1.0","description":"A hand-curated Arabic proverbs & sayings (amthal) reference spanning classical/MSA proverbs and well-known regional-dialect sayings from the Levant, Egypt, the Gulf and the Maghreb: proverb lookups, keyword search, theme and region browsing, an English-equivalent finder, a meaning explainer, a proverb of the day, and a small glossary of Arabic proverb/oral-wisdom terms.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://amthal.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/amthal/docs"},"termsOfService":"https://connectorbay.com/amthal/terms"},"servers":[{"url":"https://amthal.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/amthal/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/proverb_of_the_day":{"post":{"operationId":"proverb_of_the_day","summary":"A deterministic \"proverb of the day\" -- the same Arabic proverb for everyone asking on a given","description":"A deterministic \"proverb of the day\" -- the same Arabic proverb for everyone asking on a given\n    calendar date -- with its Arabic text, transliteration, literal translation and meaning. Use for\n    \"proverb of the day\", \"teach me an Arabic saying for today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"proverb_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/proverb_search":{"post":{"operationId":"proverb_search","summary":"Search across every proverb's Arabic text, transliteration, literal translation, meaning, English","description":"Search across every proverb's Arabic text, transliteration, literal translation, meaning, English\n    equivalent and themes for a keyword. Use for \"find proverbs about patience\", \"any Egyptian saying about\n    money\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for across Arabic text, transliteration, translation, meaning and theme.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"proverb_searchArguments","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/proverb_info":{"post":{"operationId":"proverb_info","summary":"Look up one Arabic proverb: its Arabic text, transliteration, a literal English translation, its real","description":"Look up one Arabic proverb: its Arabic text, transliteration, a literal English translation, its real\n    figurative meaning, its region, and the closest English equivalent where one genuinely exists. Use for\n    \"what does 'al-sabru miftahu al-faraj' mean\", \"explain the proverb about the gazelle\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text":{"description":"An Arabic proverb (script or transliteration, exact or partial), or a keyword to look one up by.","examples":["الصبر مفتاح الفرج","as-sabru miftahu al-faraj","camel's crooked neck"],"minLength":1,"title":"Text","type":"string"}},"required":["text"],"title":"proverb_infoArguments","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/proverbs_by_theme":{"post":{"operationId":"proverbs_by_theme","summary":"List every proverb tagged with one theme -- patience, wisdom, family, hospitality, time, friendship,","description":"List every proverb tagged with one theme -- patience, wisdom, family, hospitality, time, friendship,\n    money, work, speech, fate, food, or caution. Use for \"show me Arabic proverbs about hospitality\",\n    \"sayings about patience\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"theme":{"description":"One of: patience, wisdom, family, hospitality, time, friendship, money, work, speech, fate, food, caution.","minLength":1,"title":"Theme","type":"string"}},"required":["theme"],"title":"proverbs_by_themeArguments","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/proverbs_by_region":{"post":{"operationId":"proverbs_by_region","summary":"List every proverb from one region -- pan-Arab/classical (Modern Standard Arabic, shared widely","description":"List every proverb from one region -- pan-Arab/classical (Modern Standard Arabic, shared widely\n    across the Arab world), Levantine, Egyptian, Gulf, or Maghrebi. Use for \"Gulf proverbs\", \"Levantine\n    sayings about family\", \"classical Arabic proverbs about wisdom\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"One of: pan_arab (classical/MSA, shared widely), levantine, egyptian, gulf, maghrebi.","minLength":1,"title":"Region","type":"string"}},"required":["region"],"title":"proverbs_by_regionArguments","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_proverb":{"post":{"operationId":"random_proverb","summary":"A random Arabic proverb, optionally restricted to one theme. Use for \"give me a random Arabic","description":"A random Arabic proverb, optionally restricted to one theme. Use for \"give me a random Arabic\n    proverb\", \"surprise me with a saying about friendship\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"theme":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional theme to restrict the pick to; omit for any proverb in the dataset.","title":"Theme"}},"title":"random_proverbArguments","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/english_equivalent":{"post":{"operationId":"english_equivalent","summary":"Given either an Arabic proverb or an English idiom/proverb, finds the closest match in the other","description":"Given either an Arabic proverb or an English idiom/proverb, finds the closest match in the other\n    language from this dataset, only when a genuinely close equivalent exists -- never a forced match --\n    together with a note on how close the match is (exact / close / loose). Use for \"what's the English\n    equivalent of 'the early bird catches the worm' in Arabic\", \"is there an Arabic saying like 'too many\n    cooks spoil the broth'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"proverb":{"description":"Either an Arabic proverb (script or transliteration) or an English idiom/proverb.","examples":["الطيور على أشكالها تقع","at-tuyuru 'ala ashkaliha taqa'u","birds of a feather flock together"],"minLength":1,"title":"Proverb","type":"string"}},"required":["proverb"],"title":"english_equivalentArguments","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_meaning":{"post":{"operationId":"explain_meaning","summary":"A fuller explanation of a proverb's figurative sense -- contrasting the literal, word-for-word","description":"A fuller explanation of a proverb's figurative sense -- contrasting the literal, word-for-word\n    translation with what it actually means -- plus the typical context in which it gets said. Use for\n    \"explain what the camel's crooked neck proverb really means and when people say it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"proverb":{"description":"An Arabic proverb (script or transliteration, exact or partial).","minLength":1,"title":"Proverb","type":"string"}},"required":["proverb"],"title":"explain_meaningArguments","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/proverb_glossary":{"post":{"operationId":"proverb_glossary","summary":"A short glossary of ten terms about the Arabic proverb and oral-wisdom tradition: mathal, hikma, qawl","description":"A short glossary of ten terms about the Arabic proverb and oral-wisdom tradition: mathal, hikma, qawl\n    ma'thur, mathal sha'bi, fusha, ammiyya/darija, kinaya, saj' (rhymed prose), Majma' al-Amthal (the\n    classical al-Maydani compilation), and amthal al-'arab. Use for \"what's the difference between a mathal\n    and a hikma\", \"what does fusha mean\", \"what is Majma' al-Amthal\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"mathal | hikma | qawl_mathur | mathal_shaabi | fusha | ammiyya | kinaya | saj | majma_al-amthal | amthal_al-arab; omit to list all ten terms.","title":"Term"}},"title":"proverb_glossaryArguments","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}}}}