Energy API reference

The Energy API is for OEMs: the companies that make batteries, EV chargers, vehicles, heat pumps and inverters. It connects your users’ tariffs and prices every device. With VPP, it enrolls devices in programs and delivers their instructions.

Make a request

The base URL is https://energy-api.flatpeak.com. Exchange your Account ID and a secret key for a bearer token, then send the token on every other request. A token lasts one hour.

curl --request POST \
  --url https://energy-api.flatpeak.com/auth/tokens \
  --user "$ACCOUNT_ID:$SECRET_KEY"

curl --request GET \
  --url https://energy-api.flatpeak.com/devices \
  --header "Authorization: Bearer $BEARER_TOKEN" \
  --header 'Flatpeak-Version: 2027-01-01.busbar'

The secret key sets the mode: sk_test_ keys work on test data, sk_live_ keys on live data. See Authentication and test mode.

Layout

Group	Covers
Platform	Authentication, events, users, locations, devices
Tariffs	Connect sessions and pages, tariffs, prices, optimizations, costs, meter records
VPP	Programs, enrollments, instructions, device state and settings, VPP events, groups, zones

VPP is optional and uses the same users, locations, devices and tariffs. Start with the quickstart, then add VPP with the VPP quickstart.

Specs

Spec	Contains
`flatpeak-api-spec-energy-tariffs.json`	Platform and Tariffs
`flatpeak-api-spec-energy.json`	Everything

What VPP adds lists the fields VPP adds to users, locations, devices and Connect sessions.

Object model

A tariff belongs to a location, and every device at the location prices against it. A VPP enrollment belongs to a device, so devices at one address take part independently.

Object	ID prefix	What it is
User	`usr_`	The person who owns the devices
Location	`loc_`	The property: address, timezone and currency
Tariff	`trf_`	An import or export tariff connected at a location
Device	`dev_`	A battery, charger, vehicle, heat pump or inverter at a location
Connect session	`cos_`	One run of the Connect flow for a device
VPP program	`vpr_`	A program a VPP operator offers to your devices
VPP enrollment	`enr_`	One device’s membership of one program
Consent record	`cns_`	One grant or revocation of consent for a device
VPP event	`vpe_`	A dispatch that draws on your fleet

Conventions

Topic	Rule
Versioning	Send `Flatpeak-Version: 2027-01-01.busbar`, or set the version on your account
Errors	Every non-2xx response carries `type`, `code` and `message`. The rate limit is 400 requests per second per endpoint
Pagination	Lists return `data` and `next_cursor`. Page forward with `cursor` and `limit`
Timezones	Timestamps are RFC 3339. Send any timezone and the response uses the same one
Events and webhooks	Every change is an event. List events, or receive them as signed webhooks

Naming

Both Flatpeak APIs follow the same rules.

Rule	Example
A resource is named after the thing itself, in the plural	`/devices`, `/meter-records`, `/connect-sessions`
`PATCH` edits fields. Anything that changes state is a `POST` to a verb	`POST /vpp-enrollments/{enrollment_id}/unenroll`
Created under the parent, retrieved by its own ID	`POST /devices/{device_id}/vpp-enrollments`, `GET /vpp-enrollments/{enrollment_id}`
Fields carry their unit	`power_kw`, `energy_kwh`, `backup_reserve_percent`, `interval_seconds`
Power and energy are signed: positive is import, negative is export	`power_kw: -4.3`
Timestamps start with `time_`. Windows are `start_time` and `end_time`	`time_created`, `time_updated`
Lists of IDs end in `_ids`	`device_ids`
`name` is your own label, and `display_name` is what your users see	A group’s `name`, a program’s `display_name`
Roles are named for what they do: `supplier` sells the energy, `operator` runs the program, `oem` makes the device	`supplier`, `operator_id`, `oem_id`
IDs carry a prefix that names the object	`dev_` device, `sup_` supplier, `opr_` operator, `enr_` enrollment
Enum values are upper case	`ALLOCATION_OPEN`