> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Change a battery setting

> Update a battery's discharge floor, charge ceiling, or other persistent settings.

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.

```bash theme={null}
curl https://api.amps.ai/battery/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"
```

```json theme={null}
{
  "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.

```bash theme={null}
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" }
  }'
```

```json theme={null}
{
  "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](/guides/error-handling/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

<CardGroup cols={2}>
  <Card title="Settings" icon="sliders" href="/guides/capabilities/settings">
    Settings vs commands, and every setting code.
  </Card>

  <Card title="Battery cookbook" icon="battery-full" href="/cookbooks/battery">
    All battery recipes.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.