{"openapi":"3.1.0","info":{"title":"Caffeine Calculator API","version":"1.0.0","description":"Caffeine metabolism maths as an API, computed locally and deterministically with a first-order (exponential) decay model. The level endpoint computes how much caffeine remains in the body after a given time from a dose and a half-life (about 5 hours by default), as milligrams and a percentage, and how long until it falls to a chosen threshold. The timeline endpoint returns an hour-by-hour decay curve and the time until caffeine is \"sleep safe\" — below a threshold (50 mg by default) — handy for working out a coffee cut-off before bed. The sources endpoint gives the typical caffeine content of common drinks (brewed coffee, espresso, tea, energy drinks, cola and more) for a single drink, or totals a list such as two coffees and a cola. Everything is computed locally and deterministically, so it is instant and private. This is informational only: real caffeine half-life varies widely between people (roughly 3–7 hours, and much longer in pregnancy or with certain medications) — it is not medical advice. Ideal for coffee, sleep and wellbeing apps, energy-drink and habit trackers, and quantified-self tools. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is caffeine pharmacokinetics; for a drug reference database use a drug API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/caffeine-api","description":"oanor gateway"}],"tags":[{"name":"Caffeine"},{"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/level":{"get":{"operationId":"get_v1_level","tags":["Caffeine"],"summary":"Caffeine remaining after a time","description":"","parameters":[{"name":"dose","in":"query","required":true,"description":"Caffeine dose (mg)","schema":{"type":"string"},"example":"200"},{"name":"hours","in":"query","required":true,"description":"Hours elapsed","schema":{"type":"string"},"example":"5"},{"name":"half_life","in":"query","required":false,"description":"Half-life hours (default 5)","schema":{"type":"string"},"example":"5"},{"name":"threshold","in":"query","required":false,"description":"Target mg for time-to","schema":{"type":"string"},"example":"50"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"input":{"hours":5,"dose_mg":200,"half_life_hours":5},"disclaimer":"Informational only — caffeine half-life varies widely (≈3–7 h, longer in pregnancy or with some medications). Not medical advice.","remaining_mg":100,"threshold_mg":50,"metabolized_mg":100,"percent_remaining":50,"hours_to_threshold":10},"meta":{"timestamp":"2026-06-04T01:59:17.356Z","request_id":"a5138b3e-1557-452d-af6c-f797a8a4da07"},"status":"ok","message":"Caffeine remaining","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/sources":{"get":{"operationId":"get_v1_sources","tags":["Caffeine"],"summary":"Caffeine by drink","description":"","parameters":[{"name":"drink","in":"query","required":false,"description":"A single drink","schema":{"type":"string"},"example":"espresso"},{"name":"drinks","in":"query","required":false,"description":"Or a list e.g. coffee:2,cola:1","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Typical caffeine per serving (mg).","drink":"espresso","disclaimer":"Informational only — caffeine half-life varies widely (≈3–7 h, longer in pregnancy or with some medications). Not medical advice.","caffeine_mg":63},"meta":{"timestamp":"2026-06-04T01:59:17.444Z","request_id":"13b36312-7134-4801-9b11-d2cc7e96e4c2"},"status":"ok","message":"Caffeine by drink","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/timeline":{"get":{"operationId":"get_v1_timeline","tags":["Caffeine"],"summary":"Hour-by-hour decay + sleep-safe time","description":"","parameters":[{"name":"dose","in":"query","required":true,"description":"Caffeine dose (mg)","schema":{"type":"string"},"example":"200"},{"name":"half_life","in":"query","required":false,"description":"Half-life hours (default 5)","schema":{"type":"string"},"example":"5"},{"name":"hours","in":"query","required":false,"description":"Range hours (default 24)","schema":{"type":"string"},"example":"24"},{"name":"step","in":"query","required":false,"description":"Step hours (default 1)","schema":{"type":"string"},"example":"1"},{"name":"sleep_threshold","in":"query","required":false,"description":"mg (default 50)","schema":{"type":"string"},"example":"50"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"First-order decay: mg(t) = dose × 0.5^(t / half-life). 'Sleep safe' is when caffeine falls below the threshold (default 50 mg).","input":{"step":1,"hours":24,"dose_mg":200,"half_life_hours":5,"sleep_threshold_mg":50},"timeline":[{"mg":200,"hour":0},{"mg":174.11,"hour":1},{"mg":151.57,"hour":2},{"mg":131.95,"hour":3},{"mg":114.87,"hour":4},{"mg":100,"hour":5},{"mg":87.06,"hour":6},{"mg":75.79,"hour":7},{"mg":65.98,"hour":8},{"mg":57.43,"hour":9},{"mg":50,"hour":10},{"mg":43.53,"hour":11},{"mg":37.89,"hour":12},{"mg":32.99,"hour":13},{"mg":28.72,"hour":14},{"mg":25,"hour":15},{"mg":21.76,"hour":16},{"mg":18.95,"hour":17},{"mg":16.49,"hour":18},{"mg":14.36,"hour":19},{"mg":12.5,"hour":20},{"mg":10.88,"hour":21},{"mg":9.47,"hour":22},{"mg":8.25,"hour":23},{"mg":7.18,"hour":24}],"disclaimer":"Informational only — caffeine half-life varies widely (≈3–7 h, longer in pregnancy or with some medications). Not medical advice.","hours_to_sleep_safe":10},"meta":{"timestamp":"2026-06-04T01:59:17.545Z","request_id":"83eed1ea-6383-4119-a56b-5125816479e3"},"status":"ok","message":"Decay timeline","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":{"note":"First-order decay with a default 5-hour half-life. Informational only — caffeine half-life varies widely (≈3–7 h, longer in pregnancy or with some medications). Not medical advice.","service":"caffeine","endpoints":{"/v1/level":"Remaining caffeine (mg and %) after a time, and hours to reach a threshold.","/v1/sources":"Caffeine per serving for common drinks, or the total for a drinks list.","/v1/timeline":"Hour-by-hour caffeine decay and the time until it is 'sleep safe'."},"description":"Caffeine metabolism maths: remaining caffeine over time (half-life decay), a decay timeline with a sleep threshold, and caffeine content of common drinks.","default_half_life_hours":5},"meta":{"timestamp":"2026-06-04T01:59:17.644Z","request_id":"41857f96-a27b-4c00-aef8-28a192f654a2"},"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":11435,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1295,"monthly_call_quota":21050,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3285,"monthly_call_quota":260500,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":7085,"monthly_call_quota":1345000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/caffeine-api"}