Skip to main content
POST
/
battery
/
{deviceId}
/
settings
curl
curl --request POST \
  --url 'https://api.amps.ai/battery/device_abc123/settings' \
  --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'content-type: application/json' \
  --data '{
    "safety_reserve": {
      "value": 20,
      "unit": "percent"
    }
  }'
{ "success": true, "data": { "deviceId": "device_abc123", "updated": [ "safety_reserve" ] }, "meta": { "requestId": "req_8a2Bf3kP", "environment": "sandbox", "timestamp": "2026-06-02T12:00:00.000Z", "latencyMs": 12 } }

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
deviceId
string
required

The unique identifier for the battery device.

Example:

"device_abc123"

Body

application/json

Sparse map of writable settings. At least one field is required. Each value uses the canonical { value, unit } shape; unit must match the canonical setting.

Sparse map of writable settings. At least one field is required. Unknown or read-only keys are rejected with UNSUPPORTED_SETTING.

​
safety_reserve
Quantity · object

The lowest state-of-charge the battery will ever reach, even during a power cut. (unit: percent, min: 0, max: 100)

​
discharge_floor
Quantity · object

The lowest state-of-charge the battery will reach during normal operation. (unit: percent, min: 0, max: 100)

​
charge_ceiling
Quantity · object

The highest state-of-charge the battery will charge to. (unit: percent, min: 0, max: 100)

​
export_limit
Quantity · object

Maximum power the battery can send back to the grid. (unit: watts, min: 0)

​
max_charge_rate
Quantity · object

Maximum rate the battery will charge at. (unit: amps, min: 0, max: 1000)

​
max_discharge_rate
Quantity · object

Maximum rate the battery will discharge at. (unit: amps, min: 0, max: 1000)

Response

Settings written. Response lists the canonical setting keys that changed.

​
success
boolean
required

Always true for success responses.

​
data
Battery Settings Update · object
required

Acknowledgement of a settings write. updated lists the canonical setting keys that changed; OEMs that fire-and-forget will still echo the keys.

​
meta
Response Meta · object
required

Metadata attached to every response: the request identifier, the serving environment, the build timestamp, and the server-side latency.