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

# Fleet API reference

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

The Fleet API is for energy suppliers and VPP operators. It enrolls your customers' devices in your programs, dispatches them one by one or as a group, and settles what they deliver. OEMs connect the devices through the Energy API.

## Make a request

The base URL is `https://fleet-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://fleet-api.flatpeak.com/auth/tokens \
  --user "$ACCOUNT_ID:$SECRET_KEY"
```

```bash 2. Call the API theme={"system"}
curl --request GET \
  --url https://fleet-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/fleet-api/reference/authentication.md) and [test mode](/docs/fleet-api/guides/platform/test-mode.md).

## Layout

| Group | Covers |
| :- | :- |
| Platform | Authentication, events, OEMs, devices, locations, tariffs |
| Enroll customers | Connect sessions, programs, enrollments |
| Dispatch devices | VPP events, plans, device and location telemetry |
| Organize the fleet | Groups, zones |
| Settle and reward | Exports, rewards |

Start with the [quickstart](/docs/fleet-api/guides/quickstart.md).

## Object model

A device reaches you through an enrollment in one of your programs. A VPP event sets a power target for a group. A plan runs one device on a managed tariff.

```mermaid actions={false} theme={"system"}
classDiagram
direction LR
    class Location
    class Device
    class Program
    class Enrollment
    class Group
    class VppEvent
    class Plan

    Location "1" o-- "n" Device
    Program "1" o-- "n" Enrollment
    Device "1" o-- "n" Enrollment
    Group "n" o-- "n" Device
    VppEvent "n" --> "1" Group : targets
    Device "1" o-- "n" Plan

    click Location href "/fleet-api/reference/locations/retrieve"
    click Device href "/fleet-api/reference/devices/retrieve"
    click Program href "/fleet-api/reference/vpp-programs/retrieve"
    click Enrollment href "/fleet-api/reference/vpp-enrollments/retrieve"
    click Group href "/fleet-api/reference/groups/retrieve"
    click VppEvent href "/fleet-api/reference/vpp-events/retrieve"
    click Plan href "/fleet-api/reference/plans/retrieve"
```

Click an object for its reference.

| Object | ID prefix | What it is |
| :- | :- | :- |
| OEM | `oem_` | A company whose devices you can reach |
| Device | `dev_` | A device connected to your account |
| Location | `loc_` | The property a device sits behind |
| Tariff | `trf_` | An import or export tariff at a location or for one device |
| Program | `vpr_` | A VPP program you offer |
| Enrollment | `enr_` | One device's membership of one program |
| VPP event | `vpe_` | A power target for a group |
| Plan | `pln_` | A schedule for one device on a managed tariff |
| Group | `grp_` | A named set of devices, by list or by filter |
| Zone | `zon_` | A network area, by country, states, postal codes or geometry |
| Reward | `rwd_` | A ledger entry for what one device delivered |
| Export | `exp_` | A file of settlement evidence, consent records or enrollments |
| Consent record | `cns_` | One grant or revocation of consent for a device |

## Conventions

| Topic | Rule |
| :- | :- |
| [Versioning](/docs/fleet-api/guides/platform/versioning.md) | Send `Flatpeak-Version: 2027-01-01.busbar`, or set the version on your account |
| [Errors](/docs/fleet-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/fleet-api/guides/platform/pagination.md) | Lists return `data` and `next_cursor`. Page forward with `cursor` and `limit` |
| [Timezones](/docs/fleet-api/guides/platform/timezones.md) | Timestamps are RFC 3339. Send any timezone and the response uses the same one |
| [Events](/docs/fleet-api/guides/platform/events.md) and [webhooks](/docs/fleet-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}/plans`, `GET /plans/{plan_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` |
| An object your account created carries `account_id`. Objects that an OEM or Flatpeak created, such as devices, locations, enrollments and rewards, do not | `account_id` on a program, a group or a VPP event |
| `name` is your own label, and `display_name` is what your customers 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.