{"openapi":"3.1.0","info":{"title":"Sleep Cycle API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/sleep-api","description":"oanor gateway"}],"tags":[{"name":"Sleep"},{"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/bedtime":{"get":{"operationId":"get_v1_bedtime","tags":["Sleep"],"summary":"Recommended bedtimes from a wake time","description":"","parameters":[{"name":"wake","in":"query","required":true,"description":"Wake-up time","schema":{"type":"string"},"example":"07:00"},{"name":"latency","in":"query","required":false,"description":"Minutes to fall asleep (default 15)","schema":{"type":"string"},"example":"15"},{"name":"cycle_length","in":"query","required":false,"description":"Cycle minutes (default 90)","schema":{"type":"string"},"example":"90"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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","time_24h":"02:15","minute_of_day":135},"sleep_hours":4.5,"sleep_duration":"4h 30m"}],"disclaimer":"Informational only — sleep needs vary by individual; not medical advice.","fall_asleep_minutes":15,"cycle_length_minutes":90},"meta":{"timestamp":"2026-06-03T17:42:01.669Z","request_id":"78db587f-7d48-4bf1-a77b-ec54a5ee4406"},"status":"ok","message":"Recommended bedtimes","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/duration":{"get":{"operationId":"get_v1_duration","tags":["Sleep"],"summary":"Sleep duration & cycle analysis","description":"","parameters":[{"name":"bedtime","in":"query","required":true,"description":"Bedtime","schema":{"type":"string"},"example":"23:00"},{"name":"wake","in":"query","required":true,"description":"Wake time","schema":{"type":"string"},"example":"07:00"},{"name":"latency","in":"query","required":false,"description":"Minutes to fall asleep (default 0)","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"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/nap":{"get":{"operationId":"get_v1_nap","tags":["Sleep"],"summary":"Nap planner","description":"","parameters":[{"name":"start","in":"query","required":false,"description":"Nap start or \"now\"","schema":{"type":"string"},"example":"14:00"},{"name":"latency","in":"query","required":false,"description":"Minutes to fall asleep (default 15)","schema":{"type":"string"},"example":"15"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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","time_24h":"15:45","minute_of_day":945},"nap_minutes":90,"total_from_start":"1h 45m"}],"advice":"For an alertness boost without grogginess, keep naps to ~20 minutes or do a full 90-minute cycle.","start_at":{"time_12h":"2:00 PM","time_24h":"14:00","minute_of_day":840},"asleep_at":{"time_12h":"2:15 PM","time_24h":"14:15","minute_of_day":855},"disclaimer":"Informational only — sleep needs vary by individual; not medical advice.","fall_asleep_minutes":15},"meta":{"timestamp":"2026-06-03T17:42:01.860Z","request_id":"fa4b1232-da5f-4c6c-9a8f-5dae3e4b9835"},"status":"ok","message":"Nap planner","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/wake-time":{"get":{"operationId":"get_v1_wake_time","tags":["Sleep"],"summary":"Recommended wake times from a bedtime","description":"","parameters":[{"name":"bedtime","in":"query","required":false,"description":"Bedtime or \"now\"","schema":{"type":"string"},"example":"22:00"},{"name":"latency","in":"query","required":false,"description":"Minutes to fall asleep (default 15)","schema":{"type":"string"},"example":"15"},{"name":"cycle_length","in":"query","required":false,"description":"Cycle minutes (default 90)","schema":{"type":"string"},"example":"90"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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":7.5,"sleep_duration":"7h 30m"},{"cycles":6,"quality":"ideal","wake_at":{"time_12h":"7:15 AM","time_24h":"07:15","minute_of_day":435},"sleep_hours":9,"sleep_duration":"9h"}],"fall_asleep_minutes":15,"cycle_length_minutes":90},"meta":{"timestamp":"2026-06-03T17:42:01.960Z","request_id":"8b04277d-346b-450d-8924-4b3cdc3bd39b"},"status":"ok","message":"Recommended wake times","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":"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}}}},"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":8935,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1045,"monthly_call_quota":18550,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3035,"monthly_call_quota":235500,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":6835,"monthly_call_quota":1220000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/sleep-api"}