> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # List VPP programs > Returns the VPP programs available to a device, with its enrollment status and estimated earnings for each. Only programs Flatpeak has approved are listed. Enrollment happens through Connect. ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy.json GET /devices/{device_id}/vpp-programs openapi: 3.0.3 info: description: >- The Flatpeak Energy API connects energy hardware (batteries, EV chargers, vehicles, heat pumps, water heaters, solar and generators) to electricity prices, grid fees, and VPP programs. ## Create bearer token Obtain a bearer token from `POST /auth/tokens` using your `account_id` and `secret_key` via basic auth, then send it as `Authorization: Bearer ` on every request. ## Base URL `https://energy-api.flatpeak.com` ## Pagination List endpoints return a `list` envelope with `data`, `next_cursor`, and `url`. Page forward by passing `next_cursor` as `cursor` on the next request, until it is `null`. Cursors are opaque and bound to the endpoint and query parameters that issued them. ## Errors Every non-2xx response uses a standard error envelope with `object`, `type`, `code`, and `message`. Codes are machine-readable and safe to branch on. ## Money Monetary values are decimal numbers and are always paired with a `currency_code` (ISO 4217). Energy is expressed in kilowatt hours (kWh). ## Live vs test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Energy API termsOfService: https://flatpeak.com/legal contact: name: Technical Support email: support@flatpeak.com url: https://flatpeak.com/contact license: name: Apache 2.0 url: https://flatpeak.com/legal servers: - url: https://energy-api.flatpeak.com security: - bearerAuth: [] tags: - name: Authentication description: >- Exchange your account credentials for a bearer token to authenticate API requests. - name: Connect description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection, VPP enrollment, and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). x-tariff-description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). - name: Users description: Create, retrieve, update, delete, and list users. - name: Locations description: Create, retrieve, update, delete, and list locations. - name: Devices description: >- Create, retrieve, update, delete and list devices; submit and retrieve their state; read and write their shared settings. - name: Meters description: Submit meter records and check batch status. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Prices description: Retrieve and audit calculated energy prices. - name: Costs description: Calculate the monetary cost of imported or exported energy. - name: Optimizations description: >- Rank the connected tariff to find the best times to consume or export energy, as inputs to your own scheduling. - name: Dispatch description: >- Fetch the VPP operator's instructions for a device, and confirm what the device will deliver. - name: Events description: Retrieve and list account events. - name: VPP Enrollments description: Create, retrieve and list VPP enrollments, and unenroll a device. - name: VPP Programs description: List VPP programs available to devices. - name: VPP Events description: >- VPP events committed by VPP operators, with your fleet's share and its per-device allocation. You can take over the allocation while it is open. - name: Operator groups description: >- Read-only views of the device groups VPP operators define. You see the groups that touch your fleet, and only your own devices in them. - name: Zones description: >- Network areas VPP operators define that touch your fleet. Read-only. You see only your own devices in them. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /devices/{device_id}/vpp-programs: parameters: - name: device_id in: path required: true schema: type: string example: dev_63a6087272941ef077a8fd3e description: Flatpeak Device ID. get: tags: - VPP Programs summary: List VPP programs description: >- Returns the VPP programs available to a device, with its enrollment status and estimated earnings for each. Only programs Flatpeak has approved are listed. Enrollment happens through Connect. operationId: list-vpp-programs parameters: - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' responses: '200': $ref: '#/components/responses/VppProgramList' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: parameters: cursor: name: cursor in: query required: false schema: type: string description: >- Pagination cursor. Pass `next_cursor` from the previous response unchanged; omit for the first page. A cursor used with different parameters returns `400 cursor_invalid`. limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 30 description: Maximum number of objects to return per page, default 30. Maximum 100. responses: '400': description: >- 400 Bad Request: the request was malformed or a required field is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '401 Unauthorized: authentication credentials are missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '404 Not Found: the requested resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '429 Too Many Requests: the rate limit has been exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- 500 Internal Server Error: an unexpected error occurred. Safe to retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- 503 Service Unavailable: the service is temporarily down for maintenance. Retry after the indicated delay. content: application/json: schema: $ref: '#/components/schemas/Error' VppProgramList: description: VPP program list response. content: application/json: schema: allOf: - $ref: '#/components/schemas/ListResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/VppProgram' description: The page of results. schemas: ListResponse: type: object description: Standard envelope for paginated list endpoints. required: - object - url - next_cursor - data properties: object: type: string enum: - list default: list description: Object type. url: type: string description: URL for this list. example: /users next_cursor: type: string nullable: true description: >- Opaque cursor for the next page. Pass it as `cursor` on the next request. `null` on the last page. Do not stop on a short or empty `data` array. example: djF8ZXZ0fGE5ZjN8NjYxNjc3ODdjMTY1MmIzZmJlYmE1ZjAx data: type: array items: {} description: The page of results. VppProgram: title: VppProgram type: object description: >- A VPP program available to a device, with the device's enrollment state and the estimate shown to the user. The same information Connect shows on the VPP Programs page. properties: id: type: string pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ example: vpr_6a1f8e375db9de605baadd46 description: Flatpeak VPP Program ID. object: type: string description: Object type, `vpp_program`. example: vpp_program enum: - vpp_program operator: type: object description: The VPP operator that runs the program. required: - id - display_name properties: id: type: string pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ example: opr_8587fa49c7e5297ccc6c57e5 description: Flatpeak ID of the VPP operator that runs the program. display_name: type: string example: Pick description: VPP operator display name. display_name: type: string example: Community Powershare description: VPP program display name. url: type: string example: https://pick.com/programs/community-powershare description: VPP program information URL. managed: type: boolean example: false description: >- `true` for a managed tariff: the VPP operator runs the device under this program with binding plans, and it replaces the user's tariff. The user signs up for it with the VPP operator: see [Programs](/energy-api/reference/connect/vpp/programs#managed-tariffs). currency_code: type: string example: USD description: >- Currency of every amount on the program, as an ISO 4217 code: `estimate.amount` and each `rate` in `terms.rewards`. pattern: ^[A-Z]{3}$ zone_id: type: string nullable: true readOnly: true description: >- Flatpeak Zone ID of the [zone](/energy-api/reference/zones/retrieve) the VPP operator restricted the program to. `null` when not restricted by area. example: null enrollment_state: type: string enum: - NOT_ENROLLED - PENDING - ACTIVE - SUSPENDED - LEAVING - ENDED - REJECTED example: NOT_ENROLLED description: >- The device's enrollment state for this program, or `NOT_ENROLLED` if it has never enrolled. estimate: type: object description: >- What the user is told to expect before they join. It is a projection and never binding. The copy follows `managed`: bill savings for a managed tariff ("Your bill drops by"), earnings otherwise ("You earn"). Present it as provided, and do not convert between periods. required: - amount - period properties: amount: type: number example: 612 description: >- Estimated amount for one `period`, in the program's `currency_code`, in large currency units: bill savings when `managed` is `true`, earnings otherwise. period: type: string enum: - YEAR - MONTH example: YEAR description: Period the estimate covers. Set per program by the VPP operator. dispatch_events_per_month: type: number minimum: 0 example: 15 description: Approximate number of VPP events per month the estimate assumes. terms: type: object description: >- What binds the user and the VPP operator once the user has joined: what the user is paid, whether they may skip events, and how long leaving takes. Show the rewards at enrollment. The enrollment keeps a copy of the `terms` it joined with. properties: rewards: type: array description: >- What the user is paid. Each `basis` appears at most once. Empty when the program pays no rewards, as a managed tariff may. The VPP operator pays the user, and Flatpeak keeps the ledger. example: - basis: FIXED rate: 15 period: QUARTER - basis: DELIVERED_KWH rate: 0.35 items: type: object required: - basis - rate properties: basis: type: string enum: - FIXED - EVENT - DELIVERED_KWH - COMMITTED_KWH example: DELIVERED_KWH description: >- What `rate` is paid for. | Value | `rate` is paid | | :--- | :--- | | `FIXED` | Once per `period`, by calendar period, pro-rated by the days the enrollment is `ACTIVE` | | `EVENT` | Per VPP event the device delivers in full | | `DELIVERED_KWH` | Per kWh delivered, from the device's meter records | | `COMMITTED_KWH` | Per kWh of the device's locked share of a VPP event, whatever the device then delivers. Nothing for a commitment the user opted out of | rate: type: number example: 0.35 description: >- Amount paid per unit of `basis`, in the program's `currency_code`, in large currency units. period: type: string enum: - MONTH - QUARTER - YEAR example: QUARTER description: >- Period a `FIXED` reward is paid for. Required when `basis` is `FIXED`, and not used otherwise. opt_out_policy: type: string enum: - ALLOWED - ALLOWED_BEFORE_LOCK - NOT_ALLOWED example: ALLOWED description: >- Whether users may skip individual VPP events. | Value | Meaning | | :--- | :--- | | `ALLOWED` | Default. Any scheduled or active VPP event. Skipped intervals are recorded as `OPTED_OUT`. | | `ALLOWED_BEFORE_LOCK` | Only until the allocation locks. | | `NOT_ALLOWED` | No per-event opt-out. Users can still unenroll. | notice_days: type: integer example: 30 description: >- Maximum number of days leaving may take once the user is enrolled. A request to leave that the VPP operator has not approved ends after this many days. Shown to the user before they join and when they leave. readOnly: true telemetry_requirements: type: object description: >- Telemetry the program requires from enrolled devices: sampling intervals for state and for the device's own meter records. The effective requirement appears per device on `telemetry`. required: - device_meter_interval_seconds properties: state_interval_seconds: type: integer minimum: 60 example: 300 description: >- Sampling interval for device state, in seconds, minimum 60. A sample is due when the interval has elapsed and a signal changed. While nothing changes, send a heartbeat every `telemetry.state_resend_interval_seconds`, which Flatpeak sets at three times this interval and never below 300 seconds. device_meter_interval_seconds: type: integer minimum: 60 example: 900 description: >- Sampling interval for the device's own meter records, in seconds: the device meters its flows at least this finely, down to 60. Every program sets it, because every program settles on device meter records. Delivery is separate. readOnly: true enrollment: type: object readOnly: true description: How a device gets in. properties: join_days: type: integer example: 10 description: >- Maximum number of days enrollment may take after the user asks to join. Shown to the user before they join. dispatch_test_required: type: boolean example: true description: >- `true` when enrollment includes a dispatch test: Flatpeak issues a `TEST` event, and the device must deliver it before approval. `false` when the step is skipped. required: - id - object - operator - display_name - enrollment_state x-examples: Example 1: operator: id: opr_8587fa49c7e5297ccc6c57e5 display_name: Pick id: vpr_6a1f8e375db9de605baadd46 object: vpp_program display_name: Community Powershare url: https://pick.com/programs/community-powershare managed: false currency_code: USD zone_id: null enrollment_state: NOT_ENROLLED estimate: amount: 612 period: YEAR dispatch_events_per_month: 15 terms: rewards: - basis: FIXED rate: 15 period: QUARTER - basis: DELIVERED_KWH rate: 0.35 opt_out_policy: ALLOWED notice_days: 30 telemetry_requirements: state_interval_seconds: 300 device_meter_interval_seconds: 900 enrollment: join_days: 10 dispatch_test_required: true Error: type: object description: Standard error envelope returned by every non-2xx response. required: - object - type - code - message properties: object: type: string enum: - error default: error description: Object type. type: type: string description: High-level error category. example: invalid_request code: type: string description: Machine-readable error code, safe to branch on. example: not_found message: type: string description: Human-readable description of the error. example: The requested resource could not be found. context: type: string description: Optional originating context, for example `api.price_get`. example: api.price_get live_mode: type: boolean description: Whether the error occurred against live or test data. time_created: type: string format: date-time description: Time the error was generated (RFC 3339). example: '2026-01-01T00:00:00Z' securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token obtained from POST /auth/tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.