# Coffee Roasting API
> Coffee-roasting maths as an API, computed locally and deterministically — the roast-profile numbers a home or specialty roaster tracks batch to batch. The loss endpoint works the weight-loss relationship from any two of the green weight, the roasted weight and the loss percentage: weight loss % = (green − roasted) / green × 100, so 1 kg of green dropping to 840 g is a 16 % loss, a 15 % target leaves 850 g, and to bag 800 g of roasted you charge 952 g of green (roasted ÷ (1 − loss%)). Light roasts shed about 12–14 %, medium 15–17 %, dark 18–20 %. The development endpoint computes the development time and the Development Time Ratio (DTR) from the total roast time and the first-crack time — DTR = (total − first crack) / total × 100, with most roasters aiming for roughly 20–25 %; times accepted as seconds or mm:ss. Everything is computed locally and deterministically, so it is instant and private. Ideal for coffee-roasting, roastery, specialty-coffee and roast-logging app developers, profile and batch tools, and roasting education. Pure local computation — no key, no third-party service, instant. Weights in grams, times in seconds or mm:ss. Live, nothing stored. 2 compute endpoints. This is roast-profile maths; for brewing ratios use a coffee-brewing 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/coffeeroast-api/..."
```

## Pricing
- **Free** (Free) — 6,150 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 59,500 calls/Mo, 6 req/s
- **Pro** ($10/Mo) — 242,000 calls/Mo, 15 req/s
- **Mega** ($31/Mo) — 1,395,000 calls/Mo, 40 req/s

## Endpoints

### Roasting

#### `GET /v1/development` — Development time ratio

**Parameters:**
- `total_time` (query, required, string) — Total roast time (sec or mm:ss) Example: `10:00`
- `first_crack` (query, required, string) — First-crack time (sec or mm:ss) Example: `8:00`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/coffeeroast-api/v1/development?total_time=10%3A00&first_crack=8%3A00"
```

**Response:**
```json
{
    "data": {
        "note": "Development Time Ratio (DTR) = (total − first crack) / total × 100. Most roasters target ~20–25%; lower can taste underdeveloped, higher can flatten acidity.",
        "inputs": {
            "total_time": "10:00",
            "first_crack": "8:00"
        },
        "total_seconds": 600,
        "development_time": "2:00",
        "development_seconds": 120,
        "first_crack_seconds": 480,
        "development_ratio_percent": 20
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:12.308Z",
        "request_id": "6d3dc603-9746-4b78-bcd1-c49fb95753a4"
    },
    "status": "ok",
    "message": "Development ratio",
    "success": true
}
```

#### `GET /v1/loss` — Roast weight loss

**Parameters:**
- `green_weight` (query, optional, string) — Green coffee weight Example: `1000`
- `roasted_weight` (query, optional, string) — Roasted weight Example: `840`
- `loss_percent` (query, optional, string) — Loss % (give any two)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/coffeeroast-api/v1/loss?green_weight=1000&roasted_weight=840"
```

**Response:**
```json
{
    "data": {
        "note": "Weight loss % = (green − roasted) / green × 100. Light roasts lose ~12–14%, medium ~15–17%, dark ~18–20%. Green needed = roasted / (1 − loss%).",
        "inputs": {
            "green_weight": 1000,
            "roasted_weight": 840
        },
        "green_weight": 1000,
        "roasted_weight": 840,
        "weight_loss_grams": 160,
        "weight_loss_percent": 16
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:12.394Z",
        "request_id": "a25525e0-f88d-43d9-aa3d-83734e56af50"
    },
    "status": "ok",
    "message": "Weight loss",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Weights in grams (or any consistent unit); times as seconds or mm:ss. This is roast-profile maths; for brewing ratios use a coffee-brewing API.",
        "service": "coffeeroast-api",
        "endpoints": {
            "GET /v1/loss": "Weight loss % from any two of green, roasted, loss% — including green needed for a target yield.",
            "GET /v1/meta": "This document.",
            "GET /v1/development": "Development time and DTR from the total roast time and first-crack time."
        },
        "description": "Coffee-roasting maths: weight loss (green↔roasted), development-time ratio (DTR), and batch sizing."
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:12.484Z",
        "request_id": "6312630b-bcaf-41ca-a8de-2898941d7d1c"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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