Kapa Energy Battery API

Control and monitor residential batteries across manufacturers through one API.

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.