Skip to main content
Use commands to charge, discharge, switch to self-consumption, or idle a battery. You can also list and cancel commands.

Command behavior

  • 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.

Time conventions

  • 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.

Energy limits

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.

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.

Batch control

Send up to 1,000 commands in one request. Each operation includes the battery id, an action, and the command parameters. Both start and end are required for every operation. Operations for the same battery must have non-overlapping windows. Kapa returns 202 Accepted with one result per operation. Invalid JSON, schema violations, more than 1,000 operations, or overlapping operations cause a whole-batch error. An unknown battery, an unsupported command, or an invalid time window rejects only the affected operation. Accepted operations proceed asynchronously. Batches are not atomic. Kapa does not roll back commands if other commands fail later.

Command status events

Receive command status changes at your HTTPS endpoint. Delivery is at least once and not ordered. Deduplicate with event_id and order changes with updated_at. Webhook registration is not covered by this version of the API.

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.