Skip to main content
PUT
/
devices
/
{device_id}
/
state
Submit a device state
curl --request PUT \
  --url https://api.flatpeak.com/devices/{device_id}/state \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "time": "2022-02-01T10:30:00Z",
  "state_of_charge_percent": 34.2,
  "target_state_of_charge_percent": 80,
  "record_reference_id": "MET1234567890",
  "energy_flow_direction": "EXPORT",
  "battery_power_kw": 3.4,
  "energy_remaining_kwh": 8.3,
  "backup_reserve_percent": 20
}
'
{
  "device_id": "dev_6563a6757360a6d6a628e839",
  "id": "dsr_6a284b7596d3f2b722544e70",
  "account_id": "acc_661677911f2197045e6cf1b1",
  "time_created": "2022-02-01T10:33:00Z",
  "object": "device_state"
}

Authorizations

​
Authorization
string
header
required

Authenticate with bearer you obtained from authentication endpoint.

Path Parameters

​
device_id
string
required

Flatpeak Device ID.

Body

application/json

Submit the current operational state of a device, such as BESS state of charge and power.

​
time
string<date-time>
required

Time the measurement was recorded, in RFC3339 format.

Example:

"2022-02-01T10:30:00Z"

​
state_of_charge_percent
number
required

Current battery state of charge as a percentage from 0 to 100.

Example:

34.2

​
target_state_of_charge_percent
number
required

Target battery state of charge as a percentage from 0 to 100.

Example:

80

​
record_reference_id
string

Optional unique identifier for the telemetry record, used for idempotency and reconciliation.

Example:

"MET1234567890"

​
energy_flow_direction
enum<string>

Direction of energy flow this applies to. IMPORT (from grid) or EXPORT (to grid).

Available options:
IMPORT,
EXPORT
Example:

"EXPORT"

​
battery_power_kw
number

Current battery power in kilowatts.

Example:

3.4

​
energy_remaining_kwh
number

Estimated usable energy currently available in the battery, in kilowatt-hours.

Example:

8.3

​
backup_reserve_percent
number

Percentage of battery capacity reserved for backup and unavailable for optimisation or dispatch.

Example:

20

Response

Example response

​
device_id
string
required

Flatpeak device ID.

Example:

"dev_6563a6757360a6d6a628e839"

​
id
string
required

Flatpeak device state record ID.

Example:

"dsr_6a284b7596d3f2b722544e70"

​
account_id
string
required

Flatpeak Account ID.

Example:

"acc_661677911f2197045e6cf1b1"

​
time_created
string<date-time>
required

Time when this object was created. In UTC.

Example:

"2022-02-01T10:33:00Z"

​
object
string

Object type.

Example:

"device_state"