Discharge the battery

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.

POST /bat/v1/{id}/discharge

Discharge the battery

cURL

curl --request POST \
  --url https://api.kapa.energy/bat/v1/{id}/discharge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start": "2026-11-12T18:00:00Z",
  "end": "2026-11-12T19:00:00Z",
  "min_wh": 1500
}
'

202

{
  "command_id": "cmd_610",
  "battery_id": "bat_1",
  "action": "discharge",
  "parameters": {
    "min_wh": 1500,
    "max_wh": null
  },
  "start": "2026-11-12T18:00:00Z",
  "end": "2026-11-12T19:00:00Z",
  "status": "pending",
  "status_reason": null,
  "batch_id": null,
  "created_at": "2026-11-12T16:02:51Z",
  "updated_at": "2026-11-12T16:02:51Z"
}

Authorizations

Authorization · string · header · required

OAuth 2.0 client credentials. Obtain a token from POST /token.

Headers

Idempotency-Key · string

Unique value identifying this request (a UUID is recommended). Reuse the same key and the same body when retrying. See Idempotency in the API description.

Maximum string length: 255

Path Parameters

id · string · required

Battery identifier.

Body

application/json

start · string<date-time> | null

Start of the command (inclusive). Omitted or null means as soon as possible.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$

end · string<date-time> | null

End of the command (exclusive). Omitted or null means until cancelled or superseded.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$

min_wh · integer | null

Stored energy level, in Wh, at which discharging stops. Omitted or null means down to the lowest level the manufacturer allows.

Required range: x >= 0

max_wh · integer | null

To be confirmed. The meaning of this parameter for a discharge is not defined yet.

Required range: x >= 0

Response

202

application/json

Command accepted. Its status then evolves asynchronously.

command_id · string · required

Command identifier.

battery_id · string · required

Battery identifier.

action · enum<string> · required

• charge: charge the battery.
• discharge: discharge the battery.
• autoconsume: self-consumption.
• idle: neither charge nor discharge.

Available options: charge, discharge, autoconsume, idle

parameters · object · required

Action-specific parameters, as accepted. charge uses allow_import and max_wh; discharge and autoconsume use min_wh and max_wh; idle has none.

Show child attributes

start · string<date-time> · required

Effective start (inclusive). If the request omitted start, or gave a time in the past, this is the time Kapa accepted the command.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$

Example:

"2026-11-12T18:00:00Z"

end · string<date-time> | null · required

End (exclusive). Null means open-ended, until cancelled or superseded.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$

status · enum<string> · required

• pending: accepted by Kapa, not yet acknowledged by the manufacturer's cloud.
• scheduled: acknowledged by the manufacturer; start is in the future.
• active: in effect on the battery.
• completed: the window ended normally.
• cancelled: cancelled with cancel_command.
• superseded: the whole window is covered by more recent commands.
• failed: the command could not be applied; see status_reason.

Available options: pending, scheduled, active, completed, cancelled, superseded, failed

status_reason · string | null · required

Machine-readable reason when status is failed, e.g. oem_rejected, oem_unreachable, battery_offline. Null otherwise.

batch_id · string | null · required

Identifier of the batch that created the command. Null for single commands.

created_at · string<date-time> · required

When Kapa accepted the command.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$

Example:

"2026-11-12T18:00:00Z"

updated_at · string<date-time> · required

Last status change.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$

Example:

"2026-11-12T18:00:00Z"