Skip to main content
A group is a named set of devices that you dispatch together, and whose capacity you read as one. A zone is a network area that Flatpeak resolves to devices, so you never handle addresses.

Groups

Create a group with exactly one of:
Request body
A filter combines device_types, program_id, zone_id and a response-time range. The range matches the device’s median response_time.total_seconds, and a device with no measured response time is excluded when a bound is set. To dispatch a group, create a VPP event with its group_id. The event takes the members the group has at that moment. The group object carries device_count but not the device list: list all group devices returns the current members’ IDs, a page at a time, with the total in count. Plans, state and telemetry stay per device.

Zones

Create a zone with a definition. It always names a country_code, and narrows the country with at most one of these:
Request body
The country is required because a postal code or a state has no meaning without it: 2000 is central Sydney and also Antwerp. Postal codes match as full codes or prefixes: BS1 covers every postcode under it. Precision depends on the country: Flatpeak resolves membership against enrollment addresses and re-evaluates it continuously, and you receive only device IDs. Resolving a new zone, or one whose definition you changed, can take time: create and update return device_count as null, and the count appears once membership is resolved. zone.membership.update fires as devices join or leave. Update a zone to rename it or replace its area; groups and programs that reference the zone follow. List all zone devices returns the IDs of the devices in the zone, a page at a time, with the total in count. A zone is not dispatchable itself: create a group that filters on zone_id and dispatch the group. Use the same zone_id in a program’s eligibility to enroll only inside an area.

Capacity

The capacity forecast returns the power and energy a group can dispatch over a future window. Pass start_time, end_time (90 days at most) and a direction. Headroom comes from each member’s demand forecast, state of charge, limits, backup reserve, export rule, charge-from-grid setting and consents, and Flatpeak derates it by the device’s fulfillment history. confidence runs from 0 to 1 and drops further into the future and where telemetry has gaps.