Create a device

curl --request POST \
  --url https://energy-api.flatpeak.com/devices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference_id": "DEV3456789012",
  "location_id": "loc_641b90b758fb8e6293716e40",
  "device_type": "HEAT_PUMP"
}
'

{
  "id": "dev_63a6087272941ef077a8fd3e",
  "object": "device",
  "reference_id": "DEV1234567890",
  "live_mode": true,
  "location_id": "loc_641b90b758fb8e6293716e40",
  "capabilities": {
    "pv": {
      "peak_power_kw": 6.2,
      "azimuth": 180,
      "tilt": 23,
      "terrain_shading": false,
      "forecasts_enabled": true
    }
  },
  "device_type": "PV_SYSTEM",
  "time_last_seen": "2026-07-08T19:30:00Z",
  "time_created": "2026-01-20T09:30:00Z",
  "account_id": "acc_661677911f2197045e6cf1b1"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

POST

devices

curl --request POST \
  --url https://energy-api.flatpeak.com/devices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference_id": "DEV3456789012",
  "location_id": "loc_641b90b758fb8e6293716e40",
  "device_type": "HEAT_PUMP"
}
'

{
  "id": "dev_63a6087272941ef077a8fd3e",
  "object": "device",
  "reference_id": "DEV1234567890",
  "live_mode": true,
  "location_id": "loc_641b90b758fb8e6293716e40",
  "capabilities": {
    "pv": {
      "peak_power_kw": 6.2,
      "azimuth": 180,
      "tilt": 23,
      "terrain_shading": false,
      "forecasts_enabled": true
    }
  },
  "device_type": "PV_SYSTEM",
  "time_last_seen": "2026-07-08T19:30:00Z",
  "time_created": "2026-01-20T09:30:00Z",
  "account_id": "acc_661677911f2197045e6cf1b1"
}

{
  "object": "error",
  "type": "invalid_request",
  "code": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "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": "not_found",
  "message": "The requested resource could not be found.",
  "context": "api.price_get",
  "live_mode": true,
  "time_created": "2026-01-01T00:00:00Z"
}

View device Properties diagram (important!)

Authorizations

Authorization

string

header

required

Bearer token obtained from POST /auth/tokens.

Body

application/json

Creates a device.

location_id

string

required

Flatpeak Location ID.

Example:

"loc_641b90b758fb8e6293716e40"

device_type

enum<string>

required

What the device is, as your users would name it. Set when you create the device. Connect uses it for the noun your users see: BATTERY_STORAGE reads "your battery".

Available options:

BATTERY_STORAGE,

ELECTRIC_VEHICLE,

EV_CHARGER,

AIR_CONDITIONER,

HEAT_PUMP,

WATER_HEATER,

PV_SYSTEM,

POWER_GENERATOR,

OTHER

Example:

"BATTERY_STORAGE"

reference_id

string

Your own reference, for example an ID from your system.

Example:

"DEV1234567890"

capabilities

DeviceCapabilities · object

What the device can do, by subsystem. For tariffs, only a pv block is used: optimizations take the solar part of each window from it.

Show child attributes

Response

Success: the device resource.

A device: an energy asset at a location, with its hardware identity, capabilities, consents, telemetry duties and, through its own methods, state and settings.

string

required

read-only

Flatpeak Device ID.

Pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$

Example:

"dev_63a6087272941ef077a8fd3e"

object

enum<string>

default:device

required

read-only

Object type.

Available options:

device

Example:

"device"

reference_id

string | null

required

Your own reference, for example an ID from your system. null when not set.

Example:

"DEV1234567890"

live_mode

boolean

required

true for live data, false for test data.

location_id

string

required

Flatpeak Location ID of the device's current location. Moves are appended to the device's location history; past records keep the location current at the time.

Example:

"loc_641b90b758fb8e6293716e40"

capabilities

DeviceCapabilities · object

required

Technical envelope of the device, grouped by subsystem. Include only the subsystems the device has: a battery-only unit omits pv, a solar-only unit omits battery.

Show child attributes

device_type

enum<string>

required

What the device is, as your users would name it. Set when you create the device. Connect uses it for the noun your users see: BATTERY_STORAGE reads "your battery".

Available options:

BATTERY_STORAGE,

ELECTRIC_VEHICLE,

EV_CHARGER,

AIR_CONDITIONER,

HEAT_PUMP,

WATER_HEATER,

PV_SYSTEM,

POWER_GENERATOR,

OTHER

Example:

"BATTERY_STORAGE"

time_last_seen

string<date-time> | null

required

Time when Flatpeak last heard from the device, through an API call or telemetry, in UTC. null until first contact.

Example:

"2026-03-22T11:12:21Z"

time_created

string<date-time>

required

Time when the object was created, in UTC.

Example:

"2026-01-24T14:15:22Z"

account_id

string

required

read-only

Flatpeak Account ID.

Pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$

Example:

"acc_661677911f2197045e6cf1b1"

Platform

Tariffs

VPP

Authorizations

Body

Response