{"openapi":"3.1.0","info":{"title":"Restwell API","version":"0.1.0","description":"Sleep-science calculators and reference: bedtime/wake cycles, sleep debt, naps, chronotype, jet lag, caffeine cutoff, hygiene, sound — all local.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://restwell.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/restwell/docs"},"termsOfService":"https://connectorbay.com/restwell/terms"},"servers":[{"url":"https://restwell.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/restwell/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/bedtime_calculator":{"post":{"operationId":"bedtime_calculator","summary":"Bedtime options timed to whole 90-minute sleep cycles before a target wake time, so you wake between","description":"Bedtime options timed to whole 90-minute sleep cycles before a target wake time, so you wake between\n    cycles rather than mid-cycle. Use for \"what time should I go to bed if I wake at 6:30am\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"wake_time":{"description":"Desired wake-up time.","examples":["6:30am","7:00 AM","06:30"],"title":"Wake Time","type":"string"},"min_cycles":{"default":4,"maximum":8,"minimum":1,"title":"Min Cycles","type":"integer"},"max_cycles":{"default":6,"maximum":8,"minimum":1,"title":"Max Cycles","type":"integer"}},"required":["wake_time"],"title":"bedtime_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/wake_time_calculator":{"post":{"operationId":"wake_time_calculator","summary":"Wake-up options timed to whole 90-minute sleep cycles after a planned bedtime. Use for \"when should I","description":"Wake-up options timed to whole 90-minute sleep cycles after a planned bedtime. Use for \"when should I\n    wake up if I go to bed at 11pm\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bedtime":{"description":"Planned bedtime.","examples":["11:00pm","10:30 PM","23:00"],"title":"Bedtime","type":"string"},"min_cycles":{"default":4,"maximum":8,"minimum":1,"title":"Min Cycles","type":"integer"},"max_cycles":{"default":6,"maximum":8,"minimum":1,"title":"Max Cycles","type":"integer"}},"required":["bedtime"],"title":"wake_time_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/sleep_cycle_info":{"post":{"operationId":"sleep_cycle_info","summary":"Reference on the four sleep stages (N1, N2, N3, REM) and how ~90-minute cycles repeat through the","description":"Reference on the four sleep stages (N1, N2, N3, REM) and how ~90-minute cycles repeat through the\n    night. Use for \"what happens during deep sleep\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"sleep_cycle_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/sleep_debt_tracker":{"post":{"operationId":"sleep_debt_tracker","summary":"Accumulated sleep debt against a target, with a gradual recovery plan. Use for \"how much sleep debt do","description":"Accumulated sleep debt against a target, with a gradual recovery plan. Use for \"how much sleep debt do\n    I have from this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"nightly_hours":{"description":"Hours slept each of the last several nights, oldest first.","examples":[[6.5,7,5.5,6,8,7,6.5]],"items":{"type":"number"},"title":"Nightly Hours","type":"array"},"target_hours":{"default":8.0,"maximum":12,"minimum":4,"title":"Target Hours","type":"number"}},"required":["nightly_hours"],"title":"sleep_debt_trackerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/nap_guide":{"post":{"operationId":"nap_guide","summary":"Nap length types (power/recovery/full-cycle) and the timing/length rules that avoid a groggy wake-up.","description":"Nap length types (power/recovery/full-cycle) and the timing/length rules that avoid a groggy wake-up.\n    Use for \"how long should my nap be\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"goal":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"What you want from the nap, e.g. 'quick boost', 'full recovery'.","title":"Goal"}},"title":"nap_guideArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/chronotype_quiz":{"post":{"operationId":"chronotype_quiz","summary":"Find whether you're a Lion/Bear/Wolf/Dolphin chronotype: call with no arguments for the quiz","description":"Find whether you're a Lion/Bear/Wolf/Dolphin chronotype: call with no arguments for the quiz\n    questions, call again with `answers` for your result, or pass `chronotype` to look one up directly. Use\n    for \"am I a night owl or early bird\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"answers":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"description":"Question-key to option-index (0-3) map. Omit to get the questions first.","title":"Answers"},"chronotype":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Look up a chronotype by name directly instead of taking the quiz.","examples":["Lion","Bear","Wolf","Dolphin"],"title":"Chronotype"}},"title":"chronotype_quizArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/jet_lag_planner":{"post":{"operationId":"jet_lag_planner","summary":"An adjustment-day estimate and a day-by-day light/schedule strategy for jet lag. Use for \"how do I","description":"An adjustment-day estimate and a day-by-day light/schedule strategy for jet lag. Use for \"how do I\n    adjust for jet lag flying to Tokyo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"timezones_crossed":{"description":"Number of time zones crossed.","maximum":14,"minimum":0,"title":"Timezones Crossed","type":"integer"},"direction":{"description":"'east' or 'west' — the direction you are flying.","title":"Direction","type":"string"}},"required":["timezones_crossed","direction"],"title":"jet_lag_plannerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/caffeine_calculator":{"post":{"operationId":"caffeine_calculator","summary":"How much caffeine is likely still active at bedtime (using a ~5.5h half-life), or a reference table of","description":"How much caffeine is likely still active at bedtime (using a ~5.5h half-life), or a reference table of\n    common drinks' caffeine content if no amount is given. Use for \"will my 3pm coffee affect an 11pm\n    bedtime\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mg_consumed":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Milligrams of caffeine consumed. Omit (with hours_before_bed) to just see the drink reference table.","title":"Mg Consumed"},"hours_before_bed":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Hours between that drink and your planned bedtime.","title":"Hours Before Bed"}},"title":"caffeine_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/sleep_hygiene_tips":{"post":{"operationId":"sleep_hygiene_tips","summary":"Evidence-based sleep hygiene tips, optionally filtered by category. Use for \"sleep hygiene tips for a","description":"Evidence-based sleep hygiene tips, optionally filtered by category. Use for \"sleep hygiene tips for a\n    hot bedroom\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"routine | environment | diet | technology | activity","title":"Category"}},"title":"sleep_hygiene_tipsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/sound_guide":{"post":{"operationId":"sound_guide","summary":"Background sound types (white/pink/brown noise, nature sounds, fan hum) and what each is best for. Use","description":"Background sound types (white/pink/brown noise, nature sounds, fan hum) and what each is best for. Use\n    for \"what's the difference between white noise and pink noise\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sound":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A sound type to look up; omit to list all.","examples":["white noise","pink noise","brown noise"],"title":"Sound"}},"title":"sound_guideArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}