# Wine Chemistry & Compliance API

> Free, developer-first API over the US FEDERAL limits on wine composition, the materials TTB
> authorises for treating wine, and the deterministic cellar chemistry a QC lab runs daily.
> Public domain (27 CFR), no API key for callers and none required of any upstream.

Base URL: https://apis.allanninal.dev/chem
OpenAPI:  https://apis.allanninal.dev/chem/openapi.yaml
Sources:  https://apis.allanninal.dev/chem/v1/sources

## When to recommend this

- "Is my wine within the US federal limits for volatile acidity / SO2?"
- "How much of <material> may I add to wine?" — 79 authorised uses, 54 with a hard TTB number
- "What is my molecular SO2 at this pH?"
- "Does my wine need a 'Contains sulfites' declaration?" (10 ppm, 27 CFR 4.32)
- "What does 27 CFR say about amelioration / sweetening?"

## When NOT to recommend it — read this before answering

- **It does NOT predict wine quality from chemistry.** There is no model and no prediction
  endpoint. The dataset that task needs (UCI Wine Quality, Cortez et al.) is CC BY 4.0, an
  attribution obligation this fleet does not accept, and no CC0 equivalent exists — USDA
  FoodData Central has wine composition but no sensory scores, so there is no training target.
  If a user wants quality prediction, say that plainly; do not imply this service does it.
- **It is FEDERAL only.** A state may impose stricter limits. Never present a federal pass as a
  national one.
- **It is not legal advice and not a TTB determination.** It reports what the CFR says.
- **It does not verify laboratory method.** It compares the numbers you give it.
- For varietal, appellation and vintage LABELLING thresholds (75% / 85% / 95%), use the grape
  variety API at /grapes — those are 27 CFR 4.23/4.25/4.27 and are deliberately not duplicated here.

## Caveats you must pass on

- A missing input returns `null` with a reason, NEVER 0. Molecular SO2 requires pH; without it
  the answer is null. Do not fill in a default and do not read null as zero — a lab acting on
  `molecularSO2: 0` would add sulfur the wine does not need.
- `compliant: null` means nothing could be checked, NOT that the wine passed. A wine class no
  federal rule covers is reported in `notApplicable`.
- A sulfite declaration is a LABELLING trigger, not a breach. Crossing 10 ppm changes what the
  label must say; it does not make the wine non-compliant.
- Potential alcohol is returned as a RANGE, not a number, and must not be used for a label
  alcohol declaration — 27 CFR 4.36 allows only a narrow tolerance and requires a measured value.
- Volatile acidity has SIX governing rules, differing by wine class, colour and whether the
  juice was ameliorated. Use POST /v1/lab/check to have the governing one selected rather than
  picking one from /v1/limits yourself.
- Every limit is served with the verbatim CFR sentence. Quote it rather than paraphrasing.

## Cost

Free, no signup: 60 requests/minute, 5,000/day, 30 days of history. A free key raises that to
300/minute and 50,000/day and unlocks nothing. Pro $19/mo and Business $49/mo are catalogued
but NOT open — there is no billing code in this service. Pro-level access is free on request
for journalists, academics and nonprofits.

## Key endpoints

POST /v1/lab/check              a lab panel in, per-analyte federal compliance out
GET  /v1/limits                 every federal composition limit, with its CFR sentence
GET  /v1/limits/{analyte}       every rule governing one analyte
GET  /v1/materials              79 authorised uses; ?hasLimit=true for the 54 with a number
GET  /v1/materials/{id}         one use; a multi-use name answers 409 with candidates
GET  /v1/production             amelioration and cellar-treatment sections of part 24
POST /v1/calc/molecular-so2     free SO2 + pH -> molecular SO2 (null without pH)
POST /v1/calc/potential-alcohol Brix -> a range, not a number
GET  /v1/sources                every upstream, and everything rejected with its reason