Groups

Groups are the primary way to organize addresses and operate at portfolio scale. Access to almost all address- and device-scoped data flows through group assignment.

Base path: /api/v2/groups

What we provide

Method	Path	Purpose
`GET`	`/groups`	List groups assigned to the authenticated user (paginated)
`GET`	`/groups/:group_uuid/addresses`	List addresses in a group (paginated); may include active Sparky/Flint identifiers when present
`POST`	`/groups/:group_uuid/addresses/:address_uuid`	Add or reactivate an address in a curtailment pool
`DELETE`	`/groups/:group_uuid/addresses/:address_uuid`	Remove an address from a curtailment pool
`GET`	`/groups/:group_uuid/flex/schedules`	List group flex schedules
`GET`	`/groups/:group_uuid/flex/schedules/:schedule_uuid`	Get one flex schedule
`POST`	`/groups/:group_uuid/flex/schedules`	Create a flex schedule
`DELETE`	`/groups/:group_uuid/flex/schedules/:schedule_uuid`	Delete a flex schedule
`GET`	`/groups/:group_uuid/flex/aggregation`	Flex energy aggregates over a time range
`GET`	`/groups/:group_uuid/flex/aggregates/latest`	Latest flex aggregate snapshot

Schedule details are documented under Schedules.

Group kinds

Kind	Role
`PARTNER`	Ownership / access anchor. Membership via this API is read-oriented.
`CURTAILMENT_POOL`	Operational pool. Authorized callers can add and remove addresses here.

An address may belong to at most one active curtailment pool at a time. PARTNER group membership and pool membership are separate links.

Group list payload

Each group entry typically includes:

uuid, key, name
groupKind (PARTNER or CURTAILMENT_POOL)
Assignment fields such as assignedAt and isActive
Lifecycle timestamps

Pool membership mutations

POST / DELETE on /:group_uuid/addresses/:address_uuid manage curtailment-pool membership.

Mutation responses are compact acknowledgements, not full address listings:

{
  "groupUuid": "...",
  "groupKey": "...",
  "addressUuid": "...",
  "action": "added",
  "modifiedAt": "2026-07-06T12:00:00.000+00:00"
}

`action`	Meaning
`added`	New active membership created (`201`)
`reactivated`	Previously disconnected membership restored (`200`)
`unchanged`	Already an active member; safe idempotent retry (`200`)
`removed`	Active membership soft-disconnected (`200`)

Use GET /groups/:group_uuid/addresses when you need the full address set after a change.

Authorization rules for membership writes

A successful pool mutation requires all of:

Target group kind is CURTAILMENT_POOL.
Caller has access to that pool group.
Address is owned through an accessible PARTNER group.
For moves between pools: remove from the current pool first, then add to the new pool.

Guidance

Start every session by listing accessible groups.
Keep PARTNER ownership groups and curtailment pools as separate concepts in your data model.
Treat membership POST as idempotent; branch on action, not only HTTP status.
Expect a short propagation delay between a successful membership change and downstream steering/aggregation behaviour.