# Cooking API
> Recipe and kitchen conversions as an API. Convert between volume units (teaspoon, tablespoon, cup, fl-oz, ml, litre, pint, quart, gallon) and between mass units (gram, kilogram, ounce, pound) — and, crucially, between volume and mass for a specific ingredient using its density, so 1 cup of all-purpose flour ≈ 125 g, 1 cup of granulated sugar ≈ 200 g and 1 cup of water ≈ 237 g. 30 common ingredients are built in (flours, sugars, butter, oils, honey, rice, oats, cocoa, cornstarch and more), each with its grams-per-cup. Perfect for recipe apps, scaling and "metric vs cups" conversion, shopping lists and meal-prep tools. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. Distinct from general physical unit conversion, which has no ingredient densities.

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

## Pricing
- **Free** (Free) — 1,025 calls/Mo, 2 req/s
- **Starter** ($1/Mo) — 8,650 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 137,500 calls/Mo, 20 req/s
- **Mega** ($59/Mo) — 725,000 calls/Mo, 50 req/s

## Endpoints

### Cooking

#### `GET /v1/convert` — Convert a cooking measure

**Parameters:**
- `amount` (query, required, string) — Amount Example: `1`
- `from` (query, required, string) — Unit (cup, g, tbsp, ml, oz…) Example: `cup`
- `to` (query, required, string) — Unit Example: `g`
- `ingredient` (query, optional, string) — For volume<->mass (e.g. all-purpose-flour) Example: `all-purpose-flour`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cooking-api/v1/convert?amount=1&from=cup&to=g&ingredient=all-purpose-flour"
```

**Response:**
```json
{
    "data": {
        "to": "g",
        "from": "cup",
        "amount": 1,
        "result": 124.918589,
        "ingredient": "all-purpose-flour",
        "density_g_per_ml": 0.528
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:44.282Z",
        "request_id": "dd9504e2-b331-44cc-9c0e-7358da774c63"
    },
    "status": "ok",
    "message": "Convert a cooking measure",
    "success": true
}
```

### Reference

#### `GET /v1/ingredients` — Supported ingredients

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

**Response:**
```json
{
    "data": {
        "count": 30,
        "mass_units": [
            "mg",
            "g",
            "kg",
            "oz",
            "lb",
            "lbs"
        ],
        "ingredients": [
            {
                "name": "water",
                "grams_per_cup": 236.588236,
                "density_g_per_ml": 1
            },
            {
                "name": "milk",
                "grams_per_cup": 243.922471,
                "density_g_per_ml": 1.031
            },
            {
                "name": "heavy-cream",
                "grams_per_cup": 239.427295,
                "density_g_per_ml": 1.012
            },
            {
                "name": "vegetable-oil",
                "grams_per_cup": 217.188001,
                "density_g_per_ml": 0.918
            },
            {
                "name": "olive-oil",
                "grams_per_cup": 217.188001,
                "density_g_per_ml": 0.918
            },
            {
                "name": "honey",
                "grams_per_cup": 339.977295,
                "density_g_per_ml": 1.437
            },
            {
                "name": "maple-syrup",
                "grams_per_cup": 324.125883,
                "density_g_per_ml": 1.37
            },
            {
                "name": "all-purpose-flour",
                "grams_per_cup": 124.918589,
                "density_g_per_ml": 0.528
            },
            {
                "name": "bread-flour",
                "gram
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Cooking API",
        "notes": "Volume units are US customary (1 cup = 236.59 ml). Volume<->mass requires an ingredient (defaults to water). Densities are typical values; brands vary. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/convert",
                "params": {
                    "to": "unit (required)",
                    "from": "unit (required)",
                    "amount": "required",
                    "ingredient": "needed for volume<->mass, e.g. all-purpose-flour"
                },
                "returns": "the converted amount"
            },
            {
                "path": "/v1/ingredients",
                "params": [],
                "returns": "supported ingredients (with grams per cup) and units"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Recipe and kitchen conversions: between volume units (teaspoon, tablespoon, cup, ml, fl-oz, pint…), between mass units (g, kg, oz, lb), and — crucially — between volume and mass for a specific ingredient using its density (1 cup of all-purpose flour ≈ 125 g, 1 cup of sugar ≈ 200 g). Pure local, no key."
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:44.451Z",
        "request_id": "2d6259b2-ae04-45d6-8284-772eb12fba4c"
    },
    "status": "ok",
 
…(truncated, see openapi.json for full schema)
```


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