Change a battery setting - Amps AI Documentation

Settings are persistent limits, like the lowest charge level the battery will discharge to. Change them with POST /battery/{id}/settings. Unlike commands, settings writes are applied in the request and return 200.

1. Check the battery supports it

settings lists each setting the battery supports, with its current value, unit, and bounds. A setting the battery doesn’t report in a usable form is left out.

curl https://api.amps.ai/battery/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "settings": {
      "safety_reserve": { "value": 10, "unit": "percent", "min": 0, "max": 100 },
      "discharge_floor": { "value": 20, "unit": "percent", "min": 0, "max": 100 },
      "charge_ceiling": { "value": 100, "unit": "percent", "min": 0, "max": 100 },
      "export_limit": { "value": 5000, "unit": "watts", "min": 0 },
      "max_charge_rate": { "value": 25, "unit": "amps", "min": 0, "max": 1000 },
      "max_discharge_rate": { "value": 25, "unit": "amps", "min": 0, "max": 1000 },
      "scheduler_enabled": { "value": false }
    }
  }
}

Setting	Unit
`safety_reserve`	`percent`	Lowest charge level, even in a power cut.
`discharge_floor`	`percent`	Lowest charge level in normal operation.
`charge_ceiling`	`percent`	Highest charge level.
`export_limit`	`watts`	Maximum export to the grid.
`max_charge_rate`	`amps`	Maximum charge current.
`max_discharge_rate`	`amps`	Maximum discharge current.
`scheduler_enabled`		Read-only.

2. Send the update

Send only the settings you want to change. Each value needs the unit shown in step 1.

curl -X POST https://api.amps.ai/battery/device_abc123/settings \
  -H "x-api-key: $AMPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discharge_floor": { "value": 15, "unit": "percent" },
    "charge_ceiling": { "value": 95, "unit": "percent" }
  }'

{
  "success": true,
  "data": {
    "deviceId": "device_abc123",
    "updated": ["discharge_floor", "charge_ceiling"]
  }
}

Response	When
`422 DEVICE_NOT_CAPABLE`	The battery doesn’t list the setting, or it is read-only.
`422 SETTING_OUT_OF_RANGE`	The value is outside `min`/`max`, or one the battery can’t deliver.
`422 INVALID_SETTING_UNIT`	The unit doesn’t match.
`409 SCHEDULER_ACTIVE`	A schedule running on the device blocks the write.

See Error codes.

3. Confirm

updated lists the settings that changed. A battery can round a value to the nearest step its hardware supports, so read the battery again to see what it holds.

Next steps

Settings

Settings vs commands, and every setting code.

Battery cookbook

All battery recipes.