Switch to self-consumption
curl --request POST \
--url https://api.kapa.energy/bat/v1/{id}/autoconsume \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"start": "2026-11-12T08:00:00Z",
"end": "2026-11-12T17:00:00Z",
"min_wh": 2600,
"max_wh": 13000
}
'import requests
url = "https://api.kapa.energy/bat/v1/{id}/autoconsume"
payload = {
"start": "2026-11-12T08:00:00Z",
"end": "2026-11-12T17:00:00Z",
"min_wh": 2600,
"max_wh": 13000
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
start: '2026-11-12T08:00:00Z',
end: '2026-11-12T17:00:00Z',
min_wh: 2600,
max_wh: 13000
})
};
fetch('https://api.kapa.energy/bat/v1/{id}/autoconsume', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.kapa.energy/bat/v1/{id}/autoconsume",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'start' => '2026-11-12T08:00:00Z',
'end' => '2026-11-12T17:00:00Z',
'min_wh' => 2600,
'max_wh' => 13000
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.kapa.energy/bat/v1/{id}/autoconsume"
payload := strings.NewReader("{\n \"start\": \"2026-11-12T08:00:00Z\",\n \"end\": \"2026-11-12T17:00:00Z\",\n \"min_wh\": 2600,\n \"max_wh\": 13000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.kapa.energy/bat/v1/{id}/autoconsume")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"start\": \"2026-11-12T08:00:00Z\",\n \"end\": \"2026-11-12T17:00:00Z\",\n \"min_wh\": 2600,\n \"max_wh\": 13000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.kapa.energy/bat/v1/{id}/autoconsume")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"start\": \"2026-11-12T08:00:00Z\",\n \"end\": \"2026-11-12T17:00:00Z\",\n \"min_wh\": 2600,\n \"max_wh\": 13000\n}"
response = http.request(request)
puts response.read_body{
"command_id": "cmd_611",
"battery_id": "bat_1",
"action": "autoconsume",
"parameters": {
"min_wh": 2600,
"max_wh": 13000
},
"start": "2026-11-12T08:00:00Z",
"end": "2026-11-12T17:00:00Z",
"status": "pending",
"status_reason": null,
"batch_id": null,
"created_at": "2026-11-12T07:45:12Z",
"updated_at": "2026-11-12T07:45:12Z"
}{
"type": "https://api.kapa.energy/problems/invalid-time-window",
"title": "Invalid time window",
"status": 400,
"code": "invalid_time_window",
"detail": "end must be after start.",
"invalid_params": [
{
"name": "end",
"reason": "must be after start"
}
]
}{
"type": "https://api.kapa.energy/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"code": "unauthorized",
"detail": "The access token has expired."
}{
"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_9 is accessible to this client."
}{
"type": "https://api.kapa.energy/problems/idempotency-key-in-use",
"title": "Idempotency key in use",
"status": 409,
"code": "idempotency_key_in_use",
"detail": "Retry once the original request has completed."
}{
"type": "https://api.kapa.energy/problems/energy-out-of-range",
"title": "Energy out of range",
"status": 422,
"code": "energy_out_of_range",
"detail": "max_wh (15000) exceeds the usable capacity of this battery (13000 Wh).",
"invalid_params": [
{
"name": "max_wh",
"reason": "exceeds usable_capacity_wh"
}
]
}Commands
Switch to self-consumption
Self-consumption: the battery stores on-site production surplus and discharges
to cover site consumption, to minimise grid import and export. Stored energy is
kept between min_wh and max_wh.
POST
/
bat
/
v1
/
{id}
/
autoconsume
Switch to self-consumption
curl --request POST \
--url https://api.kapa.energy/bat/v1/{id}/autoconsume \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"start": "2026-11-12T08:00:00Z",
"end": "2026-11-12T17:00:00Z",
"min_wh": 2600,
"max_wh": 13000
}
'import requests
url = "https://api.kapa.energy/bat/v1/{id}/autoconsume"
payload = {
"start": "2026-11-12T08:00:00Z",
"end": "2026-11-12T17:00:00Z",
"min_wh": 2600,
"max_wh": 13000
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
start: '2026-11-12T08:00:00Z',
end: '2026-11-12T17:00:00Z',
min_wh: 2600,
max_wh: 13000
})
};
fetch('https://api.kapa.energy/bat/v1/{id}/autoconsume', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.kapa.energy/bat/v1/{id}/autoconsume",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'start' => '2026-11-12T08:00:00Z',
'end' => '2026-11-12T17:00:00Z',
'min_wh' => 2600,
'max_wh' => 13000
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.kapa.energy/bat/v1/{id}/autoconsume"
payload := strings.NewReader("{\n \"start\": \"2026-11-12T08:00:00Z\",\n \"end\": \"2026-11-12T17:00:00Z\",\n \"min_wh\": 2600,\n \"max_wh\": 13000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.kapa.energy/bat/v1/{id}/autoconsume")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"start\": \"2026-11-12T08:00:00Z\",\n \"end\": \"2026-11-12T17:00:00Z\",\n \"min_wh\": 2600,\n \"max_wh\": 13000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.kapa.energy/bat/v1/{id}/autoconsume")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"start\": \"2026-11-12T08:00:00Z\",\n \"end\": \"2026-11-12T17:00:00Z\",\n \"min_wh\": 2600,\n \"max_wh\": 13000\n}"
response = http.request(request)
puts response.read_body{
"command_id": "cmd_611",
"battery_id": "bat_1",
"action": "autoconsume",
"parameters": {
"min_wh": 2600,
"max_wh": 13000
},
"start": "2026-11-12T08:00:00Z",
"end": "2026-11-12T17:00:00Z",
"status": "pending",
"status_reason": null,
"batch_id": null,
"created_at": "2026-11-12T07:45:12Z",
"updated_at": "2026-11-12T07:45:12Z"
}{
"type": "https://api.kapa.energy/problems/invalid-time-window",
"title": "Invalid time window",
"status": 400,
"code": "invalid_time_window",
"detail": "end must be after start.",
"invalid_params": [
{
"name": "end",
"reason": "must be after start"
}
]
}{
"type": "https://api.kapa.energy/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"code": "unauthorized",
"detail": "The access token has expired."
}{
"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_9 is accessible to this client."
}{
"type": "https://api.kapa.energy/problems/idempotency-key-in-use",
"title": "Idempotency key in use",
"status": 409,
"code": "idempotency_key_in_use",
"detail": "Retry once the original request has completed."
}{
"type": "https://api.kapa.energy/problems/energy-out-of-range",
"title": "Energy out of range",
"status": 422,
"code": "energy_out_of_range",
"detail": "max_wh (15000) exceeds the usable capacity of this battery (13000 Wh).",
"invalid_params": [
{
"name": "max_wh",
"reason": "exceeds usable_capacity_wh"
}
]
}Authorizations
OAuth 2.0 client credentials. Obtain a token from POST /token.
Headers
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:
255Path Parameters
Battery identifier.
Body
application/json
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 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$Lowest stored energy level, in Wh. Below it, the battery stops discharging to cover site consumption. Omitted or null means the lowest level the manufacturer allows.
Required range:
x >= 0Highest stored energy level, in Wh. Above it, the battery stops charging from
on-site production. Must be greater than or equal to min_wh and must not
exceed usable_capacity_wh. Omitted or null means the full usable capacity.
Required range:
x >= 0Response
Command accepted. Its status then evolves asynchronously.
Command identifier.
Battery identifier.
charge: charge the battery.discharge: discharge the battery.autoconsume: self-consumption.idle: neither charge nor discharge.
Available options:
charge, discharge, autoconsume, idle 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
Show child attributes
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 (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$pending: accepted by Kapa, not yet acknowledged by the manufacturer's cloud.scheduled: acknowledged by the manufacturer;startis in the future.active: in effect on the battery.completed: the window ended normally.cancelled: cancelled withcancel_command.superseded: the whole window is covered by more recent commands.failed: the command could not be applied; seestatus_reason.
Available options:
pending, scheduled, active, completed, cancelled, superseded, failed Machine-readable reason when status is failed, e.g. oem_rejected,
oem_unreachable, battery_offline. Null otherwise.
Identifier of the batch that created the command. Null for single commands.
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"
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"