# Humidor API
> Cigar-humidor maths as an API, computed locally and deterministically — the numbers behind storing cigars right, so you buy the correct humidor and keep it at the perfect humidity. The capacity endpoint works out how many cigars an interior holds: interior volume × a packing efficiency ÷ one cigar's volume, where a cigar is a cylinder of its ring gauge (in 64ths of an inch) and length — a 9 × 7 × 3 inch interior holds about 40 Toros (ring 50, 6 inch) at a realistic 0.62 packing, leaving room for air and a humidification device. The media endpoint sizes the humidification: about one 60 g two-way pack per 25 cigars, replaced roughly every two months, so a 40-cigar humidor wants two packs. The seasoning endpoint covers a brand-new humidor — its Spanish cedar must absorb moisture for about two weeks at 84 % RH (one seasoning pack per 25-cigar capacity, or the distilled-water wipe-down) before any cigars go in, or the dry wood will rob them. Everything is computed locally and deterministically, so it is instant and private. Ideal for cigar-shop and tobacconist apps, humidor-maker product pages, cigar-aficionado and collection-tracker sites, and buying guides. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For room humidity or dew point use a psychrometric 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/humidor-api/..."
```

## Pricing
- **Free** (Free) — 280 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 7,000 calls/Mo, 5 req/s
- **Pro** ($17/Mo) — 48,000 calls/Mo, 13 req/s
- **Mega** ($51/Mo) — 170,000 calls/Mo, 32 req/s

## Endpoints

### Humidor

#### `GET /v1/capacity` — Cigar capacity from interior volume

**Parameters:**
- `interior_length_in` (query, required, string) — Interior length in inches Example: `9`
- `interior_width_in` (query, required, string) — Interior width in inches Example: `7`
- `interior_height_in` (query, required, string) — Interior height in inches Example: `3`
- `ring_gauge` (query, optional, string) — Cigar ring gauge in 64ths (default 50) Example: `50`
- `cigar_length_in` (query, optional, string) — Cigar length in inches (default 6) Example: `6`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/humidor-api/v1/capacity?interior_length_in=9&interior_width_in=7&interior_height_in=3&ring_gauge=50&cigar_length_in=6"
```

**Response:**
```json
{
    "data": {
        "note": "Capacity ≈ interior volume × packing efficiency ÷ one cigar's volume, where a cigar is a cylinder of its ring gauge (in 64ths of an inch) and length. Round cigars leave gaps, so ~0.62 packing is realistic — and leave room for a humidification device and air flow. Boxes and cellophane take more space again.",
        "inputs": {
            "ring_gauge": 50,
            "cigar_length_in": 6,
            "interior_width_in": 7,
            "interior_height_in": 3,
            "interior_length_in": 9
        },
        "capacity_cigars": 40,
        "interior_cubic_in": 189,
        "per_cigar_cubic_in": 2.876
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.900Z",
        "request_id": "539cda05-e12c-45f7-ac77-a6c9e9da2479"
    },
    "status": "ok",
    "message": "Capacity",
    "success": true
}
```

#### `GET /v1/media` — Humidification packs to maintain RH

**Parameters:**
- `capacity_cigars` (query, required, string) — Cigar capacity Example: `40`
- `cigars_per_pack` (query, optional, string) — Cigars per 60g pack (default 25) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/humidor-api/v1/media?capacity_cigars=40&cigars_per_pack=25"
```

**Response:**
```json
{
    "data": {
        "note": "One 60 g humidification pack holds about 25 cigars' worth of air at a steady RH; size up for bigger humidors and when you open the lid often. Two-way packs (e.g. 69 % RH) both add and absorb moisture — replace them when they go stiff, roughly every two months. A fuller humidor holds RH more steadily than an empty one.",
        "inputs": {
            "capacity_cigars": 40,
            "cigars_per_pack": 25
        },
        "packs_needed": 2,
        "replace_every_weeks": 8
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.993Z",
        "request_id": "f802be88-3e44-45dd-b90c-bf6dd9a8526e"
    },
    "status": "ok",
    "message": "Humidification media",
    "success": true
}
```

#### `GET /v1/seasoning` — Seasoning a new humidor

**Parameters:**
- `capacity_cigars` (query, required, string) — Cigar capacity Example: `60`
- `days` (query, optional, string) — Seasoning days (default 14) Example: `14`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/humidor-api/v1/seasoning?capacity_cigars=60&days=14"
```

**Response:**
```json
{
    "data": {
        "note": "A new humidor's Spanish cedar must absorb moisture before it can hold RH, or it will rob your cigars. Use 84 %-RH seasoning packs (about one per 25-cigar capacity) for ~2 weeks with the lid closed, or the wipe-down method with distilled water — never tap water. Don't add cigars until a hygrometer holds steady around 70 %.",
        "inputs": {
            "days": 14,
            "capacity_cigars": 60
        },
        "rh_target_pct": 84,
        "seasoning_days": 14,
        "seasoning_packs": 3
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:45.087Z",
        "request_id": "290b6340-9cf1-4aec-97a9-19ee06adb193"
    },
    "status": "ok",
    "message": "Seasoning",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Inches; ring gauge in 64ths (50 = Toro). Capacity = interior × packing ÷ cigar volume; ~1 pack per 25 cigars; season ~2 weeks at 84 % RH. Estimates — measure RH with a calibrated hygrometer. For room humidity/dew point use a psychrometric API.",
        "service": "humidor-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/media": "Humidification packs to maintain a capacity at RH, and replacement interval.",
            "GET /v1/capacity": "Cigars an interior holds from its dimensions and a cigar size.",
            "GET /v1/seasoning": "Seasoning packs and days for a new humidor."
        },
        "description": "Cigar-humidor maths: cigar capacity from interior volume, humidification packs to hold RH, and seasoning a new humidor."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:45.171Z",
        "request_id": "512a8199-0bea-4754-ba9e-aad20e738072"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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