{"openapi":"3.1.0","info":{"title":"Humidor API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/humidor-api","description":"oanor gateway"}],"tags":[{"name":"Humidor"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/capacity":{"get":{"operationId":"get_v1_capacity","tags":["Humidor"],"summary":"Cigar capacity from interior volume","description":"","parameters":[{"name":"interior_length_in","in":"query","required":true,"description":"Interior length in inches","schema":{"type":"string"},"example":"9"},{"name":"interior_width_in","in":"query","required":true,"description":"Interior width in inches","schema":{"type":"string"},"example":"7"},{"name":"interior_height_in","in":"query","required":true,"description":"Interior height in inches","schema":{"type":"string"},"example":"3"},{"name":"ring_gauge","in":"query","required":false,"description":"Cigar ring gauge in 64ths (default 50)","schema":{"type":"string"},"example":"50"},{"name":"cigar_length_in","in":"query","required":false,"description":"Cigar length in inches (default 6)","schema":{"type":"string"},"example":"6"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/media":{"get":{"operationId":"get_v1_media","tags":["Humidor"],"summary":"Humidification packs to maintain RH","description":"","parameters":[{"name":"capacity_cigars","in":"query","required":true,"description":"Cigar capacity","schema":{"type":"string"},"example":"40"},{"name":"cigars_per_pack","in":"query","required":false,"description":"Cigars per 60g pack (default 25)","schema":{"type":"string"},"example":"25"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/seasoning":{"get":{"operationId":"get_v1_seasoning","tags":["Humidor"],"summary":"Seasoning a new humidor","description":"","parameters":[{"name":"capacity_cigars","in":"query","required":true,"description":"Cigar capacity","schema":{"type":"string"},"example":"60"},{"name":"days","in":"query","required":false,"description":"Seasoning days (default 14)","schema":{"type":"string"},"example":"14"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":280,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":545,"monthly_call_quota":7000,"rps_limit":5,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1720,"monthly_call_quota":48000,"rps_limit":13,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":5120,"monthly_call_quota":170000,"rps_limit":32,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/humidor-api"}