> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a VPP event > Creates a VPP event for a group and allocates its target across the group's devices. The event takes every device that is in the group at creation; each is listed in the event's [devices](/fleet-api/reference/vpp-events/list-devices), including those given no share. A duplicate `reference_id` returns `409` `reference_id_exists`. ## OpenAPI ````yaml fleet-api/reference/flatpeak-api-spec-fleet.json POST /vpp-events openapi: 3.0.3 info: description: >- The Flatpeak Fleet API. VPP operators use it to enroll, dispatch and settle OEM device fleets. ## Authentication Exchange your `account_id` and `secret_key` for a bearer token at `POST /auth/tokens` with basic auth. Send it as `Authorization: Bearer ` on every request. ## Base URL `https://fleet-api.flatpeak.com` ## Pagination Lists return `data`, `next_cursor` and `url`. Pass `next_cursor` as `cursor` until it is `null`. A cursor is opaque and bound to the endpoint and query parameters that issued it. ## Errors Every non-2xx response carries `object`, `type`, `code` and `message`. Branch on `code`. ## Money and energy Money is a decimal number paired with a `currency_code` (ISO 4217). Power is in kW and energy in kWh. Positive is import, negative is export. ## Live and test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Fleet 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://fleet-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 for onboarding customers through your own app. - name: OEMs description: List and retrieve the OEMs whose devices your fleet can reach. - name: Devices description: >- Retrieve, list and update the devices connected to your account, and read their consent history and shared settings. - name: Locations description: >- Read the location a device sits behind: its timezone, currency, metering and your devices there. - name: Dispatch description: Submit plans to devices on managed tariffs and read the dispatch timeline. - name: Telemetry description: Read device state, device meter records and location meter records. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Events description: Retrieve and list account events. - name: VPP Programs description: >- Define and manage VPP programs: the commercial terms devices enroll under, and their live state. - name: Groups description: >- Named collections of devices for bulk dispatch and aggregated reads. OEMs see them read-only as [groups](/energy-api/reference/groups/list) on the Energy API. - name: Zones description: >- Network areas resolved to devices by Flatpeak, for locational eligibility and grouping without handling addresses. - name: Exports description: >- Package settlement evidence, consent records and enrollment registers as downloadable files. - name: Rewards description: >- The reward ledger: entries accrue from delivery, you approve them, pay the customers and mark them paid. - name: VPP Enrollments description: Track and act on device enrollments across your programs. - name: VPP Events description: >- Commit market activations: create an event for a group, then read its state and its devices' results. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /vpp-events: parameters: [] post: tags: - VPP Events summary: Create a VPP event description: >- Creates a VPP event for a group and allocates its target across the group's devices. The event takes every device that is in the group at creation; each is listed in the event's [devices](/fleet-api/reference/vpp-events/list-devices), including those given no share. A duplicate `reference_id` returns `409` `reference_id_exists`. operationId: create-a-vpp-event parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VppEventCreate' responses: '201': $ref: '#/components/responses/VppEventCreated' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '409': $ref: '#/components/responses/409' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: schemas: VppEventCreate: type: object title: VppEventCreate description: >- Creates a VPP event for one group. To dispatch one program, use a group that filters on `program_id`; to dispatch chosen devices, use a group with an explicit device list. additionalProperties: false required: - group_id - intervals properties: reference_id: type: string description: >- Your external reference for the activation. Unique per account; a duplicate returns `409`. nullable: true example: NG-DFS-2026-08-04-EV17 event_type: type: string enum: - ECONOMIC - TEST description: >- `ECONOMIC`: market-driven, the default. `TEST`: exercises the dispatch chain without settlement. example: ECONOMIC group_id: type: string description: >- The group to dispatch. The event takes every device that is in the group now; later changes to the group do not change the event. example: grp_2f6a9c1d8e3b5a7c4d0e9f1a intervals: type: array minItems: 1 description: >- Ordered, non-overlapping intervals, each with a signed `power_kw` target. A flat event is one interval. Allocation runs per interval: `power_kw` is a total for the group, split across its devices. items: type: object properties: start_time: type: string format: date-time description: Interval start, in UTC. example: '2026-08-04T20:14:00Z' end_time: type: string format: date-time description: Interval end, in UTC. example: '2026-08-04T21:00:00Z' power_kw: type: number description: >- Requested power over this interval, in kilowatts, signed: positive for import, negative for export. example: -4800 required: - start_time - end_time - power_kw VppEvent: type: object title: VppEvent description: >- One market activation: a power target per interval for one group. The event takes every device in the group at creation and records each one in its device list. Plans are separate: they run devices under a managed tariff. additionalProperties: false required: - id - object - live_mode - reference_id - event_type - group_id - intervals - start_time - end_time - status - time_allocation_locks - device_count - delivery - time_created - time_updated - account_id properties: id: type: string description: Flatpeak VPP event ID. example: vpe_7d2a4c6e9b1f3a5c8e0d2f4b object: type: string description: Object type, `vpp_event`. example: vpp_event enum: - vpp_event live_mode: type: boolean description: '`true` for live data, `false` for test data.' example: true reference_id: type: string description: >- Your reference for the activation, for example the market operator's. Unique per account: a second event with the same `reference_id` returns `409`, so creation is safe to retry. nullable: true example: NG-DFS-2026-08-04-EV17 event_type: type: string enum: - ECONOMIC - TEST description: >- `ECONOMIC`: market-driven, the default. `TEST`: exercises the dispatch chain without settlement. example: ECONOMIC group_id: type: string description: >- The group the event dispatches. The event took every device that was in the group when it was created; later changes to the group do not change the event. example: grp_2f6a9c1d8e3b5a7c4d0e9f1a intervals: type: array minItems: 1 description: >- Ordered, non-overlapping intervals, each with a signed `power_kw` target for the group. A flat event is one interval. items: type: object properties: start_time: type: string format: date-time description: Interval start, in UTC. example: '2026-08-04T20:14:00Z' end_time: type: string format: date-time description: Interval end, in UTC. example: '2026-08-04T21:00:00Z' power_kw: type: number description: >- Requested power over this interval, in kilowatts, signed: positive for import, negative for export. example: -4800 required: - start_time - end_time - power_kw start_time: type: string description: 'Event envelope start: the first interval''s start, in UTC. Read only.' format: date-time example: '2026-08-04T20:14:00Z' readOnly: true end_time: type: string description: 'Event envelope end: the last interval''s end, in UTC. Read only.' format: date-time example: '2026-08-04T22:00:00Z' readOnly: true status: type: string enum: - ALLOCATION_OPEN - LOCKED - ACTIVE - COMPLETE - CANCELED readOnly: true description: >- Lifecycle status, the same values the Energy API reports to OEMs. Changes fire `vpp_event.update`. | Value | Meaning | | :--- | :--- | | `ALLOCATION_OPEN` | Until `time_allocation_locks`. Device shares can still change | | `LOCKED` | Shares fixed and sent to the OEMs | | `ACTIVE` | During the window | | `COMPLETE` | After the window | | `CANCELED` | Called off by you | example: ALLOCATION_OPEN time_allocation_locks: type: string format: date-time readOnly: true description: >- Time after which the allocation is fixed, in UTC. Until then Flatpeak may rebalance shares. example: '2026-08-25T16:00:00Z' device_count: type: integer readOnly: true description: >- Devices the event took from the group when it was created. Each one is in the event's device list, whether or not it was given a share. example: 1930 delivery: type: object description: >- Requested, committed and delivered figures for the whole event: the sum across the event's devices. Kept current as meter records arrive. additionalProperties: false required: - requested_power_kw - requested_energy_kwh - committed_power_kw - committed_energy_kwh - delivered_power_kw - delivered_energy_kwh - fulfillment - status properties: requested_power_kw: type: number description: >- The event's target power, in kilowatts, signed: positive import, negative export. example: -4800 requested_energy_kwh: type: number description: >- Energy the target implies over the window, in kWh, signed like power. example: -8480 committed_power_kw: type: number description: >- Power the fleet accepted after Flatpeak bounded each device, in kilowatts, signed like the target. example: -4620 committed_energy_kwh: type: number description: >- Energy the fleet's commitments imply over the window, in kWh, signed like power. example: -8160 delivered_power_kw: type: number description: >- Mean power delivered over the window so far, in kilowatts, signed like power. `null` while unreported. nullable: true example: -4390 delivered_energy_kwh: type: number description: >- Energy delivered within the window so far, in kWh, signed like power. `null` while unreported. nullable: true example: -7755 fulfillment: type: number description: >- Share of the committed energy delivered, from 0 to 1, energy weighted. `null` while no meter records cover the window. minimum: 0 maximum: 1 nullable: true example: 0.95 status: type: string enum: - FULL - PARTIAL - ZERO - UNREPORTED nullable: true description: >- Delivery outcome at fleet level. `null` before the window starts. | Value | Meaning | | :--- | :--- | | `FULL` | Fulfillment 1 | | `PARTIAL` | Fulfillment between 0 and 1 | | `ZERO` | Meter records cover the window, nothing delivered | | `UNREPORTED` | No meter records cover the window | example: PARTIAL readOnly: true time_created: type: string description: Time when the object was created, in UTC. format: date-time example: '2026-08-03T11:20:00Z' time_updated: type: string format: date-time description: Time when the event was created or last updated, in UTC. example: '2026-08-25T14:00:12Z' account_id: type: string description: Flatpeak Account ID of the operator that owns the VPP event. example: acc_63e2f1b9a4c8d05f7e3a9b1c 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: access_denied 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' 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' '409': description: >- 409 Conflict: the resource conflicts with existing data, for example a duplicate reference. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- 422 Unprocessable Entity: the request is well-formed but cannot be processed, for example missing required data. 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' VppEventCreated: description: VPP event response. content: application/json: schema: $ref: '#/components/schemas/VppEvent' example: id: vpe_7d2a4c6e9b1f3a5c8e0d2f4b object: vpp_event live_mode: true reference_id: NG-DFS-2026-08-04-EV17 event_type: ECONOMIC group_id: grp_2f6a9c1d8e3b5a7c4d0e9f1a intervals: - start_time: '2026-08-04T20:00:00Z' end_time: '2026-08-04T22:00:00Z' power_kw: -4800 start_time: '2026-08-04T20:00:00Z' end_time: '2026-08-04T22:00:00Z' status: ALLOCATION_OPEN time_allocation_locks: '2026-08-04T18:00:00Z' device_count: 1930 delivery: requested_power_kw: -4800 requested_energy_kwh: -9600 committed_power_kw: -4620 committed_energy_kwh: -9240 delivered_power_kw: null delivered_energy_kwh: null fulfillment: null status: null time_created: '2026-08-03T11:20:00Z' time_updated: '2026-08-03T11:20:00Z' account_id: acc_63e2f1b9a4c8d05f7e3a9b1c securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authenticate with the `bearer_token` obtained from the [authentication](/fleet-api/reference/authentication) endpoint. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.