{"openapi":"3.1.0","info":{"title":"Ditado (Saying) API","version":"0.1.0","description":"A hand-curated Brazilian Portuguese proverbs & idiomatic-sayings (ditados populares) reference: saying lookups, keyword search, theme browsing, an equivalent finder, regional (PT vs BR) notes, a literal-vs-idiomatic explainer, a saying of the day, and a small category/grammar glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://ditado.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/ditado/docs"},"termsOfService":"https://connectorbay.com/ditado/terms"},"servers":[{"url":"https://ditado.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/ditado/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/saying_info":{"post":{"operationId":"saying_info","summary":"Look up one Brazilian Portuguese ditado/provérbio: its Portuguese text, a literal English","description":"Look up one Brazilian Portuguese ditado/provérbio: its Portuguese text, a literal English\n    translation, its real meaning/lesson, the closest English equivalent idiom where one genuinely exists,\n    and a usage example sentence in Portuguese with an English translation. Use for \"what does 'água mole\n    em pedra dura' mean\", \"explain the saying about the gift horse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text_or_query":{"description":"A Brazilian Portuguese saying (exact or partial), or a keyword/theme to look one up by.","examples":["água mole em pedra dura","cavalo dado","farinha pouca"],"minLength":1,"title":"Text Or Query","type":"string"}},"required":["text_or_query"],"title":"saying_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/saying_search":{"post":{"operationId":"saying_search","summary":"Search across every saying's Portuguese text, literal translation, meaning, English equivalent and","description":"Search across every saying's Portuguese text, literal translation, meaning, English equivalent and\n    themes for a keyword. Use for \"find sayings about money\", \"any Brazilian proverb about patience\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for across Portuguese text, translation, meaning and theme.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"saying_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/sayings_by_theme":{"post":{"operationId":"sayings_by_theme","summary":"List every saying tagged with one theme -- friendship, money, time, wisdom/patience, love,","description":"List every saying tagged with one theme -- friendship, money, time, wisdom/patience, love,\n    work/perseverance, caution/prudence, or family. Use for \"show me Brazilian sayings about friendship\",\n    \"proverbs about money in Portuguese\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"theme":{"description":"One of: friendship, money, time, wisdom_patience, love, work_perseverance, caution_prudence, family.","minLength":1,"title":"Theme","type":"string"}},"required":["theme"],"title":"sayings_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/random_saying":{"post":{"operationId":"random_saying","summary":"A random Brazilian Portuguese saying from the full dataset. Use for \"give me a random Brazilian","description":"A random Brazilian Portuguese saying from the full dataset. Use for \"give me a random Brazilian\n    proverb\", \"teach me a Portuguese saying\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seed":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Optional seed for a reproducible pick.","title":"Seed"}},"title":"random_sayingArguments","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/equivalent_finder":{"post":{"operationId":"equivalent_finder","summary":"Given either an English idiom/proverb or a Portuguese saying, finds the closest match in the other","description":"Given either an English idiom/proverb or a Portuguese saying, finds the closest match in the other\n    language from this dataset -- only when a genuinely close equivalent exists in the bundled data, never\n    a forced match. Use for \"what's the Brazilian saying for 'the grass is greener'\", \"is there an English\n    equivalent for 'água mole em pedra dura'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text":{"description":"Either an English idiom/proverb or a Brazilian Portuguese saying.","examples":["the grass is greener","água mole em pedra dura","don't look a gift horse in the mouth"],"minLength":1,"title":"Text","type":"string"}},"required":["text"],"title":"equivalent_finderArguments","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/regional_variant_note":{"post":{"operationId":"regional_variant_note","summary":"Where documented, notes whether a saying has a known wording or usage difference between European","description":"Where documented, notes whether a saying has a known wording or usage difference between European\n    Portuguese and Brazilian Portuguese. Most sayings have no documented split and this says so honestly\n    rather than inventing one. Use for \"is this saying used in Portugal too\", \"does 'água mole' have a\n    Portugal version\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"saying":{"description":"A Brazilian Portuguese saying (exact or partial).","minLength":1,"title":"Saying","type":"string"}},"required":["saying"],"title":"regional_variant_noteArguments","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/saying_of_the_day":{"post":{"operationId":"saying_of_the_day","summary":"A deterministic \"saying of the day\" -- the same ditado for everyone asking on a given calendar","description":"A deterministic \"saying of the day\" -- the same ditado for everyone asking on a given calendar\n    date -- with its full explanation. Use for \"saying of the day\", \"teach me a Brazilian proverb for\n    today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"saying_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/literal_vs_idiomatic_explainer":{"post":{"operationId":"literal_vs_idiomatic_explainer","summary":"Explicitly contrasts a saying's word-for-word literal translation against what it actually,","description":"Explicitly contrasts a saying's word-for-word literal translation against what it actually,\n    idiomatically means -- built for language learners who'd otherwise be confused reading it literally.\n    Use for \"what does 'farinha pouca, meu pirão primeiro' literally say vs actually mean\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"saying":{"description":"A Brazilian Portuguese saying (exact or partial).","minLength":1,"title":"Saying","type":"string"}},"required":["saying"],"title":"literal_vs_idiomatic_explainerArguments","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/glossary":{"post":{"operationId":"glossary","summary":"A short glossary distinguishing \"ditado\", \"provérbio\", \"gíria\" and \"expressão idiomática\" as","description":"A short glossary distinguishing \"ditado\", \"provérbio\", \"gíria\" and \"expressão idiomática\" as\n    categories, plus grammar notes relevant to reading these sayings (the indefinite \"quem\", the\n    reflexive/impersonal \"se\"). Use for \"what's the difference between a ditado and a provérbio\", \"what\n    does 'quem' mean in these sayings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ditado | proverbio | giria | expressao_idiomatica | pronomes | se; omit to list all.","title":"Term"}},"title":"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}}}}