> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapa.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Kapa Energy Battery API

> Control and monitor residential batteries across manufacturers through one API.

> [!NOTE]
>
> This reference documents version `1.0.0-draft.1` of the API.

The Kapa Energy Battery API gives HEMS and VPP operators a single interface to send
commands to residential batteries and read their telemetry, whatever the
manufacturer. Kapa translates each request into the manufacturer's own cloud API.

## Conventions

### Time

* Timestamps are RFC 3339, in UTC, with a `Z` suffix: `2026-11-12T18:00:00Z`.
* Durations are ISO 8601: `PT15M`.
* Time windows are half-open, `[start, end)`: `start` is included, `end` is excluded.

### Power

Power is in watts (W), as integers.

* **Positive (+)**: the battery is discharging, or the site is exporting to the grid.
* **Negative (−)**: the battery is charging, or the site is importing from the grid.

Nominal ratings such as `nominal_charge_power_w` are magnitudes and are always positive.

### Energy

Energy is in watt-hours (Wh), as integers. Battery levels are expressed as stored
energy in Wh rather than state of charge in %, because the meaning of SoC differs
between manufacturers. Stored energy is measured against the usable capacity: it
ranges from 0 to `usable_capacity_wh`.

### Telemetry

* Each data point carries two times: `measured_at`, when the device took the
  measurement, and `received_at`, when Kapa retrieved it from the manufacturer's cloud.
* Data points are never interpolated or resampled. Each point is an actual
  measurement reported by the manufacturer. Units, signs and field names are
  standardised across manufacturers; a field the manufacturer does not report is `null`.

## Commands

* Commands are asynchronous. Command endpoints return `202 Accepted` with a command
  whose `status` then evolves. Follow it with `GET /bat/v1/{id}/commands` or the
  `command.status_changed` webhook.
* A `start` in the past is treated as the time Kapa accepts the command.
* **Overlaps:** when a new command overlaps existing commands on the same battery,
  the newest command takes precedence over the overlapping period. Older commands
  stay in effect outside it. A command whose whole window is covered by newer
  commands becomes `superseded`.
* Outside any command window, the battery follows its **default behaviour**: the
  mode its owner configured in the manufacturer's app.

## Idempotency

Command and batch endpoints accept an optional `Idempotency-Key` header. Kapa stores
the key with the response for 24 hours. A retry with the same key and the same body
returns the original response without sending anything again.

## Errors

Errors use RFC 9457 Problem Details (`application/problem+json`). The `code` field is
stable and meant for programs; `title` and `detail` are meant for humans.

| `code` | HTTP | Meaning |
| - | - | - |
| `invalid_parameters` | 400 | A parameter is missing, malformed or inconsistent (e.g. `min_wh` greater than `max_wh`). |
| `invalid_time_window` | 400 | `start` is not before `end`, or `end` is in the past. |
| `overlapping_operations` | 400 | Two operations of a batch target the same battery over overlapping windows. |
| `unauthorized` | 401 | The access token is missing, invalid or expired. |
| `battery_not_found` | 404 | No battery with this id is accessible to the client. |
| `idempotency_key_in_use` | 409 | A request with the same `Idempotency-Key` is still being processed. |
| `action_not_supported` | 422 | The battery cannot apply this command or parameter (e.g. `allow_import: false`). |
| `energy_out_of_range` | 422 | An energy level exceeds the battery's usable capacity. |
| `idempotency_key_reused` | 422 | The `Idempotency-Key` was already used with a different request body. |

## Webhooks

Kapa pushes telemetry and command status changes to an HTTPS endpoint. Delivery is
at least once and not ordered: deduplicate with `event_id`, and order data with
`measured_at` or `updated_at`. Webhook registration is not covered by this version
of the API.


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