# Winemaking API
> 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.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/winemaking-api/..."
```

## Pricing
- **Free** (Free) — 5,250 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 53,500 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 227,000 calls/Mo, 15 req/s
- **Mega** ($37/Mo) — 1,305,000 calls/Mo, 40 req/s

## Endpoints

### Winemaking

#### `GET /v1/acid` — Acid (TA) adjustment

**Parameters:**
- `volume` (query, required, string) — Volume (litres) Example: `20`
- `current_ta` (query, required, string) — Current TA (g/L as tartaric) Example: `5`
- `target_ta` (query, required, string) — Target TA (g/L) Example: `6.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/winemaking-api/v1/acid?volume=20&current_ta=5&target_ta=6.5"
```

**Response:**
```json
{
    "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
}
```

#### `GET /v1/so2` — SO2 free vs molecular + dose

**Parameters:**
- `ph` (query, required, string) — Wine pH Example: `3.4`
- `molecular_target` (query, optional, string) — Target molecular SO2 mg/L (default 0.8)
- `current_free_so2` (query, optional, string) — Current free SO2 mg/L Example: `10`
- `target_free_so2` (query, optional, string) — Target free SO2 mg/L
- `volume` (query, optional, string) — Volume for KMS dose (litres) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/winemaking-api/v1/so2?ph=3.4&current_free_so2=10&volume=20"
```

**Response:**
```json
{
    "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
}
```

#### `GET /v1/sugar` — Chaptalization & potential ABV

**Parameters:**
- `volume` (query, required, string) — Must volume (litres) Example: `20`
- `brix` (query, optional, string) — Current Brix (or sg) Example: `21`
- `sg` (query, optional, string) — Current specific gravity
- `target_abv` (query, optional, string) — Target potential ABV % Example: `13`
- `target_brix` (query, optional, string) — Or target Brix
- `target_sg` (query, optional, string) — Or target SG

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/winemaking-api/v1/sugar?volume=20&brix=21&target_abv=13"
```

**Response:**
```json
{
    "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
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/winemaking-api/v1/meta"
```

**Response:**
```json
{
    "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
}
```


---
Marketplace page: https://www.oanor.com/api/winemaking-api
OpenAPI spec: https://www.oanor.com/api/winemaking-api/openapi.json