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

# Control

> Send commands, track their status, and control batteries in batches.

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](https://docs.kapa.energy/webhooks/command-status-changed.md) 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.

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


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