{"openapi":"3.1.0","info":{"title":"BatteryHealth API","version":"0.1.0","description":"A fully local device-battery-health and charging-habit reference toolkit: brand-neutral lithium-ion battery science, a real charge-cycle estimator, device-type-specific nuances (phone/laptop/EV), a charging-habits checklist, and a glossary. General education only, not a diagnosis of any specific device.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://batteryhealth.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/batteryhealth/docs"},"termsOfService":"https://connectorbay.com/batteryhealth/terms"},"servers":[{"url":"https://batteryhealth.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/batteryhealth/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/battery_science":{"post":{"operationId":"battery_science","summary":"Real, brand-neutral lithium-ion battery science by topic: charge-cycle definition, depth-of-discharge","description":"Real, brand-neutral lithium-ion battery science by topic: charge-cycle definition, depth-of-discharge\n    impact on longevity, heat as a degradation factor, and the real nuance around avoiding 0%/100% extremes for\n    daily use on some devices versus when full charges are fine. Use for \"what is a battery charge cycle\", \"is\n    it bad to leave my phone at 100% all the time\", \"does heat damage batteries\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"charge cycles, depth of discharge, heat, charge extremes, or chemistry overview. Omit to list all.","examples":["charge cycles","charge extremes"],"title":"Topic"}},"title":"battery_scienceArguments","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/charge_cycle_estimator":{"post":{"operationId":"charge_cycle_estimator","summary":"Real computed math: estimates approximate total charge-cycle count from days-owned and a typical day's","description":"Real computed math: estimates approximate total charge-cycle count from days-owned and a typical day's\n    charging pattern. A full cycle is 100% of capacity used, which correctly accumulates across multiple partial\n    charges in the same day (e.g. a 40% top-up plus a separate 60% top-up on the same day together make one full\n    cycle). Use for \"how many charge cycles has my phone probably been through if I've had it for a year and\n    charge it twice a day\". Real math from the numbers given; not a reading of your device's actual battery\n    health.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"days_owned":{"description":"How many days you've owned/used the device.","exclusiveMinimum":0,"maximum":20000,"title":"Days Owned","type":"integer"},"charges":{"description":"A typical day's charging pattern: a list of {from_percent, to_percent} charge events. Multiple partial charges in one day are summed toward full cycles.","examples":[[{"from_percent":20,"to_percent":70},{"from_percent":70,"to_percent":100}]],"items":{"additionalProperties":{"type":"number"},"type":"object"},"title":"Charges","type":"array"}},"required":["days_owned","charges"],"title":"charge_cycle_estimatorArguments","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/device_type_guide":{"post":{"operationId":"device_type_guide","summary":"Brief, accurate, brand-neutral battery nuances by device type — phone (optimized/adaptive charging,","description":"Brief, accurate, brand-neutral battery nuances by device type — phone (optimized/adaptive charging,\n    fast wireless charging heat), laptop (charge-limit modes, CPU heat under load), and EV (active thermal\n    management/BMS, DC fast charging vs AC home charging, daily charge-level guidance). Use for \"is fast charging\n    bad for my EV\", \"should I use my laptop's battery charge limit\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_type":{"description":"phone, laptop, or ev.","examples":["phone","ev"],"title":"Device Type","type":"string"}},"required":["device_type"],"title":"device_type_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/charging_habits_checklist":{"post":{"operationId":"charging_habits_checklist","summary":"A general, brand-neutral charging-habits checklist: avoiding extremes when practical, using","description":"A general, brand-neutral charging-habits checklist: avoiding extremes when practical, using\n    manufacturer optimized-charging features, keeping the device cool while charging, and more. Use for\n    \"battery charging tips\", \"how should I charge my phone to make the battery last\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"charging_habits_checklistArguments","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/battery_glossary":{"post":{"operationId":"battery_glossary","summary":"Plain-language definitions of core battery-health terms: charge cycle, depth of discharge, state of","description":"Plain-language definitions of core battery-health terms: charge cycle, depth of discharge, state of\n    charge, battery management system (BMS), trickle charge, calendar aging, optimized/adaptive charging, and\n    thermal runaway. Use for \"what does depth of discharge mean\", \"what is a BMS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","examples":["depth of discharge","BMS"],"title":"Term"}},"title":"battery_glossaryArguments","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}}}}