{"openapi":"3.1.0","info":{"title":"Dicho (Saying) API","version":"0.1.0","description":"A hand-curated Spanish-language proverbs & sayings (dichos/refranes) reference, focused on Mexican usage with regional variants noted for Spain, Argentina and elsewhere: dicho lookups, keyword search, category browsing, an equivalent finder, a meaning explainer, regional-variant notes, usage examples, a dicho of the day, and a small category/grammar glossary with a full-list browse.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://dicho.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/dicho/docs"},"termsOfService":"https://connectorbay.com/dicho/terms"},"servers":[{"url":"https://dicho.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/dicho/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/dicho_info":{"post":{"operationId":"dicho_info","summary":"Look up one Spanish-language dicho/refrán: its Spanish text, a literal English translation, its real","description":"Look up one Spanish-language dicho/refrán: its Spanish text, a literal English translation, its real\n    meaning/lesson, the closest English equivalent idiom where one genuinely exists, and a usage example\n    sentence in Spanish with an English translation. Use for \"what does 'camarón que se duerme' mean\",\n    \"explain the saying about the gift horse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text_or_query":{"description":"A Spanish-language dicho/refrán (exact or partial), or a keyword/category to look one up by.","examples":["camarón que se duerme","caballo regalado","a falta de pan"],"minLength":1,"title":"Text Or Query","type":"string"}},"required":["text_or_query"],"title":"dicho_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/dicho_search":{"post":{"operationId":"dicho_search","summary":"Search across every dicho's Spanish text, literal translation, meaning, English equivalent and","description":"Search across every dicho's Spanish text, literal translation, meaning, English equivalent and\n    categories for a keyword. Use for \"find dichos about money\", \"any Mexican saying about patience\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search for across Spanish text, translation, meaning and category.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"dicho_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/dichos_by_category":{"post":{"operationId":"dichos_by_category","summary":"List every dicho tagged with one category -- love, money, family, work, wisdom/caution, food, or","description":"List every dicho tagged with one category -- love, money, family, work, wisdom/caution, food, or\n    time/patience. Use for \"show me Mexican sayings about family\", \"dichos about money\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"One of: love, money, family, work, wisdom_caution, food, time_patience.","minLength":1,"title":"Category","type":"string"}},"required":["category"],"title":"dichos_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/dicho_of_the_day":{"post":{"operationId":"dicho_of_the_day","summary":"A deterministic \"dicho of the day\" -- the same Spanish saying for everyone asking on a given","description":"A deterministic \"dicho of the day\" -- the same Spanish saying for everyone asking on a given\n    calendar date -- with its full explanation. Use for \"dicho of the day\", \"teach me a Mexican saying for\n    today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"dicho_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/equivalent_finder":{"post":{"operationId":"equivalent_finder","summary":"Given either an English idiom/proverb or a Spanish dicho, finds the closest match in the other","description":"Given either an English idiom/proverb or a Spanish dicho, 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 Mexican saying for 'the early bird catches the worm'\", \"is there an\n    English equivalent for 'camarón que se duerme'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"text":{"description":"Either an English idiom/proverb or a Spanish dicho.","examples":["the early bird catches the worm","camarón que se duerme, se lo lleva la corriente","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/meaning_explainer":{"post":{"operationId":"meaning_explainer","summary":"A fuller explanation of a dicho's figurative sense -- contrasting the literal, word-for-word","description":"A fuller explanation of a dicho'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, with an\n    example. Use for \"explain what 'a falta de pan, tortillas' really means and when people say it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dicho":{"description":"A Spanish-language dicho/refrán (exact or partial).","minLength":1,"title":"Dicho","type":"string"}},"required":["dicho"],"title":"meaning_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/regional_variant_note":{"post":{"operationId":"regional_variant_note","summary":"Where documented, notes whether a dicho has a known wording or usage difference across Mexico,","description":"Where documented, notes whether a dicho has a known wording or usage difference across Mexico,\n    Spain, Argentina or elsewhere in the Spanish-speaking world. Most dichos have no documented split and\n    this says so honestly rather than inventing one. Use for \"is this dicho used in Spain too\", \"does 'a\n    falta de pan' have a different version in Spain\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dicho":{"description":"A Spanish-language dicho/refrán (exact or partial).","minLength":1,"title":"Dicho","type":"string"}},"required":["dicho"],"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/usage_example":{"post":{"operationId":"usage_example","summary":"Just a dicho's example sentence: one natural usage sentence in Spanish with its English translation.","description":"Just a dicho's example sentence: one natural usage sentence in Spanish with its English translation.\n    Use for \"give me an example sentence using 'no todo lo que brilla es oro'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dicho":{"description":"A Spanish-language dicho/refrán (exact or partial).","minLength":1,"title":"Dicho","type":"string"}},"required":["dicho"],"title":"usage_exampleArguments","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 \"dicho\", \"refrán\", \"frase hecha\" and \"modismo\" as categories, plus","description":"A short glossary distinguishing \"dicho\", \"refrán\", \"frase hecha\" and \"modismo\" as categories, plus\n    grammar notes relevant to reading these sayings (the impersonal/reflexive \"se\", tú vs. vos) -- or, with\n    list_all, a lightweight browse of every dicho in the dataset. Use for \"what's the difference between a\n    dicho and a refrán\", \"what does 'se' mean in these sayings\", \"list every dicho you have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"dicho | refran | frase_hecha | modismo | se | vos; omit to list the glossary categories, or pass list_all to browse every dicho.","title":"Term"},"list_all":{"default":false,"description":"If true, ignore `term` and return the full dataset as a lightweight browse list (id, Spanish text, categories).","title":"List All","type":"boolean"}},"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}}}}