Quickstart

Enroll a test device and commit it to a VPP event. You need a Console account with a trial: contact support to activate one.

Authenticate

Copy your Account ID and secret key from Console > API Keys. Use a test mode key, which starts with sk_test_. Base64 encode account_id:secret_key and call authentication.

curl --request POST \
  --url https://fleet-api.flatpeak.com/auth/tokens \
  --header 'Authorization: Basic <base64 encoded account_id:secret_key>'

{
  "bearer_token": "eyJhbGciOiJIUzI1NiIsInR5cC",
  "expires_in": 3600,
  "live_mode": false
}

The token lasts one hour, after which you request another.

Create a program

You see a device only through an enrollment in one of your programs, so start by creating a VPP program. Set listed to false: an unlisted program is offered only from your app and needs no OEM approval.

Request example

curl --request POST \
  --url https://fleet-api.flatpeak.com/vpp-programs \
  --header 'Authorization: Bearer <bearer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "display_name": "Quickstart program",
  "listed": false,
  "currency_code": "GBP",
  "estimate": { "amount": 120, "period": "YEAR" },
  "terms": { "rewards": [{ "basis": "DELIVERED_KWH", "rate": 0.25 }] },
  "enrollment": { "dispatch_test_required": false }
}'

The program starts in DRAFT. Set status to LIVE with update a VPP program; an unlisted program goes live at once. Keep its id for the next step.

Create a Connect session

You do not create devices: the customer signs in to their OEM account in Connect, and the device appears in the API. Create a Connect session with:

Field	Value
`oem_id`	The OEM the customer signs in with, from list all OEMs. Use `oem_6a3a8dada72cd0a249ff9528` to simulate an OEM and a device
`program_id`	The `id` of your program
`callback_url`	Where the customer returns. Use `myapp://flatpeak/complete`

curl --request POST \
  --url https://fleet-api.flatpeak.com/connect-sessions \
  --header 'Authorization: Bearer <bearer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "oem_id": "oem_6a3a8dada72cd0a249ff9528",
  "program_id": "vpr_5c8d1f2a7b3e4d6c9a0f1b2c",
  "callback_url": "myapp://flatpeak/complete"
}'

{
  "id": "cos_6a3196d6e61a44f33f7307ed",
  "object": "connect_session",
  "live_mode": false,
  "oem_id": "oem_6a3a8dada72cd0a249ff9528",
  "program_id": "vpr_5c8d1f2a7b3e4d6c9a0f1b2c",
  "device_id": null,
  "target_url": "https://universal.flatpeak.com",
  "callback_url": "myapp://flatpeak/complete",
  "time_created": "2026-07-08T18:37:27Z",
  "time_expiry": "2026-07-10T18:37:27Z",
  "account_id": "acc_6a5e504c3b98d0d6739b5f72"
}

The session expires 48 hours after creation.

Launch Connect

Open https://universal.flatpeak.com with the session ID as the connect_session query parameter:

https://universal.flatpeak.com/?connect_session=cos_6a3196d6e61a44f33f7307ed

The customer signs in with their OEM account, grants the TELEMETRY, CONTROL, LOCATION and SETTINGS scopes, and returns to your callback_url. The OEM app opens if installed, otherwise the OEM’s web portal.

Flatpeak Connect flow — Left and right: your app. Middle: the OEM app or web portal.

Handle the callback

The customer lands on your callback_url with the session ID in the connect_session query parameter. Retrieve the Connect session and read device_id, which is null if the customer left without connecting a device.

Retrieve the device

Call retrieve a device with that device_id.

curl --request GET \
  --url https://fleet-api.flatpeak.com/devices/dev_63a6087272941ef077a8fd3e \
  --header 'Authorization: Bearer <bearer_token>'

{
  "id": "dev_63a6087272941ef077a8fd3e",
  "object": "device",
  "live_mode": false,
  "device_type": "BATTERY_STORAGE",
  "oem_id": "oem_6a3a8dada72cd0a249ff9528",
  "location_id": "loc_641b90b758fb8e6293716e40",
  "consent_scopes": ["TELEMETRY", "CONTROL", "LOCATION", "SETTINGS"],
  "dispatch_limits": {
    "max_import_power_kw": 8.4,
    "max_export_power_kw": 8.4,
    "storage_capacity_kwh": 14.2,
    "pv_peak_power_kw": null
  }
}

enrollment_state on the enrollment says whether you can dispatch the device. Change it with the enrollment actions.

Connect a tariff

A device cannot enroll until its location has an IMPORT and an EXPORT COMMODITY tariff. Until then the enrollment waits in PENDING, at step AWAITING_TARIFF. See Tariffs.

If your account supplies energy, create both tariffs at the device’s location_id with create a tariff.
If it does not, the customer connects their own tariff in Connect and the step clears.

Request example (account that supplies energy)

curl --request POST \
  --url https://fleet-api.flatpeak.com/tariffs \
  --header 'Authorization: Bearer <bearer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_id": "loc_641b90b758fb8e6293716e40",
  "tariff_type": "COMMODITY",
  "direction": "IMPORT",
  "display_name": "Two-rate home tariff",
  "contract_start_date": "2026-07-01T00:00:00Z",
  "contract_end_date": "2027-06-30T23:59:59Z",
  "schedule": [
    {
      "months": ["All"],
      "days_and_hours": [
        {
          "days": ["All"],
          "hours": [
            {
              "valid_from": "00:00:00",
              "valid_to": "07:00:00",
              "rate": { "vat_included": "YES", "vat_percentage": 0.05, "variables": { "price": 0.12 }, "expression": "$price" }
            },
            {
              "valid_from": "07:00:00",
              "valid_to": "00:00:00",
              "rate": { "vat_included": "YES", "vat_percentage": 0.05, "variables": { "price": 0.29 }, "expression": "$price" }
            }
          ]
        }
      ]
    }
  ]
}'

Repeat with "direction": "EXPORT". With no dispatch test and no approval required, the enrollment is then ACTIVE.

Retrieve device state

Call retrieve a device state.

curl --request GET \
  --url https://fleet-api.flatpeak.com/devices/dev_63a6087272941ef077a8fd3e/state \
  --header 'Authorization: Bearer <bearer_token>'

{
  "object": "device_state",
  "device_id": "dev_63a6087272941ef077a8fd3e",
  "oem_id": "oem_6a3a8dada72cd0a249ff9528",
  "time_recorded": "2026-07-08T19:30:00Z",
  "available": true,
  "power_kw": -3.4,
  "state_of_charge_percent": 34.2,
  "available_import_energy_kwh": 5.9,
  "available_export_energy_kwh": 5.5
}

Negative power_kw means the device is discharging. available_export_energy_kwh is already net of the customer’s backup reserve, which is never dispatched.

Create a VPP event

A VPP event commits a group of devices to a power target per interval. First create a group that holds the device:

curl --request POST \
  --url https://fleet-api.flatpeak.com/groups \
  --header 'Authorization: Bearer <bearer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Quickstart",
  "device_ids": ["dev_63a6087272941ef077a8fd3e"]
}'

{
  "id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a",
  "object": "group",
  "live_mode": false,
  "name": "Quickstart",
  "filter": null,
  "device_count": 1
}

Then create a VPP event for the group, to charge the device at 4.3 kW overnight. power_kw is positive for import and negative for export, up to max_import_power_kw and max_export_power_kw in dispatch_limits.

curl --request POST \
  --url https://fleet-api.flatpeak.com/vpp-events \
  --header 'Authorization: Bearer <bearer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "event_type": "TEST",
  "group_id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a",
  "intervals": [
    { "start_time": "2026-07-09T02:00:00Z", "end_time": "2026-07-09T04:30:00Z", "power_kw": 4.3 }
  ]
}'

{
  "id": "vpe_7d2a4c6e9b1f3a5c8e0d2f4b",
  "object": "vpp_event",
  "live_mode": false,
  "event_type": "TEST",
  "status": "ALLOCATION_OPEN",
  "group_id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a",
  "device_count": 1,
  "start_time": "2026-07-09T02:00:00Z",
  "end_time": "2026-07-09T04:30:00Z",
  "time_created": "2026-07-08T19:45:22Z"
}

Flatpeak bounds the target to the device’s limits and passes it to the OEM as a binding instruction, which the OEM confirms. TEST events do not affect settlement.

Check delivery

After the event, call list device meter records. At 4.3 kW, each half hour records about 2.15 kWh of import.

curl --request GET \
  --url 'https://fleet-api.flatpeak.com/devices/dev_63a6087272941ef077a8fd3e/meter-records?start_time=2026-07-09T02:00:00Z&end_time=2026-07-09T04:30:00Z&aggregate_by=HALF_HOUR&order_by=OLDEST&limit=100' \
  --header 'Authorization: Bearer <bearer_token>'

{
  "object": "meter_records",
  "device_id": "dev_63a6087272941ef077a8fd3e",
  "oem_id": "oem_6a3a8dada72cd0a249ff9528",
  "count": 5,
  "next_cursor": null,
  "data": [
    {
      "start_time": "2026-07-09T02:00:00Z",
      "end_time": "2026-07-09T02:30:00Z",
      "energy_kwh": 2.15
    },
    {
      "start_time": "2026-07-09T02:30:00Z",
      "end_time": "2026-07-09T03:00:00Z",
      "energy_kwh": 2.15
    }
  ]
}

The dispatch timeline shows what the device did per interval, with the VPP event behind it.

Get started

Enroll customers

Devices

Tariffs

Dispatch devices

Settle and reward

Platform