{"openapi":"3.1.0","info":{"title":"Vintner API","version":"0.1.0","description":"A fully local home-winemaking calculator & reference toolkit: verified Brix-to-ABV and chaptalization calculators, a pH-aware sulfite dosing calculator, fermentation temperature guidance, a winemaking-lens grape variety guide, a troubleshooting guide, an equipment glossary, a racking schedule guide, and aging guidance.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://vintner.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/vintner/docs"},"termsOfService":"https://connectorbay.com/vintner/terms"},"servers":[{"url":"https://vintner.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/vintner/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/brix_to_abv_calculator":{"post":{"operationId":"brix_to_abv_calculator","summary":"Potential/actual alcohol by volume from the change in Brix across fermentation, using the verified,","description":"Potential/actual alcohol by volume from the change in Brix across fermentation, using the verified,\n    widely-published (starting Brix - final Brix) x 0.55 home-winemaking approximation. Use for \"what's my\n    potential alcohol from 24 Brix\", \"ABV from 25 Brix down to 0\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"starting_brix":{"description":"Brix reading before fermentation started.","maximum":40,"minimum":0,"title":"Starting Brix","type":"number"},"final_brix":{"description":"Brix reading at (or near) the end of fermentation. Can be slightly negative for a fully dry wine on some hydrometer scales.","maximum":40,"minimum":-3,"title":"Final Brix","type":"number"}},"required":["starting_brix","final_brix"],"title":"brix_to_abv_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/sulfite_dosing_calculator":{"post":{"operationId":"sulfite_dosing_calculator","summary":"Grams of potassium metabisulfite (KMS) needed to raise free SO2 by a target ppm in a given volume, plus","description":"Grams of potassium metabisulfite (KMS) needed to raise free SO2 by a target ppm in a given volume, plus\n    pH-aware guidance on what free-SO2 level is actually protective (since a higher-pH wine needs more free SO2\n    for the same antimicrobial effect). Use for \"how much KMS for 20 liters to add 30 ppm SO2 at pH 3.4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"volume_liters":{"description":"Batch volume in liters.","exclusiveMinimum":0,"title":"Volume Liters","type":"number"},"target_ppm_so2":{"description":"How many ppm of free SO2 you want to add (not the total target level -- the increase).","exclusiveMinimum":0,"maximum":200,"title":"Target Ppm So2","type":"number"},"wine_ph":{"anyOf":[{"maximum":4.2,"minimum":2.8,"type":"number"},{"type":"null"}],"default":null,"description":"The wine's pH, if known. Required SO2 varies a lot with pH; if omitted, a typical table-wine pH (~3.35) is assumed.","title":"Wine Ph"}},"required":["volume_liters","target_ppm_so2"],"title":"sulfite_dosing_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/chaptalization_calculator":{"post":{"operationId":"chaptalization_calculator","summary":"Grams of sugar needed to raise must from a current to a target Brix in a given volume, using the standard","description":"Grams of sugar needed to raise must from a current to a target Brix in a given volume, using the standard\n    ~10 g/L-per-Brix-point home-winemaking rule of thumb. Use for \"how much sugar to raise 20 liters from 19 to\n    23 Brix\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"current_brix":{"description":"Must's current Brix.","maximum":40,"minimum":0,"title":"Current Brix","type":"number"},"target_brix":{"description":"Desired Brix after the sugar addition.","maximum":40,"minimum":0,"title":"Target Brix","type":"number"},"volume_liters":{"description":"Batch volume in liters.","exclusiveMinimum":0,"title":"Volume Liters","type":"number"}},"required":["current_brix","target_brix","volume_liters"],"title":"chaptalization_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/fermentation_temp_guide":{"post":{"operationId":"fermentation_temp_guide","summary":"Typical fermentation temperature ranges (°F and °C) for red, white, or sparkling-base wine, with the","description":"Typical fermentation temperature ranges (°F and °C) for red, white, or sparkling-base wine, with the\n    reasoning behind each range. Use for \"what temperature should I ferment a red at\", \"is 55°F too cold for a\n    white wine fermentation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"wine_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'red', 'white', or 'sparkling_base'. Omit to list all three.","title":"Wine Type"}},"title":"fermentation_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/grape_variety_guide":{"post":{"operationId":"grape_variety_guide","summary":"A grape variety's typical harvest Brix/acid/pH ranges and fermentation considerations, from a","description":"A grape variety's typical harvest Brix/acid/pH ranges and fermentation considerations, from a\n    winemaking (not tasting) lens -- ten common varieties: Cabernet Sauvignon, Merlot, Pinot Noir, Chardonnay,\n    Sauvignon Blanc, Riesling, Zinfandel, Syrah, Malbec, Grenache. Use for \"what Brix should I pick Zinfandel at\",\n    \"fermentation considerations for Syrah\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A grape variety, e.g. 'Cabernet Sauvignon', 'Pinot Noir'. Omit to list all.","title":"Name"}},"title":"grape_variety_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/troubleshooting_guide":{"post":{"operationId":"troubleshooting_guide","summary":"Likely cause and a general fix approach for common home-winemaking problems: stuck fermentation, an","description":"Likely cause and a general fix approach for common home-winemaking problems: stuck fermentation, an\n    off flavor (hydrogen-sulfide/rotten-egg or vinegar/acetic smell), cloudy wine that won't clear, or excessive\n    fermentation foam. Use for \"my wine smells like rotten eggs\", \"fermentation seems stuck\", \"my wine won't clear\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"issue":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"e.g. 'stuck fermentation', 'rotten egg smell', 'vinegar smell', 'cloudy wine', 'excessive foam'. Omit to list all.","title":"Issue"}},"title":"troubleshooting_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_glossary":{"post":{"operationId":"equipment_glossary","summary":"Definitions of ~12 common home-winemaking equipment and process terms (must, racking, lees, airlock,","description":"Definitions of ~12 common home-winemaking equipment and process terms (must, racking, lees, airlock,\n    hydrometer, malolactic fermentation, SO2, must weight, carboy/demijohn, punch-down, wine thief, Campden\n    tablet). Use for \"what does 'racking' mean\", \"what's a Campden tablet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A winemaking term, e.g. 'racking', 'lees', 'hydrometer'. Omit to list all.","title":"Term"}},"title":"equipment_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}},"/v1/tools/racking_schedule_guide":{"post":{"operationId":"racking_schedule_guide","summary":"A general home-winemaking racking timeline (a widely-used '1-3-3'-style rule of thumb) from the first","description":"A general home-winemaking racking timeline (a widely-used '1-3-3'-style rule of thumb) from the first\n    racking off gross lees through bottling. Use for \"when should I rack my wine\", \"how often should I rack\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"racking_schedule_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/aging_guide":{"post":{"operationId":"aging_guide","summary":"Typical bulk-aging and bottle-aging ranges for red, white, rosé, or sparkling wine -- general guidance, not","description":"Typical bulk-aging and bottle-aging ranges for red, white, rosé, or sparkling wine -- general guidance, not\n    a guarantee. Use for \"how long should I bulk age a red\", \"when is a white ready to drink\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"wine_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'red', 'white', 'rose', or 'sparkling'. Omit to list all.","title":"Wine Type"}},"title":"aging_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}}}}