Create a VPP event

curl --request POST \
  --url https://fleet-api.flatpeak.com/vpp-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "group_id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a",
  "intervals": [
    {
      "start_time": "2026-08-04T20:14:00Z",
      "end_time": "2026-08-04T21:00:00Z",
      "power_kw": -4800
    }
  ],
  "reference_id": "NG-DFS-2026-08-04-EV17",
  "event_type": "ECONOMIC"
}
'

import requests

url = "https://fleet-api.flatpeak.com/vpp-events"

payload = {
    "group_id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a",
    "intervals": [
        {
            "start_time": "2026-08-04T20:14:00Z",
            "end_time": "2026-08-04T21:00:00Z",
            "power_kw": -4800
        }
    ],
    "reference_id": "NG-DFS-2026-08-04-EV17",
    "event_type": "ECONOMIC"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    group_id: 'grp_2f6a9c1d8e3b5a7c4d0e9f1a',
    intervals: [
      {
        start_time: '2026-08-04T20:14:00Z',
        end_time: '2026-08-04T21:00:00Z',
        power_kw: -4800
      }
    ],
    reference_id: 'NG-DFS-2026-08-04-EV17',
    event_type: 'ECONOMIC'
  })
};

fetch('https://fleet-api.flatpeak.com/vpp-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://fleet-api.flatpeak.com/vpp-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'group_id' => 'grp_2f6a9c1d8e3b5a7c4d0e9f1a',
    'intervals' => [
        [
                'start_time' => '2026-08-04T20:14:00Z',
                'end_time' => '2026-08-04T21:00:00Z',
                'power_kw' => -4800
        ]
    ],
    'reference_id' => 'NG-DFS-2026-08-04-EV17',
    'event_type' => 'ECONOMIC'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://fleet-api.flatpeak.com/vpp-events"

	payload := strings.NewReader("{\n  \"group_id\": \"grp_2f6a9c1d8e3b5a7c4d0e9f1a\",\n  \"intervals\": [\n    {\n      \"start_time\": \"2026-08-04T20:14:00Z\",\n      \"end_time\": \"2026-08-04T21:00:00Z\",\n      \"power_kw\": -4800\n    }\n  ],\n  \"reference_id\": \"NG-DFS-2026-08-04-EV17\",\n  \"event_type\": \"ECONOMIC\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://fleet-api.flatpeak.com/vpp-events")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"group_id\": \"grp_2f6a9c1d8e3b5a7c4d0e9f1a\",\n  \"intervals\": [\n    {\n      \"start_time\": \"2026-08-04T20:14:00Z\",\n      \"end_time\": \"2026-08-04T21:00:00Z\",\n      \"power_kw\": -4800\n    }\n  ],\n  \"reference_id\": \"NG-DFS-2026-08-04-EV17\",\n  \"event_type\": \"ECONOMIC\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://fleet-api.flatpeak.com/vpp-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"group_id\": \"grp_2f6a9c1d8e3b5a7c4d0e9f1a\",\n  \"intervals\": [\n    {\n      \"start_time\": \"2026-08-04T20:14:00Z\",\n      \"end_time\": \"2026-08-04T21:00:00Z\",\n      \"power_kw\": -4800\n    }\n  ],\n  \"reference_id\": \"NG-DFS-2026-08-04-EV17\",\n  \"event_type\": \"ECONOMIC\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

POST

vpp-events

Create a VPP event

curl --request POST \
  --url https://fleet-api.flatpeak.com/vpp-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "group_id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a",
  "intervals": [
    {
      "start_time": "2026-08-04T20:14:00Z",
      "end_time": "2026-08-04T21:00:00Z",
      "power_kw": -4800
    }
  ],
  "reference_id": "NG-DFS-2026-08-04-EV17",
  "event_type": "ECONOMIC"
}
'

import requests

url = "https://fleet-api.flatpeak.com/vpp-events"

payload = {
    "group_id": "grp_2f6a9c1d8e3b5a7c4d0e9f1a",
    "intervals": [
        {
            "start_time": "2026-08-04T20:14:00Z",
            "end_time": "2026-08-04T21:00:00Z",
            "power_kw": -4800
        }
    ],
    "reference_id": "NG-DFS-2026-08-04-EV17",
    "event_type": "ECONOMIC"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    group_id: 'grp_2f6a9c1d8e3b5a7c4d0e9f1a',
    intervals: [
      {
        start_time: '2026-08-04T20:14:00Z',
        end_time: '2026-08-04T21:00:00Z',
        power_kw: -4800
      }
    ],
    reference_id: 'NG-DFS-2026-08-04-EV17',
    event_type: 'ECONOMIC'
  })
};

fetch('https://fleet-api.flatpeak.com/vpp-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://fleet-api.flatpeak.com/vpp-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'group_id' => 'grp_2f6a9c1d8e3b5a7c4d0e9f1a',
    'intervals' => [
        [
                'start_time' => '2026-08-04T20:14:00Z',
                'end_time' => '2026-08-04T21:00:00Z',
                'power_kw' => -4800
        ]
    ],
    'reference_id' => 'NG-DFS-2026-08-04-EV17',
    'event_type' => 'ECONOMIC'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://fleet-api.flatpeak.com/vpp-events"

	payload := strings.NewReader("{\n  \"group_id\": \"grp_2f6a9c1d8e3b5a7c4d0e9f1a\",\n  \"intervals\": [\n    {\n      \"start_time\": \"2026-08-04T20:14:00Z\",\n      \"end_time\": \"2026-08-04T21:00:00Z\",\n      \"power_kw\": -4800\n    }\n  ],\n  \"reference_id\": \"NG-DFS-2026-08-04-EV17\",\n  \"event_type\": \"ECONOMIC\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://fleet-api.flatpeak.com/vpp-events")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"group_id\": \"grp_2f6a9c1d8e3b5a7c4d0e9f1a\",\n  \"intervals\": [\n    {\n      \"start_time\": \"2026-08-04T20:14:00Z\",\n      \"end_time\": \"2026-08-04T21:00:00Z\",\n      \"power_kw\": -4800\n    }\n  ],\n  \"reference_id\": \"NG-DFS-2026-08-04-EV17\",\n  \"event_type\": \"ECONOMIC\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://fleet-api.flatpeak.com/vpp-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"group_id\": \"grp_2f6a9c1d8e3b5a7c4d0e9f1a\",\n  \"intervals\": [\n    {\n      \"start_time\": \"2026-08-04T20:14:00Z\",\n      \"end_time\": \"2026-08-04T21:00:00Z\",\n      \"power_kw\": -4800\n    }\n  ],\n  \"reference_id\": \"NG-DFS-2026-08-04-EV17\",\n  \"event_type\": \"ECONOMIC\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "access_denied",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

Authorizations

Authorization

string

header

required

Authenticate with the bearer_token obtained from the authentication endpoint.

Body

application/json

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.

group_id

string

required

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

object[]

required

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.

Minimum array length: 1

Show child attributes

reference_id

string | null

Your external reference for the activation. Unique per account; a duplicate returns 409.

Example:

"NG-DFS-2026-08-04-EV17"

event_type

enum<string>

ECONOMIC: market-driven, the default. TEST: exercises the dispatch chain without settlement.

Available options:

ECONOMIC,

TEST

Example:

"ECONOMIC"

Response

VPP event response.

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.

string

required

Flatpeak VPP event ID.

Example:

"vpe_7d2a4c6e9b1f3a5c8e0d2f4b"

object

enum<string>

required

Object type, vpp_event.

Available options:

vpp_event

Example:

"vpp_event"

live_mode

boolean

required

true for live data, false for test data.

Example:

true

reference_id

string | null

required

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.

Example:

"NG-DFS-2026-08-04-EV17"

event_type

enum<string>

required

ECONOMIC: market-driven, the default. TEST: exercises the dispatch chain without settlement.

Available options:

ECONOMIC,

TEST

Example:

"ECONOMIC"

group_id

string

required

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

object[]

required

Ordered, non-overlapping intervals, each with a signed power_kw target for the group. A flat event is one interval.

Minimum array length: 1

Show child attributes

start_time

string<date-time>

required

read-only

Event envelope start: the first interval's start, in UTC. Read only.

Example:

"2026-08-04T20:14:00Z"

end_time

string<date-time>

required

read-only

Event envelope end: the last interval's end, in UTC. Read only.

Example:

"2026-08-04T22:00:00Z"

status

enum<string>

required

read-only

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

Available options:

ALLOCATION_OPEN,

LOCKED,

ACTIVE,

COMPLETE,

CANCELED

Example:

"ALLOCATION_OPEN"

time_allocation_locks

string<date-time>

required

read-only

Time after which the allocation is fixed, in UTC. Until then Flatpeak may rebalance shares.

Example:

"2026-08-25T16:00:00Z"

device_count

integer

required

read-only

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

object

required

read-only

Requested, committed and delivered figures for the whole event: the sum across the event's devices. Kept current as meter records arrive.

Show child attributes

time_created

string<date-time>

required

Time when the object was created, in UTC.

Example:

"2026-08-03T11:20:00Z"

time_updated

string<date-time>

required

Time when the event was created or last updated, in UTC.

Example:

"2026-08-25T14:00:12Z"

account_id

string

required

Flatpeak Account ID of the operator that owns the VPP event.

Example:

"acc_63e2f1b9a4c8d05f7e3a9b1c"

Platform

Enroll customers

Dispatch devices

Organize the fleet

Settle and reward

Create a VPP event

Authorizations

Body

Response