---
updatedAt: 2026-09-09T17:08:49.000Z
---

Fetch the complete documentation index at: https://docs.developer.chargee.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# 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](./schedules.md).

## 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:

```json
{
  "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:

1. Target group kind is `CURTAILMENT_POOL`.
2. Caller has access to that pool group.
3. Address is owned through an accessible `PARTNER` group.
4. 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.