Update device settings

curl --request PATCH \
  --url https://energy-api.flatpeak.com/devices/{device_id}/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "battery": {
    "backup_reserve_percent": 30
  }
}
'

{
  "object": "device_settings",
  "device_id": "dev_63a6087272941ef077a8fd3e",
  "supported": [
    "battery.backup_reserve_percent",
    "battery.strategy",
    "battery.storm_mode_enabled",
    "battery.export_rule",
    "battery.charge_from_grid_enabled",
    "battery.one_off_charge"
  ],
  "battery": {
    "backup_reserve_percent": 20,
    "strategy": "SELF_POWER",
    "storm_mode_enabled": true,
    "export_rule": "BATTERY_OK",
    "charge_from_grid_enabled": true,
    "one_off_charge": false
  },
  "sync_status": "IN_SYNC",
  "updated_by": "OEM",
  "time_updated": "2026-08-31T09:12:44Z",
  "account_id": "acc_661677911f2197045e6cf1b1"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

PATCH

devices

{device_id}

settings

curl --request PATCH \
  --url https://energy-api.flatpeak.com/devices/{device_id}/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "battery": {
    "backup_reserve_percent": 30
  }
}
'

{
  "object": "device_settings",
  "device_id": "dev_63a6087272941ef077a8fd3e",
  "supported": [
    "battery.backup_reserve_percent",
    "battery.strategy",
    "battery.storm_mode_enabled",
    "battery.export_rule",
    "battery.charge_from_grid_enabled",
    "battery.one_off_charge"
  ],
  "battery": {
    "backup_reserve_percent": 20,
    "strategy": "SELF_POWER",
    "storm_mode_enabled": true,
    "export_rule": "BATTERY_OK",
    "charge_from_grid_enabled": true,
    "one_off_charge": false
  },
  "sync_status": "IN_SYNC",
  "updated_by": "OEM",
  "time_updated": "2026-08-31T09:12:44Z",
  "account_id": "acc_661677911f2197045e6cf1b1"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

Authorizations

Authorization

string

header

required

Bearer token obtained from POST /auth/tokens.

Path Parameters

device_id

string

required

Flatpeak Device ID.

Body

application/json

Partial update of the device's desired operating settings. Send only the fields that change, nested under their namespace. When two writes change the same field, the last one wins.

battery

DeviceSettingsBattery · object

Desired operating settings for a battery. All fields are persistent except one_off_charge.

Show child attributes

evse

DeviceSettingsEvse · object

Desired operating settings for an EV charger.

Show child attributes

vehicle

DeviceSettingsVehicle · object

Desired operating settings for an electric vehicle.

Show child attributes

Response

Device settings record.

The device's desired settings, one record shared between you and its VPP operator. Device-local changes are reconciled in from your state submissions. supported lists the writable field paths; writes outside it return 422. Only the blocks for subsystems the device has are returned.

object

enum<string>

required

read-only

Object type, device_settings.

Available options:

device_settings

Example:

"device_settings"

device_id

string

required

read-only

Flatpeak Device ID of the device these settings belong to.

Example:

"dev_63a6087272941ef077a8fd3e"

supported

string[]

required

read-only

The field paths that can be written for this device, derived from its type and capabilities. Recomputed on a capabilities update. Empty for device types without settings.

Example:

[
  "battery.backup_reserve_percent",
  "battery.strategy",
  "battery.storm_mode_enabled",
  "battery.export_rule",
  "battery.charge_from_grid_enabled",
  "battery.one_off_charge"
]

sync_status

enum<string>

required

read-only

Whether the device has applied the desired settings, from comparing this record with reported state. Numeric fields compare within a tolerance. A null desired value is in sync only with a null reported value. one_off_charge is not compared, because device state does not report it. FAILED fires device.settings.sync_failed.

Available options:

IN_SYNC,

PENDING,

FAILED

Example:

"IN_SYNC"

updated_by

enum<string>

required

read-only

Who made the last change. When two writes change the same field, the last one wins.

Value	Meaning
`OPERATOR`	VPP operator
`OEM`	You, or a device-local change

Available options:

OPERATOR,

OEM

Example:

"OEM"

time_updated

string<date-time>

required

read-only

When the record last changed, in UTC.

Example:

"2026-08-31T09:12:44Z"

account_id

string

required

read-only

Flatpeak Account ID.

Pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$

Example:

"acc_661677911f2197045e6cf1b1"

battery

DeviceSettingsBattery · object

Desired operating settings for a battery. All fields are persistent except one_off_charge.

Show child attributes

evse

DeviceSettingsEvse · object

Desired operating settings for an EV charger.

Show child attributes

vehicle

DeviceSettingsVehicle · object

Desired operating settings for an electric vehicle.

Show child attributes

Platform

Tariffs

VPP

Update device settings

Authorizations

Path Parameters

Body

Response