# Kapa Energy Battery API

- [Kapa Energy Battery API](https://docs.kapa.energy/index.md): Control and monitor residential batteries across manufacturers through one API.
- [Quickstart](https://docs.kapa.energy/quickstart.md): Get an access token and read battery information.
- [Get an access token](https://docs.kapa.energy/api-reference/authentication/get-an-access-token.md): OAuth 2.0 client credentials grant (RFC 6749, section 4.4). Send the returned token as `Authorization: Bearer <access_token>` with every other request, and request a new one when it expires.
- [Get battery information](https://docs.kapa.energy/api-reference/batteries/get-battery-information.md): Static characteristics of the battery, standardised across manufacturers.
- [Charge the battery](https://docs.kapa.energy/api-reference/commands/charge-the-battery.md): Charges the battery at the highest power the device allows, from on-site production and, if `allow_import` is true, from the grid. Charging stops when stored energy reaches `max_wh`, or at `end`.
- [Discharge the battery](https://docs.kapa.energy/api-reference/commands/discharge-the-battery.md): Discharges the battery at the highest power the device allows. Energy not consumed on site is exported to the grid, within any export limit applied by the manufacturer or the installation. Discharging stops when stored energy reaches `min_wh`, or at `end`.
- [Switch to self-consumption](https://docs.kapa.energy/api-reference/commands/switch-to-self-consumption.md): Self-consumption: the battery stores on-site production surplus and discharges to cover site consumption, to minimise grid import and export. Stored energy is kept between `min_wh` and `max_wh`.
- [Put the battery on idle](https://docs.kapa.energy/api-reference/commands/put-the-battery-on-idle.md): The battery neither charges nor discharges during the window. Manufacturer safety functions (e.g. protection against deep discharge) may still act.
- [List commands](https://docs.kapa.energy/api-reference/commands/list-commands.md): Commands on this battery whose window overlaps `[start, end)`, with their current status, most recently created first.
- [Cancel commands](https://docs.kapa.energy/api-reference/commands/cancel-commands.md): Cancels every unfinished command on this battery (`pending`, `scheduled` or `active`) whose window overlaps `[start, end)`. With an empty body, all current and upcoming commands are cancelled.
- [Command status changed](https://docs.kapa.energy/api-reference/commands/command-status-changed.md): Sent each time the status of a command changes. Carries the full command.
- [Get telemetry history](https://docs.kapa.energy/api-reference/telemetry/get-telemetry-history.md): Measurements taken during `[start, end)`, in ascending `measured_at` order. Points are returned as reported by the manufacturer, without interpolation, so their spacing can be irregular and can differ between batteries.
- [Get latest telemetry](https://docs.kapa.energy/api-reference/telemetry/get-latest-telemetry.md): The most recent measurement Kapa has received for this battery. `point` is null if no measurement has been received yet.
- [New telemetry points](https://docs.kapa.energy/api-reference/telemetry/new-telemetry-points.md): Sent when Kapa retrieves new measurements from manufacturers' clouds. One delivery can carry points for several batteries. A missed delivery can be recovered with `GET /bat/v1/{id}/telemetry`.
- [Send a batch of commands](https://docs.kapa.energy/api-reference/batches/send-a-batch-of-commands.md): Sends up to 1,000 commands, to one or many batteries, in a single request. Each operation takes the same parameters as the matching single-battery endpoint, plus `id` (the battery) and `action`. In a batch, `start` and `end` are required for every operation. A battery can appear in several operation…
- [New telemetry points](https://docs.kapa.energy/webhooks/telemetry.md): Receive telemetry events at your HTTPS endpoint.
- [Command status changed](https://docs.kapa.energy/webhooks/command-status-changed.md): Receive command.status_changed events at your HTTPS endpoint.

## OpenAPI Specs

- [openapi](/openapi.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.