Put the battery on idle

The battery neither charges nor discharges during the window. Manufacturer safety functions (e.g. protection against deep discharge) may still act.

POST /bat/v1/{id}/idle

Put the battery on idle

cURL

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

202

{
  "command_id": "cmd_612",
  "battery_id": "bat_1",
  "action": "idle",
  "parameters": {},
  "start": "2026-11-12T18:00:00Z",
  "end": "2026-11-12T20:00:00Z",
  "status": "pending",
  "status_reason": null,
  "batch_id": null,
  "created_at": "2026-11-12T16:10:33Z",
  "updated_at": "2026-11-12T16:10:33Z"
}

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$

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"