{"openapi":"3.1.0","info":{"title":"Roast API","version":"0.1.0","description":"A fully local coffee brewing calculator and reference toolkit: brew-ratio, cold-brew and espresso dose:yield math, plus extraction troubleshooting, roast-level, grind-size, water-temperature, origin-flavor and glossary references.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://roast.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/roast/docs"},"termsOfService":"https://connectorbay.com/roast/terms"},"servers":[{"url":"https://roast.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/roast/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/brew_ratio_calculator":{"post":{"operationId":"brew_ratio_calculator","summary":"Solves a standard brew ratio for pour-over (~1:16), French press (~1:15), espresso (~1:2), or cold brew","description":"Solves a standard brew ratio for pour-over (~1:16), French press (~1:15), espresso (~1:2), or cold brew\n    concentrate (~1:8). Give either water_grams or coffee_grams and the other is computed; give both to see the\n    ratio they actually imply. Use for \"how much coffee for 500g water pour-over\", \"how much water for 20g coffee\n    in a French press\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"method":{"description":"Brew method.","examples":["pour_over","french_press","espresso","cold_brew_concentrate"],"title":"Method","type":"string"},"water_grams":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Water weight in grams. Omit to solve for it from coffee_grams.","title":"Water Grams"},"coffee_grams":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Coffee weight in grams. Omit to solve for it from water_grams.","title":"Coffee Grams"}},"required":["method"],"title":"brew_ratio_calculatorArguments","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/extraction_troubleshooter":{"post":{"operationId":"extraction_troubleshooter","summary":"Turns a coffee taste problem (bitter, sour, weak, harsh, muddy) into its likely causes (grind, brew time,","description":"Turns a coffee taste problem (bitter, sour, weak, harsh, muddy) into its likely causes (grind, brew time,\n    water temperature, ratio) and a specific fix. Use for \"why does my coffee taste bitter\", \"my pour-over is\n    weak, what's wrong\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"taste_issue":{"description":"bitter | sour | weak | harsh | muddy","title":"Taste Issue","type":"string"}},"required":["taste_issue"],"title":"extraction_troubleshooterArguments","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/roast_level_guide":{"post":{"operationId":"roast_level_guide","summary":"A roast level's flavor profile, typical bean-origin pairing, and typical use (light roasts often for","description":"A roast level's flavor profile, typical bean-origin pairing, and typical use (light roasts often for\n    pour-over/filter, dark roasts often for espresso, as general convention). Use for \"what does a light roast\n    taste like\", \"what's a medium-dark roast good for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"level":{"description":"light | medium | medium-dark | dark","title":"Level","type":"string"}},"required":["level"],"title":"roast_level_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/grind_size_guide":{"post":{"operationId":"grind_size_guide","summary":"The recommended grind size for a brew method — extra coarse for cold brew, coarse for French press, medium","description":"The recommended grind size for a brew method — extra coarse for cold brew, coarse for French press, medium\n    for drip/pour-over, medium-fine for moka pot, fine for espresso, extra fine for Turkish — with a texture\n    comparison and why. Use for \"what grind size for French press\", \"how fine should espresso grounds be\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"method":{"description":"Brew method, e.g. cold_brew, french_press, drip, moka_pot, espresso, turkish.","title":"Method","type":"string"}},"required":["method"],"title":"grind_size_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/water_temp_guide":{"post":{"operationId":"water_temp_guide","summary":"The recommended water temperature range (°F and °C) for a brew method. Most methods fall in the commonly","description":"The recommended water temperature range (°F and °C) for a brew method. Most methods fall in the commonly\n    cited 195-205°F / ~90-96°C band; cold brew uses room-temperature or cold water by design, and Turkish coffee\n    is simmered well below a boil. Use for \"what water temperature for pour-over\", \"how hot should espresso water be\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"method":{"description":"Brew method, e.g. pour_over, french_press, espresso, moka_pot, cold_brew, turkish.","title":"Method","type":"string"}},"required":["method"],"title":"water_temp_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/cold_brew_calculator":{"post":{"operationId":"cold_brew_calculator","summary":"Solves a cold-brew coffee:water ratio (default 1:8 concentrate) for whichever side you don't give it, plus","description":"Solves a cold-brew coffee:water ratio (default 1:8 concentrate) for whichever side you don't give it, plus\n    steep-time guidance (12-24 hours) and a dilution tip. Use for \"how much coffee for 1000g cold brew water\",\n    \"how long should I steep cold brew\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"coffee_grams":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Coffee weight in grams. Omit to solve for it from water_grams.","title":"Coffee Grams"},"water_grams":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Water weight in grams. Omit to solve for it from coffee_grams.","title":"Water Grams"},"ratio":{"default":"1:8","description":"Coffee:water ratio, e.g. '1:8' for a standard concentrate.","title":"Ratio","type":"string"}},"title":"cold_brew_calculatorArguments","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/espresso_dose_yield_guide":{"post":{"operationId":"espresso_dose_yield_guide","summary":"Solves an espresso dose:yield ratio (default 1:2, e.g. 18g in -> 36g out for a standard double) for","description":"Solves an espresso dose:yield ratio (default 1:2, e.g. 18g in -> 36g out for a standard double) for\n    whichever side you don't give it, and names the shot style (ristretto/normale/lungo). Use for \"18g dose, how\n    much should I yield\", \"36g out, how much coffee did that use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dose_grams":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Dry coffee dose in grams (grounds in the basket). Omit to solve for it from yield_grams.","title":"Dose Grams"},"yield_grams":{"anyOf":[{"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Liquid espresso yield in grams (shot weight out). Omit to solve for it from dose_grams.","title":"Yield Grams"},"ratio":{"default":"1:2","description":"Dose:yield ratio, e.g. '1:2' for a standard double.","title":"Ratio","type":"string"}},"title":"espresso_dose_yield_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/origin_flavor_guide":{"post":{"operationId":"origin_flavor_guide","summary":"General, qualitative flavor tendencies commonly associated with a coffee-growing region (Ethiopia,","description":"General, qualitative flavor tendencies commonly associated with a coffee-growing region (Ethiopia,\n    Colombia, Brazil, Sumatra/Indonesia, Kenya, Guatemala, Costa Rica), phrased as a general tendency rather than\n    a guarantee. Use for \"what does Ethiopian coffee taste like\", \"what's Sumatran coffee known for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"origin":{"description":"Growing region.","examples":["Ethiopia","Colombia","Brazil","Sumatra","Kenya","Guatemala","Costa Rica"],"title":"Origin","type":"string"}},"required":["origin"],"title":"origin_flavor_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/coffee_glossary":{"post":{"operationId":"coffee_glossary","summary":"Definitions of common coffee terms (extraction, TDS, bloom, crema, single-origin, blend, washed process,","description":"Definitions of common coffee terms (extraction, TDS, bloom, crema, single-origin, blend, washed process,\n    natural process, honey process, body, acidity, degassing, ...). Use for \"what's a bloom in coffee\", \"what\n    does TDS mean\".","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}}}}