# Jam & Preserve API
> Jam and preserve maths as an API, computed locally and deterministically — the sugar, setting-point and yield numbers a jam maker, preserver or recipe app works a batch to. The sugar endpoint sets the sugar from the sugar-to-fruit ratio: a traditional full-sugar jam is 1:1, so 1 kg of fruit takes 1 kg of sugar for a 2 kg batch at 50 % sugar, while lower ratios (0.6–0.75) make a softer, fresher, less-sweet preserve that needs added pectin and keeps less well — the sugar both preserves and helps the gel. The setting-point endpoint gives the gel temperature adjusted for altitude: jam sets at about 4.5 °C (8 °F) above the temperature water boils at — 104.5 °C at sea level — but because water boils lower as you climb (roughly 1 °C per 285 m), the target falls to near 99 °C at 1500 m, so cooking to the sea-level figure up a mountain over-boils the batch. The yield endpoint boils the batch down to a target soluble-solids (Brix): jam keeps at about 65 % Brix, the finished weight = the solids (sugar plus the fruit's own ~10 % dry matter) ÷ the target Brix, and the rest evaporates as water — 1 kg sugar and 1 kg fruit boils down to about 1690 g of jam, losing roughly 310 g of water. Everything is computed locally and deterministically, so it is instant and private. Ideal for preserving and recipe tools, homestead and kitchen apps, and food-production calculators. Pure local computation — no key, no third-party service, instant. Gel chemistry, not canning safety. 3 compute endpoints. For processing-time altitude adjustment use a canning 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/jam-api/..."
```

## Pricing
- **Free** (Free) — 6,300 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 55,000 calls/Mo, 6 req/s
- **Pro** ($23/Mo) — 239,000 calls/Mo, 15 req/s
- **Mega** ($73/Mo) — 1,090,000 calls/Mo, 40 req/s

## Endpoints

### Jam

#### `GET /v1/setting-point` — Gel point adjusted for altitude

**Parameters:**
- `altitude_m` (query, optional, string) — Altitude (m, default 0) Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/jam-api/v1/setting-point?altitude_m=0"
```

**Response:**
```json
{
    "data": {
        "note": "Jam gels at about 4.5 °C (8 °F) above the temperature water boils at — 104.5 °C at sea level. Because water boils lower as you climb (roughly 1 °C per 285 m), the setting point falls too: at 1500 m it is near 99 °C, not 104.5 °C. Cooking to the sea-level figure at altitude over-boils the jam; always set the thermometer target to the boil point for your elevation plus ~4.5 °C, or use the wrinkle/cold-plate test.",
        "inputs": {
            "altitude_m": 0
        },
        "jam_setting_point_c": 104.5,
        "water_boiling_point_c": 100
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:51.829Z",
        "request_id": "75ba93e1-51ab-4eea-b3e6-e66c0b5ac23e"
    },
    "status": "ok",
    "message": "Setting point",
    "success": true
}
```

#### `GET /v1/sugar` — Sugar from sugar-to-fruit ratio

**Parameters:**
- `fruit_weight_g` (query, required, string) — Fruit weight (g) Example: `1000`
- `sugar_ratio` (query, optional, string) — Sugar : fruit ratio (default 1.0) Example: `1.0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/jam-api/v1/sugar?fruit_weight_g=1000&sugar_ratio=1.0"
```

**Response:**
```json
{
    "data": {
        "note": "Jam sugar is set by the sugar-to-fruit ratio: a traditional full-sugar jam is 1:1 (equal sugar and fruit), so 1 kg of fruit takes 1 kg of sugar for a 2 kg batch at 50 % sugar. Lower ratios (0.6–0.75) make a softer, fresher, less-sweet preserve but need added pectin and shorter keeping; the sugar is what preserves and helps the set, so dropping it changes both shelf life and gel.",
        "inputs": {
            "sugar_ratio": 1,
            "fruit_weight_g": 1000
        },
        "sugar_g": 1000,
        "sugar_pct": 50,
        "total_batch_g": 2000
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:51.931Z",
        "request_id": "532ebaa7-2c00-4e8e-8f47-5d430e285bc5"
    },
    "status": "ok",
    "message": "Sugar",
    "success": true
}
```

#### `GET /v1/yield` — Finished jam weight at a target Brix

**Parameters:**
- `sugar_g` (query, required, string) — Sugar (g) Example: `1000`
- `fruit_g` (query, required, string) — Fruit (g) Example: `1000`
- `fruit_solids_pct` (query, optional, string) — Fruit dry-matter (%, default 10) Example: `10`
- `target_brix_pct` (query, optional, string) — Target soluble solids (%, default 65) Example: `65`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/jam-api/v1/yield?sugar_g=1000&fruit_g=1000&fruit_solids_pct=10&target_brix_pct=65"
```

**Response:**
```json
{
    "data": {
        "note": "Jam keeps when boiled down to about 65 % soluble solids (Brix). The solids are the sugar plus the fruit's own dry matter (~10 % for most fruit); the finished weight = solids ÷ (target Brix/100), and the rest boils off as water. 1 kg sugar + 1 kg fruit (~1100 g solids) boils down to about 1690 g of jam at 65 %, evaporating roughly 310 g of water. Higher Brix keeps longer but sets firmer and sweeter.",
        "inputs": {
            "fruit_g": 1000,
            "sugar_g": 1000,
            "target_brix_pct": 65,
            "fruit_solids_pct": 10
        },
        "soluble_solids_g": 1100,
        "starting_weight_g": 2000,
        "final_jam_weight_g": 1692.31,
        "water_to_evaporate_g": 307.69
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:52.021Z",
        "request_id": "d28e2fab-ca69-4998-8ddc-3514fc32024a"
    },
    "status": "ok",
    "message": "Yield",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Grams, metres, °C, % Brix. sugar = fruit·ratio; boil = 100 − alt/285; set = boil + 4.5; yield = solids/(brix/100). Gel chemistry, not canning safety — for processing-time altitude adjustment use a canning API.",
        "service": "jam-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/sugar": "Sugar weight and batch total from a sugar-to-fruit ratio.",
            "GET /v1/yield": "Finished jam weight and water to evaporate at a target Brix.",
            "GET /v1/setting-point": "Water boiling point and jam gel point for an altitude."
        },
        "description": "Jam / preserve maths: sugar from a sugar-to-fruit ratio, altitude-adjusted setting point, and finished yield at a target Brix."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:52.100Z",
        "request_id": "f6b1156d-4e2e-44ef-98b6-5236e038fa12"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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