Fleet API reference

The Fleet API is for energy suppliers and VPP operators. It enrolls your customers’ devices in your programs, dispatches them one by one or as a group, and settles what they deliver. OEMs connect the devices through the Energy API.

Make a request

The base URL is https://fleet-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://fleet-api.flatpeak.com/auth/tokens \
  --user "$ACCOUNT_ID:$SECRET_KEY"

curl --request GET \
  --url https://fleet-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, OEMs, devices, locations, tariffs
Enroll customers	Connect sessions, programs, enrollments
Dispatch devices	VPP events, plans, device and location telemetry
Organize the fleet	Groups, zones
Settle and reward	Exports, rewards

Start with the quickstart.

Object model

A device reaches you through an enrollment in one of your programs. A VPP event sets a power target for a group. A plan runs one device on a managed tariff.

Click an object for its reference.

Object	ID prefix	What it is
OEM	`oem_`	A company whose devices you can reach
Device	`dev_`	A device connected to your account
Location	`loc_`	The property a device sits behind
Tariff	`trf_`	An import or export tariff at a location or for one device
Program	`vpr_`	A VPP program you offer
Enrollment	`enr_`	One device’s membership of one program
VPP event	`vpe_`	A power target for a group
Plan	`pln_`	A schedule for one device on a managed tariff
Group	`grp_`	A named set of devices, by list or by filter
Zone	`zon_`	A network area, by country, states, postal codes or geometry
Reward	`rwd_`	A ledger entry for what one device delivered
Export	`exp_`	A file of settlement evidence, consent records or enrollments
Consent record	`cns_`	One grant or revocation of consent for a device

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}/plans`, `GET /plans/{plan_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`
An object your account created carries `account_id`. Objects that an OEM or Flatpeak created, such as devices, locations, enrollments and rewards, do not	`account_id` on a program, a group or a VPP event
`name` is your own label, and `display_name` is what your customers 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`