# Sleep Cycle API > Sleep-cycle planning as an API, built around the fact that a full sleep cycle averages about 90 minutes and that waking at the end of a cycle — rather than mid-cycle — leaves you feeling more refreshed. The bedtime endpoint takes a wake-up time and suggests the times to fall asleep so that you wake at the end of a whole number of cycles (6, 5, 4 or 3 cycles), allowing for the time it takes to drift off. The wake-time endpoint does the reverse: from a bedtime (or "now") it suggests the best times to set an alarm. The duration endpoint takes a bedtime and a wake time and reports time in bed, actual sleep, the number of full cycles, how many minutes you are into the current cycle and how close you are to a clean cycle boundary, with a healthy-duration assessment. The nap endpoint plans power, short, slow-wave and full-cycle naps from a start time and explains the trade-offs. All clock maths is modulo 24 hours and accepts both 24-hour ("23:15") and 12-hour ("10:30 PM") times. Everything is computed locally and deterministically, so it is instant and private. Ideal for sleep, alarm-clock and wellbeing apps, smart-home routines, shift-work planning and productivity tools. Pure local computation — no key, no third-party service, instant. Live, nothing stored. INFORMATIONAL ONLY — sleep needs vary by individual; not medical advice. 4 endpoints. This is sleep-cycle timing maths; for time-zone conversion use a time API and for body metrics such as BMI use a health-calculator 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/sleep-api/..." ``` ## Pricing - **Free** (Free) — 8,935 calls/Mo, 2 req/s - **Starter** ($10/Mo) — 18,550 calls/Mo, 8 req/s - **Pro** ($30/Mo) — 235,500 calls/Mo, 20 req/s - **Mega** ($68/Mo) — 1,220,000 calls/Mo, 50 req/s ## Endpoints ### Sleep #### `GET /v1/bedtime` — Recommended bedtimes from a wake time **Parameters:** - `wake` (query, required, string) — Wake-up time Example: `07:00` - `latency` (query, optional, string) — Minutes to fall asleep (default 15) Example: `15` - `cycle_length` (query, optional, string) — Cycle minutes (default 90) Example: `90` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/sleep-api/v1/bedtime?wake=07%3A00&latency=15&cycle_length=90" ``` **Response:** ```json { "data": { "advice": "To wake refreshed, fall asleep at one of these times so you wake at the end of a sleep cycle.", "wake_at": { "time_12h": "7:00 AM", "time_24h": "07:00", "minute_of_day": 420 }, "bedtimes": [ { "cycles": 6, "quality": "ideal", "go_to_bed": { "time_12h": "9:45 PM", "time_24h": "21:45", "minute_of_day": 1305 }, "sleep_hours": 9, "sleep_duration": "9h" }, { "cycles": 5, "quality": "good", "go_to_bed": { "time_12h": "11:15 PM", "time_24h": "23:15", "minute_of_day": 1395 }, "sleep_hours": 7.5, "sleep_duration": "7h 30m" }, { "cycles": 4, "quality": "minimum recommended", "go_to_bed": { "time_12h": "12:45 AM", "time_24h": "00:45", "minute_of_day": 45 }, "sleep_hours": 6, "sleep_duration": "6h" }, { "cycles": 3, "quality": "short", "go_to_bed": { "time_12h": "2:15 AM", …(truncated, see openapi.json for full schema) ``` #### `GET /v1/duration` — Sleep duration & cycle analysis **Parameters:** - `bedtime` (query, required, string) — Bedtime Example: `23:00` - `wake` (query, required, string) — Wake time Example: `07:00` - `latency` (query, optional, string) — Minutes to fall asleep (default 0) Example: `0` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/sleep-api/v1/duration?bedtime=23%3A00&wake=07%3A00&latency=0" ``` **Response:** ```json { "data": { "bedtime": { "time_12h": "11:00 PM", "time_24h": "23:00", "minute_of_day": 1380 }, "wake_at": { "time_12h": "7:00 AM", "time_24h": "07:00", "minute_of_day": 420 }, "assessment": "healthy duration", "disclaimer": "Informational only — sleep needs vary by individual; not medical advice.", "full_cycles": 5, "sleep_hours": 8, "time_in_bed": "8h", "sleep_minutes": 480, "sleep_duration": "8h", "on_cycle_boundary": false, "fall_asleep_minutes": 0, "time_in_bed_minutes": 480, "cycle_length_minutes": 90, "minutes_into_current_cycle": 30, "minutes_to_next_cycle_boundary": 60 }, "meta": { "timestamp": "2026-06-03T17:42:01.779Z", "request_id": "0f8c2983-3fde-4359-9778-57b725c95201" }, "status": "ok", "message": "Sleep duration analysis", "success": true } ``` #### `GET /v1/nap` — Nap planner **Parameters:** - `start` (query, optional, string) — Nap start or "now" Example: `14:00` - `latency` (query, optional, string) — Minutes to fall asleep (default 15) Example: `15` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/sleep-api/v1/nap?start=14%3A00&latency=15" ``` **Response:** ```json { "data": { "naps": [ { "type": "power nap", "effect": "Quick alertness boost; stays in light sleep, so little grogginess.", "wake_at": { "time_12h": "2:35 PM", "time_24h": "14:35", "minute_of_day": 875 }, "nap_minutes": 20, "total_from_start": "0h 35m" }, { "type": "short nap", "effect": "Refreshing, but may cause brief grogginess on waking.", "wake_at": { "time_12h": "2:45 PM", "time_24h": "14:45", "minute_of_day": 885 }, "nap_minutes": 30, "total_from_start": "0h 45m" }, { "type": "slow-wave nap", "effect": "Aids memory and recall; expect noticeable grogginess (sleep inertia).", "wake_at": { "time_12h": "3:15 PM", "time_24h": "15:15", "minute_of_day": 915 }, "nap_minutes": 60, "total_from_start": "1h 15m" }, { "type": "full-cycle nap", "effect": "A complete sleep cycle including REM; usually wake with no grogginess.", "wake_at": { "time_12h": "3:45 PM", …(truncated, see openapi.json for full schema) ``` #### `GET /v1/wake-time` — Recommended wake times from a bedtime **Parameters:** - `bedtime` (query, optional, string) — Bedtime or "now" Example: `22:00` - `latency` (query, optional, string) — Minutes to fall asleep (default 15) Example: `15` - `cycle_length` (query, optional, string) — Cycle minutes (default 90) Example: `90` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/sleep-api/v1/wake-time?bedtime=22%3A00&latency=15&cycle_length=90" ``` **Response:** ```json { "data": { "advice": "If you go to bed now, wake at one of these times to rise at the end of a sleep cycle.", "bedtime": { "time_12h": "10:00 PM", "time_24h": "22:00", "minute_of_day": 1320 }, "asleep_at": { "time_12h": "10:15 PM", "time_24h": "22:15", "minute_of_day": 1335 }, "disclaimer": "Informational only — sleep needs vary by individual; not medical advice.", "wake_times": [ { "cycles": 3, "quality": "short", "wake_at": { "time_12h": "2:45 AM", "time_24h": "02:45", "minute_of_day": 165 }, "sleep_hours": 4.5, "sleep_duration": "4h 30m" }, { "cycles": 4, "quality": "minimum recommended", "wake_at": { "time_12h": "4:15 AM", "time_24h": "04:15", "minute_of_day": 255 }, "sleep_hours": 6, "sleep_duration": "6h" }, { "cycles": 5, "quality": "good", "wake_at": { "time_12h": "5:45 AM", "time_24h": "05:45", "minute_of_day": 345 }, "sleep_hours": …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Spec **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/sleep-api/v1/meta" ``` **Response:** ```json { "data": { "notes": "All clock maths is modulo 24h. Times accept 24h ('23:15') or 12h ('10:30 PM'); 'now' uses server local time.", "service": "sleep", "endpoints": { "/v1/nap": "Given a start time, suggest nap lengths (power / short / slow-wave / full-cycle) and end times.", "/v1/bedtime": "Given a wake-up time, suggest bedtimes ending on a sleep-cycle boundary.", "/v1/duration": "Given a bedtime and wake time, report sleep duration, full cycles, and cycle alignment.", "/v1/wake-time": "Given a bedtime (or 'now'), suggest wake times ending on a sleep-cycle boundary." }, "disclaimer": "Informational only — not medical advice.", "description": "Sleep-cycle calculator: recommended bedtimes, wake times, sleep duration analysis, and nap planning, based on ~90-minute sleep cycles.", "fall_asleep_minutes_default": 15, "cycle_length_minutes_default": 90 }, "meta": { "timestamp": "2026-06-03T17:42:02.078Z", "request_id": "43a2769f-9994-42ac-9b74-26039bba472d" }, "status": "ok", "message": "Meta", "success": true } ``` --- Marketplace page: https://www.oanor.com/api/sleep-api OpenAPI spec: https://www.oanor.com/api/sleep-api/openapi.json