# Candle Making API
> Candle-making maths as an API, computed locally and deterministically — the wax, fragrance and burn-time numbers a chandler scales a batch with. The recipe endpoint sizes a pour from the container water volume: wax (g) per candle = volume(ml) × fill% × wax density (soy ≈ 0.9, beeswax ≈ 0.96, paraffin ≈ 0.9 g/ml), so a 250 ml jar at 80 % fill takes 180 g of soy wax; it adds the fragrance oil at the load percentage (commonly 6–10 %, never above the wax's maximum) and multiplies everything by the number of candles for the total wax, total fragrance and batch weight. The burn endpoint estimates how long a candle lasts: burn time ≈ wax grams ÷ burn rate, where a typical container candle consumes about 7–9 g of wax an hour. Everything is computed locally and deterministically, so it is instant and private. Ideal for candle-making, home-fragrance, handmade-craft and maker app developers, batch-calculator and recipe tools, and chandlery education. Pure local computation — no key, no third-party service, instant. Metric: millilitres, grams, percent. Live, nothing stored. 2 compute endpoints. A planning aid — pour tests and your wax datasheet always win.

## 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/candle-api/..."
```

## Pricing
- **Free** (Free) — 6,350 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 61,000 calls/Mo, 6 req/s
- **Pro** ($9/Mo) — 246,000 calls/Mo, 15 req/s
- **Mega** ($30/Mo) — 1,410,000 calls/Mo, 40 req/s

## Endpoints

### Candle

#### `GET /v1/burn` — Burn-time estimate

**Parameters:**
- `wax_grams` (query, required, string) — Wax weight (g) Example: `180`
- `burn_rate` (query, optional, string) — Burn rate g/hour (default 8) Example: `8`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/candle-api/v1/burn?wax_grams=180&burn_rate=8"
```

**Response:**
```json
{
    "data": {
        "note": "Burn time ≈ wax grams ÷ burn rate. A typical container candle burns ~7–9 g of wax per hour; bigger wicks burn faster. Measure your own rate for accuracy.",
        "inputs": {
            "burn_rate": 8,
            "wax_grams": 180
        },
        "burn_time_hours": 22.5,
        "burn_time_formatted": "22h 30m"
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:11.965Z",
        "request_id": "30089111-a333-484d-942a-bb018009bcf9"
    },
    "status": "ok",
    "message": "Burn time",
    "success": true
}
```

#### `GET /v1/recipe` — Wax & fragrance for containers

**Parameters:**
- `container_volume` (query, required, string) — Container water volume (ml) Example: `250`
- `count` (query, optional, string) — Number of candles (default 1) Example: `4`
- `fill_percent` (query, optional, string) — Fill % (default 80) Example: `80`
- `wax_type` (query, optional, string) — soy, paraffin, beeswax, coconut, palm Example: `soy`
- `wax_density` (query, optional, string) — Override density (g/ml)
- `fragrance_percent` (query, optional, string) — Fragrance load % (default 8) Example: `8`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/candle-api/v1/recipe?container_volume=250&count=4&fill_percent=80&wax_type=soy&fragrance_percent=8"
```

**Response:**
```json
{
    "data": {
        "note": "Wax (g) per candle = container volume(ml) × fill% × wax density (soy ≈ 0.9 g/ml). Fragrance = wax × load% (commonly 6–10%, never above the wax's max). Multiply by the number of candles.",
        "inputs": {
            "count": 4,
            "wax_type": "soy",
            "fill_percent": 80,
            "container_volume": 250,
            "fragrance_percent": 8
        },
        "wax_density": 0.9,
        "total_wax_grams": 720,
        "batch_weight_grams": 777.6,
        "wax_per_candle_grams": 180,
        "total_fragrance_grams": 57.6,
        "fragrance_per_candle_grams": 14.4
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:12.069Z",
        "request_id": "b2f9a3c9-1180-45c3-b29b-d7e9d6152d79"
    },
    "status": "ok",
    "message": "Wax & fragrance",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Metric: millilitres (container water volume), grams, percent. Wax density defaults by type (soy 0.9, beeswax 0.96…). A planning aid — pour tests and your wax's datasheet always win.",
        "service": "candle-api",
        "endpoints": {
            "GET /v1/burn": "Estimated burn time from wax weight and a burn rate.",
            "GET /v1/meta": "This document.",
            "GET /v1/recipe": "Wax and fragrance grams for N containers from volume, fill %, wax type and fragrance load."
        },
        "description": "Candle-making maths: wax and fragrance for a set of containers, and burn-time estimation."
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:12.174Z",
        "request_id": "552380a5-57ca-4659-87ce-aa12125b7a2b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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