{"openapi":"3.1.0","info":{"title":"Coffee Brewing API","version":"1.0.0","description":"Coffee brewing maths as an API, computed locally and deterministically. The ratio endpoint works out a brew recipe from any two of the coffee dose, the water and the brew ratio — water = coffee × ratio — and reports the third value, the ratio as 1:N, the number of cups and whether the recipe sits around the SCA \"golden ratio\" of about 1:16–1:17. The espresso endpoint does the same for espresso from any two of the dose, the yield and the brew ratio (yield = dose × brew ratio), labelling the shot ristretto, normale or lungo. The extraction endpoint computes the extraction yield, EY% = (beverage mass × TDS%) ÷ dose, from the dose, the brewed beverage mass (or the water, estimating the mass the grounds retain) and the measured total dissolved solids, then classifies the brew as under-extracted, ideal or over-extracted and weak through very strong against the SCA brewing control chart. Masses are in grams, water in grams or millilitres. Everything is computed locally and deterministically, so it is instant and private. Ideal for specialty-coffee, café, brewing-scale and recipe app developers, pour-over and espresso tools, and barista training. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is coffee brewing maths; for cooking-unit conversions use a cooking API and for caffeine intake use a caffeine API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/coffee-api","description":"oanor gateway"}],"tags":[{"name":"Coffee"},{"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/espresso":{"get":{"operationId":"get_v1_espresso","tags":["Coffee"],"summary":"Espresso ratio","description":"","parameters":[{"name":"dose","in":"query","required":false,"description":"Dose in (g)","schema":{"type":"string"},"example":"18"},{"name":"yield","in":"query","required":false,"description":"Yield out (g)","schema":{"type":"string"},"example":"36"},{"name":"brew_ratio","in":"query","required":false,"description":"Brew ratio 1:N","schema":{"type":"string"},"example":"2"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Espresso brew ratio = yield ÷ dose. A modern espresso is about 1:2 (e.g. 18 g in → 36 g out) in 25–30 s.","style":"normale (1:2)","dose_g":18,"inputs":{"dose_g":18,"yield_g":36,"brew_ratio_in":2},"yield_g":36,"brew_ratio":2,"brew_ratio_label":"1:2"},"meta":{"timestamp":"2026-06-04T18:38:07.977Z","request_id":"2880819c-0f13-43ff-8d8e-d4356fa03342"},"status":"ok","message":"Espresso ratio","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/extraction":{"get":{"operationId":"get_v1_extraction","tags":["Coffee"],"summary":"Extraction yield","description":"","parameters":[{"name":"dose","in":"query","required":true,"description":"Coffee dose (g)","schema":{"type":"string"},"example":"60"},{"name":"tds","in":"query","required":true,"description":"Total dissolved solids (%)","schema":{"type":"string"},"example":"1.35"},{"name":"beverage_mass","in":"query","required":false,"description":"Brewed beverage mass (g)","schema":{"type":"string"},"example":"940"},{"name":"water","in":"query","required":false,"description":"Or water (g) to estimate it","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Extraction yield % = (beverage mass × TDS%) ÷ dose. SCA targets 18–22 % extraction at 1.15–1.35 % TDS. Beverage mass ≈ water − 2 g per g of coffee if not measured.","inputs":{"dose_g":60,"tds_pct":1.35,"beverage_mass_g":940},"strength_label":"ideal","extraction_label":"ideal","extraction_yield_pct":21.15},"meta":{"timestamp":"2026-06-04T18:38:08.091Z","request_id":"011f793b-b72d-4335-a973-db31fbf8ddd0"},"status":"ok","message":"Extraction yield","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/ratio":{"get":{"operationId":"get_v1_ratio","tags":["Coffee"],"summary":"Brew ratio","description":"","parameters":[{"name":"coffee","in":"query","required":false,"description":"Coffee dose (g)","schema":{"type":"string"},"example":"30"},{"name":"water","in":"query","required":false,"description":"Water (g/ml)","schema":{"type":"string"},"example":"500"},{"name":"ratio","in":"query","required":false,"description":"Brew ratio 1:N","schema":{"type":"string"},"example":"16.7"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"cups":2.083,"note":"Brew ratio: water = coffee × ratio. The SCA 'golden ratio' is about 1:16–1:17 (≈ 60 g coffee per litre).","ratio":16.667,"inputs":{"water_g":500,"coffee_g":30,"ratio_in":16.7},"water_g":500,"coffee_g":30,"ratio_label":"1:16.7","strength_hint":"around the golden ratio (1:15–1:18)"},"meta":{"timestamp":"2026-06-04T18:38:08.199Z","request_id":"5bb17875-e31f-4ccb-aa75-bf40519f2c6f"},"status":"ok","message":"Brew ratio","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":"Masses in grams (water ≈ ml). Golden ratio ≈ 1:16–1:17; espresso ≈ 1:2; SCA targets 18–22 % extraction at 1.15–1.35 % TDS.","service":"coffee-api","formulae":{"brew_ratio":"water = coffee × ratio","espresso_ratio":"yield = dose × brew_ratio","extraction_yield":"EY% = (beverage_mass × TDS%) / dose"},"endpoints":{"GET /v1/meta":"This document.","GET /v1/ratio":"Brew ratio — any two of coffee, water and ratio give the third, plus cups.","GET /v1/espresso":"Espresso ratio — any two of dose, yield and brew ratio.","GET /v1/extraction":"Extraction yield % and strength from dose, beverage mass (or water) and TDS."},"description":"Coffee brewing calculator: brew ratio (coffee/water/ratio), espresso ratio (dose/yield/brew ratio), and extraction yield from dose, beverage mass and TDS."},"meta":{"timestamp":"2026-06-04T18:38:08.312Z","request_id":"9d5a474e-9622-4d35-9c77-ff805c305cb0"},"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":3000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":400,"monthly_call_quota":40000,"rps_limit":5,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1100,"monthly_call_quota":250000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":3500,"monthly_call_quota":1500000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/coffee-api"}