{"openapi":"3.1.0","info":{"title":"Qahwa (Coffee) API","version":"0.1.0","description":"A fully local Arabic/Gulf coffee-culture reference: regional gahwa/qahwa preparation styles with real ratios, the dallah-and-finjan serving ritual, hospitality etiquette, equipment, pairings, hospitality phrases, and the coffee ceremony's UNESCO-recognized cultural significance.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://qahwa.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/qahwa/docs"},"termsOfService":"https://connectorbay.com/qahwa/terms"},"servers":[{"url":"https://qahwa.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/qahwa/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/qahwa_recipe":{"post":{"operationId":"qahwa_recipe","summary":"The traditional preparation method for a regional Arabic-coffee style — Saudi/Khaleeji (very light roast,","description":"The traditional preparation method for a regional Arabic-coffee style — Saudi/Khaleeji (very light roast,\n    cardamom and often saffron, unsweetened), Levantine (medium/dark roast, fine grind, boiled, usually\n    sweetened), or Yemeni (ginger-forward, or the husk-based qishr) — with a real published coffee:water:cardamom\n    ratio for each. Omit style to get all three. Use for \"how do you make Saudi qahwa\", \"what's the ratio for\n    Yemeni coffee\", \"how is Levantine Arabic coffee made\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"style":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Regional style: saudi_khaleeji | levantine | yemeni. Omit to list all three.","title":"Style"}},"title":"qahwa_recipeArguments","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/serving_etiquette_guide":{"post":{"operationId":"serving_etiquette_guide","summary":"Arabic-coffee hospitality customs: serving order (the eldest or most honored guest first), the right-hand","description":"Arabic-coffee hospitality customs: serving order (the eldest or most honored guest first), the right-hand\n    serving and pouring convention, how full the cup is traditionally filled, the shake-the-cup gesture used to\n    decline a refill, how refills customarily work, the host's role, and the customary dates accompaniment. Use\n    for \"what's the etiquette for Arabic coffee\", \"how do I decline more coffee politely\", \"who gets served\n    first\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"serving_etiquette_guideArguments","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/equipment_guide":{"post":{"operationId":"equipment_guide","summary":"Traditional Arabic-coffee equipment: the dallah (coffee pot) and its shape, the finjan (small serving","description":"Traditional Arabic-coffee equipment: the dallah (coffee pot) and its shape, the finjan (small serving\n    cup), the mihmas (roasting pan), the mehbaj (mortar and pestle for grinding), and the rakwa (the Levantine\n    brewing pot). Omit item to list all. Use for \"what's a dallah\", \"what is a mehbaj used for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"dallah | finjan | mihmas | mehbaj | rakwa. Omit to list all.","title":"Item"}},"title":"equipment_guideArguments","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_style_comparison":{"post":{"operationId":"regional_style_comparison","summary":"A side-by-side comparison of Khaleeji/Saudi, Levantine, and Yemeni Arabic-coffee preparation: roast level,","description":"A side-by-side comparison of Khaleeji/Saudi, Levantine, and Yemeni Arabic-coffee preparation: roast level,\n    ratio, sweetening convention, signature spice, and brewing vessel for each, plus the headline differences.\n    Use for \"how does Saudi coffee differ from Yemeni coffee\", \"compare Levantine and Khaleeji Arabic coffee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"regional_style_comparisonArguments","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/cultural_significance_info":{"post":{"operationId":"cultural_significance_info","summary":"The hospitality symbolism of Arabic coffee (generosity, welcome, social bonding) and UNESCO's 2015","description":"The hospitality symbolism of Arabic coffee (generosity, welcome, social bonding) and UNESCO's 2015\n    inscription of \"Arabic coffee, a symbol of generosity\" on the Representative List of the Intangible Cultural\n    Heritage of Humanity (10th session, Windhoek, Namibia; originally submitted jointly by Saudi Arabia, the\n    UAE, Oman and Qatar, later extended in 2024 to add Jordan). Use for \"is Arabic coffee a UNESCO heritage\",\n    \"why is gahwa culturally significant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"cultural_significance_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/roasting_notes":{"post":{"operationId":"roasting_notes","summary":"How Arabic coffee's traditional very-light ('blonde') roast differs from the medium-to-dark roasts common","description":"How Arabic coffee's traditional very-light ('blonde') roast differs from the medium-to-dark roasts common\n    for espresso or standard drip coffee, and why — plus how Levantine-style roast/grind moves closer to Turkish\n    coffee. Points to the separate 'roast' connector for general roast-level, grind-size and brew-ratio\n    calculators rather than duplicating them here. Use for \"why is Arabic coffee roasted so light\", \"is qahwa\n    roast the same as espresso roast\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"roasting_notesArguments","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/pairing_guide":{"post":{"operationId":"pairing_guide","summary":"Traditional accompaniments to Arabic coffee — chiefly dates (the quintessential pairing, customarily","description":"Traditional accompaniments to Arabic coffee — chiefly dates (the quintessential pairing, customarily\n    taken with the right hand in an odd number), plus nuts, Arabic sweets, and a note on why milk or cream is\n    not traditionally added. Use for \"what do you eat with Arabic coffee\", \"why are dates served with gahwa\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"pairing_guideArguments","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/hospitality_phrases":{"post":{"operationId":"hospitality_phrases","summary":"A few common, well-known Arabic hospitality phrases related to serving or accepting coffee, transliterated","description":"A few common, well-known Arabic hospitality phrases related to serving or accepting coffee, transliterated\n    with their meaning and when they're used (offering the cup, before drinking, after finishing, declining a\n    refill). Use for \"what do you say when someone offers you Arabic coffee\", \"how do you say please help\n    yourself in Arabic\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"hospitality_phrasesArguments","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/coffee_glossary":{"post":{"operationId":"coffee_glossary","summary":"Definitions of common Arabic-coffee-culture terms (qahwa/gahwa, dallah, finjan, hail/cardamom, bunn,","description":"Definitions of common Arabic-coffee-culture terms (qahwa/gahwa, dallah, finjan, hail/cardamom, bunn,\n    mihmas, mehbaj, rakwa, sada, hilwa, majlis, karam, qishr). Use for \"what does finjan mean\", \"what is hail in\n    Arabic coffee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"coffee_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}}}}