Send a batch of commands

Sends up to 1,000 commands, to one or many batteries, in a single request. Each operation takes the same parameters as the matching single-battery endpoint, plus id (the battery) and action. In a batch, start and end are required for every operation. A battery can appear in several operations if their windows do not overlap.

Kapa validates every operation immediately and returns 202 Accepted with one result per operation. Each accepted operation becomes a command carrying the batch’s batch_id, delivered to the manufacturer asynchronously. Follow it like any other command.

• Whole-batch errors (400): invalid JSON, schema violations, more than 1,000 operations, or two operations targeting the same battery over overlapping windows.
• Per-operation errors: unknown battery, command not applicable to that battery, invalid time window. Only that operation is rejected; the others proceed.

Batches are not atomic: there is no rollback if some commands fail later.

POST /bat/v1/batches

Send a batch of commands

cURL

curl --request POST \
  --url https://api.kapa.energy/bat/v1/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operations": [
    {
      "id": "bat_1",
      "action": "charge",
      "start": "2026-11-12T13:00:00Z",
      "end": "2026-11-12T15:00:00Z",
      "allow_import": true,
      "max_wh": 12000
    },
    {
      "id": "bat_2",
      "action": "discharge",
      "start": "2026-11-12T18:00:00Z",
      "end": "2026-11-12T19:00:00Z",
      "min_wh": 1500
    },
    {
      "id": "bat_3",
      "action": "idle",
      "start": "2026-11-12T18:00:00Z",
      "end": "2026-11-12T20:00:00Z"
    }
  ]
}
'

202

{
  "batch_id": "bch_81",
  "summary": {
    "total": 3,
    "accepted": 2,
    "rejected": 1
  },
  "results": [
    {
      "index": 0,
      "id": "bat_1",
      "status": "accepted",
      "command_id": "cmd_701",
      "error": null
    },
    {
      "index": 1,
      "id": "bat_2",
      "status": "accepted",
      "command_id": "cmd_702",
      "error": null
    },
    {
      "index": 2,
      "id": "bat_3",
      "status": "rejected",
      "command_id": null,
      "error": {
        "type": "https://api.kapa.energy/problems/battery-not-found",
        "title": "Battery not found",
        "status": 404,
        "code": "battery_not_found",
        "detail": "No battery with id bat_3 is accessible to this client."
      }
    }
  ]
}

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

Body

application/json

operations · object[] · required

Required array length: 1 - 1000 elements

Option 1

Option 2

Option 3

Option 4

Show child attributes

Response

202

application/json

Batch validated. One result per operation, in request order.

batch_id · string · required

Batch identifier, also set on every command the batch created.

summary · object · required

Show child attributes

results · object[] · required

One result per operation, in request order.

Show child attributes