> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Energy API reference

> Make a request, find your way around the reference, and the conventions every endpoint shares.

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.

```bash 1. Create a token theme={"system"}
curl --request POST \
  --url https://energy-api.flatpeak.com/auth/tokens \
  --user "$ACCOUNT_ID:$SECRET_KEY"
```

```bash 2. Call the API theme={"system"}
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](/docs/energy-api/reference/auth/tokens.md) and [test mode](/docs/energy-api/guides/platform/test-mode.md).

## 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](/docs/energy-api/guides/quickstart.md), then add VPP with the [VPP quickstart](/docs/energy-api/guides/vpp/quickstart.md).

## Specs

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

[What VPP adds](/docs/energy-api/reference/vpp-fields.md) 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.

```mermaid actions={false} theme={"system"}
classDiagram
direction LR
    class User
    class Location
    class Tariff
    class Device
    class VppEnrollment
    class VppProgram

    User "1" o-- "n" Location
    Location "1" o-- "n" Tariff
    Location "1" o-- "n" Device
    Device "1" o-- "0..1" VppEnrollment
    VppProgram "1" o-- "n" VppEnrollment
```

| 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](/docs/energy-api/guides/platform/versioning.md) | Send `Flatpeak-Version: 2027-01-01.busbar`, or set the version on your account |
| [Errors](/docs/energy-api/guides/platform/errors.md) | Every non-2xx response carries `type`, `code` and `message`. The rate limit is 400 requests per second per endpoint |
| [Pagination](/docs/energy-api/guides/platform/pagination.md) | Lists return `data` and `next_cursor`. Page forward with `cursor` and `limit` |
| [Timezones](/docs/energy-api/guides/platform/timezones.md) | Timestamps are RFC 3339. Send any timezone and the response uses the same one |
| [Events](/docs/energy-api/guides/platform/events.md) and [webhooks](/docs/energy-api/guides/platform/webhooks.md) | 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` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.