{"openapi":"3.1.0","info":{"title":"Winemaking API","version":"1.0.0","description":"Winemaking and oenology maths as an API, computed locally and deterministically — the must-correction, sulfite and acid numbers a home or small-batch winemaker dials in. The sugar endpoint reads the must as Brix or specific gravity, gives the potential alcohol (potential ABV = (SG − 1) × 131.25), and works out the chaptalization sugar to reach a target ABV — sugar (g) = volume(L) × Δ potential-ABV × 16.83, since roughly 17 g/L of sugar ferments to about 1 % alcohol. The so2 endpoint handles sulfite protection: it converts between free and molecular SO2 at the wine's pH (molecular SO2 = free / (1 + 10^(pH − 1.81)), aiming for the protective 0.8 mg/L molecular), shows how the free SO2 needed plummets as pH drops, and doses the potassium metabisulfite (57.6 % SO2) and campden tablets (~0.44 g each) to hit a target free SO2 in a given volume. The acid endpoint moves titratable acidity to a target with tartaric acid to raise it (grams = ΔTA × volume) or potassium bicarbonate to lower it. Everything is computed locally and deterministically, so it is instant and private. Ideal for winemaking, cidery, mead, home-fermentation and craft-beverage app developers, must-calculator and cellar tools, and oenology education. Pure local computation — no key, no third-party service, instant. Metric: litres, grams, g/L, mg/L. Live, nothing stored. 3 compute endpoints. A planning aid — your lab numbers and palate always win. For beer ABV from gravity use a homebrewing API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/winemaking-api","description":"oanor gateway"}],"tags":[{"name":"Winemaking"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/acid":{"get":{"operationId":"get_v1_acid","tags":["Winemaking"],"summary":"Acid (TA) adjustment","description":"","parameters":[{"name":"volume","in":"query","required":true,"description":"Volume (litres)","schema":{"type":"string"},"example":"20"},{"name":"current_ta","in":"query","required":true,"description":"Current TA (g/L as tartaric)","schema":{"type":"string"},"example":"5"},{"name":"target_ta","in":"query","required":true,"description":"Target TA (g/L)","schema":{"type":"string"},"example":"6.5"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Raise TA by adding tartaric acid: grams = ΔTA(g/L) × volume(L). Tartaric is the reference acid for titratable acidity.","action":"raise","inputs":{"volume":20,"target_ta":6.5,"current_ta":5},"delta_ta_gL":1.5,"tartaric_acid_grams":30},"meta":{"timestamp":"2026-06-06T07:14:12.919Z","request_id":"779a42a2-de44-4401-ab09-29102ec5e807"},"status":"ok","message":"Acid adjustment","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/so2":{"get":{"operationId":"get_v1_so2","tags":["Winemaking"],"summary":"SO2 free vs molecular + dose","description":"","parameters":[{"name":"ph","in":"query","required":true,"description":"Wine pH","schema":{"type":"string"},"example":"3.4"},{"name":"molecular_target","in":"query","required":false,"description":"Target molecular SO2 mg/L (default 0.8)","schema":{"type":"string"}},{"name":"current_free_so2","in":"query","required":false,"description":"Current free SO2 mg/L","schema":{"type":"string"},"example":"10"},{"name":"target_free_so2","in":"query","required":false,"description":"Target free SO2 mg/L","schema":{"type":"string"}},{"name":"volume","in":"query","required":false,"description":"Volume for KMS dose (litres)","schema":{"type":"string"},"example":"20"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Molecular SO2 = free SO2 / (1 + 10^(pH−1.81)); aim for ~0.8 mg/L molecular. KMS (metabisulfite) is 57.6% SO2; a campden tablet ≈ 0.44 g KMS. Lower pH needs far less free SO2.","inputs":{"ph":3.4},"kms_grams":0.7613,"so2_to_add_mgL":21.924,"campden_tablets":1.73,"target_free_so2_mgL":31.924,"current_free_so2_mgL":10,"molecular_target_mgL":0.8,"free_so2_for_target_mgL":31.924,"current_molecular_so2_mgL":0.2506},"meta":{"timestamp":"2026-06-06T07:14:13.017Z","request_id":"4a699853-dccc-473a-b196-2b097595fd0b"},"status":"ok","message":"SO2 / sulfite","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/sugar":{"get":{"operationId":"get_v1_sugar","tags":["Winemaking"],"summary":"Chaptalization & potential ABV","description":"","parameters":[{"name":"volume","in":"query","required":true,"description":"Must volume (litres)","schema":{"type":"string"},"example":"20"},{"name":"brix","in":"query","required":false,"description":"Current Brix (or sg)","schema":{"type":"string"},"example":"21"},{"name":"sg","in":"query","required":false,"description":"Current specific gravity","schema":{"type":"string"}},{"name":"target_abv","in":"query","required":false,"description":"Target potential ABV %","schema":{"type":"string"},"example":"13"},{"name":"target_brix","in":"query","required":false,"description":"Or target Brix","schema":{"type":"string"}},{"name":"target_sg","in":"query","required":false,"description":"Or target SG","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Chaptalization: sugar (g) = volume(L) × ΔpotentialABV × 16.83. Potential ABV = (SG−1)×131.25; ~17 g/L of sugar ferments to ~1% ABV.","inputs":{"sg":1.0875,"brix":21,"volume":20},"specific_gravity":1.0875,"sugar_to_add_grams":512.24,"target_potential_abv":13,"current_potential_abv":11.478},"meta":{"timestamp":"2026-06-06T07:14:13.089Z","request_id":"87409d35-f72b-4ecb-a65c-3944a60fcfca"},"status":"ok","message":"Chaptalization","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"notes":"Metric: litres, grams, g/L, mg/L. Potential ABV = (SG−1)×131.25. Molecular SO2 = free/(1+10^(pH−1.81)). Tasting and lab numbers always override — this is a planning aid.","service":"winemaking-api","endpoints":{"GET /v1/so2":"Free vs molecular SO2 at a pH, and the KMS/campden to reach a target free SO2.","GET /v1/acid":"Tartaric acid (or bicarbonate) to move titratable acidity to a target.","GET /v1/meta":"This document.","GET /v1/sugar":"Brix/SG → potential alcohol and the sugar to chaptalize to a target ABV."},"description":"Winemaking maths: chaptalization (sugar to target alcohol), SO2/sulfite additions (free vs molecular, KMS, campden) and acid (TA) adjustment."},"meta":{"timestamp":"2026-06-06T07:14:13.180Z","request_id":"b0d24e85-277c-4727-a92f-b747ce9becc5"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5250,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":435,"monthly_call_quota":53500,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1175,"monthly_call_quota":227000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":3700,"monthly_call_quota":1305000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/winemaking-api"}