# Caffeine Calculator API > 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. ## 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/caffeine-api/..." ``` ## Pricing - **Free** (Free) — 11,435 calls/Mo, 2 req/s - **Starter** ($13/Mo) — 21,050 calls/Mo, 8 req/s - **Pro** ($33/Mo) — 260,500 calls/Mo, 20 req/s - **Mega** ($71/Mo) — 1,345,000 calls/Mo, 50 req/s ## Endpoints ### Caffeine #### `GET /v1/level` — Caffeine remaining after a time **Parameters:** - `dose` (query, required, string) — Caffeine dose (mg) Example: `200` - `hours` (query, required, string) — Hours elapsed Example: `5` - `half_life` (query, optional, string) — Half-life hours (default 5) Example: `5` - `threshold` (query, optional, string) — Target mg for time-to Example: `50` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/caffeine-api/v1/level?dose=200&hours=5&half_life=5&threshold=50" ``` **Response:** ```json { "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 } ``` #### `GET /v1/sources` — Caffeine by drink **Parameters:** - `drink` (query, optional, string) — A single drink Example: `espresso` - `drinks` (query, optional, string) — Or a list e.g. coffee:2,cola:1 **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/caffeine-api/v1/sources?drink=espresso" ``` **Response:** ```json { "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 } ``` #### `GET /v1/timeline` — Hour-by-hour decay + sleep-safe time **Parameters:** - `dose` (query, required, string) — Caffeine dose (mg) Example: `200` - `half_life` (query, optional, string) — Half-life hours (default 5) Example: `5` - `hours` (query, optional, string) — Range hours (default 24) Example: `24` - `step` (query, optional, string) — Step hours (default 1) Example: `1` - `sleep_threshold` (query, optional, string) — mg (default 50) Example: `50` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/caffeine-api/v1/timeline?dose=200&half_life=5&hours=24&step=1&sleep_threshold=50" ``` **Response:** ```json { "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, …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Spec **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/caffeine-api/v1/meta" ``` **Response:** ```json { "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 } ``` --- Marketplace page: https://www.oanor.com/api/caffeine-api OpenAPI spec: https://www.oanor.com/api/caffeine-api/openapi.json