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

# Key concepts

> The objects of the Fleet API and how they relate: devices, programs, enrollments, VPP events and plans.

You reach a device only through its enrollment in one of your programs.

## Object model

```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.

## Devices

A device is a battery, electric vehicle, EV charger or PV system, connected through its OEM. It has a `dev_` ID and a `device_type`, which names the whole product: an EV has a battery but is not `BATTERY_STORAGE`, and a vehicle charging through a connected charge point is dispatched as that `EV_CHARGER`.

`dispatch_limits` is the envelope Flatpeak checks every instruction against, computed at the device's connection point with inverter and connector limits included. It changes when the OEM adds or removes hardware, and `device.update` fires.

[List all OEMs](/docs/fleet-api/reference/oems/list.md) returns the OEMs on your account. To add one, [contact support](https://console.flatpeak.com/support).

## Telemetry and settings

* Device state is a snapshot of the live envelope at the grid connection point.
* Meter records are signed interval energy in kWh, used to settle delivery.
* Location meter records cover the whole site, where the OEM's hardware meters the grid connection point.
* Device settings are one record per device, which the customer owns and changes in your app or the OEM's.

[Devices](/docs/fleet-api/guides/devices.md) covers each.

## Import and export

The sign of every power and energy value gives the direction.

| Sign | Direction |
| :- | :- |
| Positive | From the grid into the device: charging |
| Negative | From the device to the grid: discharge or solar generation |

Prices are the exception: their sign is economic, and every tariff states the direction its prices apply to.

## VPP events and plans

| | [VPP event](/docs/fleet-api/guides/dispatch/vpp-events.md) | [Plan](/docs/fleet-api/guides/dispatch/plans.md) |
| :- | :- | :- |
| Use | Commit a group of devices to a power target | Run one device on a managed tariff |
| Scope | One group, named by `group_id`. The event takes the devices in it at creation | One device enrolled in a managed program |
| Shape | `intervals` with a signed `power_kw` for the group, which Flatpeak allocates across the devices | `intervals` with a signed `power_kw` for the device |

Both are binding on the OEM, and the OEM confirms the power the device will deliver.

Dispatch stays above `backup_reserve_percent`, and it does not export from a battery whose `export_rule` forbids it.

## Groups and zones

A [group](/docs/fleet-api/reference/groups/create.md) is a named set of devices, for bulk dispatch and aggregated reads. A [zone](/docs/fleet-api/reference/zones/create.md) is a network area that Flatpeak resolves, so you dispatch by location without sending addresses. A [capacity forecast](/docs/fleet-api/reference/groups/retrieve-capacity.md) gives a group's dispatchable power for a future window.

## Programs and enrollment

A [program](/docs/fleet-api/guides/programs.md) is your offer to customers. They enroll in your app, with `program_id` on the Connect session, or in their OEM's app once the program is `listed` and the OEM approves it. A `managed` program is a managed tariff: you supply the energy and run the device with plans. A customer who finds a listed managed tariff in their OEM's app signs up on your site, at the program's `enrollment.signup_url`, before they consent.

An enrollment has six [states](/docs/fleet-api/guides/programs/enrollment-states.md), from `PENDING` to `ACTIVE` to `ENDED`. A device needs a connected tariff to enroll.


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