SiteConfiguration

device_list object[]required

Array [

oneOf

AcChargingPole3Phase

nameName (string)required

The name of the device itself. This value will be used as the asset ID in the rest of the API.

collectorCollector (string)required

The name of the collector to which this device is connected.

ingress_validation object

Overrides the site-level ingress validation config for this asset. When set, controls how often measurements are expected during active and inactive transactions. When null, the site-level configuration is used.

anyOf

AssetIngressValidationConfig

with_transaction_expected_measurement_intervalstring<duration>

Expected measurement interval for the asset while it has an active transaction. Measurements arriving less frequently than this are flagged as stale by ingress validation. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so this value should not exceed 5 minutes for assets that participate in the uncontrollable-load computation.

without_transaction_expected_measurement_interval object

Expected measurement interval for the asset when no transaction is active. When null, the asset is always considered valid while idle. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so if this asset contributes to the uncontrollable-load computation it should still report at least every 5 minutes.

anyOf

string

string

null

null

null

null

typeType (string)

Constant value: charging_pole_3phase

Default value: charging_pole_3phase

line_currentLine Current (integer)required

The line current in Ampere.

pin_to_phase_mapping objectrequired

Defines how charging pole pins map to the collectors' phases. For more information see the 'Key Concepts - Site configuration' section in the documentation.

pin_liststring[]required

Possible values: [pin1, pin2, pin3]

phase_liststring[]required

Possible values: [L1, L2, L3]

DcChargingPole

phase_permutations object

Specify the phase mapping between this asset (child) and its parent collector (parent). Leave unset when the wiring is unknown; phase-aware control (use_topology) requires every asset's mapping to be declared, so a single unset mapping makes the controller fall back to the worst case.

anyOf

PhasePermutation

parentstring[]required

Possible values: [L1, L2, L3]

childstring[]required

Possible values: [L1, L2, L3]

null

null

nameName (string)required

The name of the device itself. This value will be used as the asset ID in the rest of the API.

collectorCollector (string)required

The name of the collector to which this device is connected.

ingress_validation object

Overrides the site-level ingress validation config for this asset. When set, controls how often measurements are expected during active and inactive transactions. When null, the site-level configuration is used.

anyOf

AssetIngressValidationConfig

with_transaction_expected_measurement_intervalstring<duration>

Expected measurement interval for the asset while it has an active transaction. Measurements arriving less frequently than this are flagged as stale by ingress validation. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so this value should not exceed 5 minutes for assets that participate in the uncontrollable-load computation.

without_transaction_expected_measurement_interval object

Expected measurement interval for the asset when no transaction is active. When null, the asset is always considered valid while idle. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so if this asset contributes to the uncontrollable-load computation it should still report at least every 5 minutes.

anyOf

string

string

null

null

null

null

typeType (string)

Constant value: dc_charging_pole

Default value: dc_charging_pole

max_powerMax Power (integer)required

The maximum power in Watt for the charging pole itself / connection to the charging pole.

strategyChargingStrategy (string)

Possible values: [load-balancing, scheduled]

Default value: load-balancing

ForecastedThreePhaseDevice

phase_permutations object

Specify the phase mapping between this asset (child) and its parent collector (parent). Leave unset when the wiring is unknown; phase-aware control (use_topology) requires every asset's mapping to be declared, so a single unset mapping makes the controller fall back to the worst case.

anyOf

PhasePermutation

parentstring[]required

Possible values: [L1, L2, L3]

childstring[]required

Possible values: [L1, L2, L3]

null

null

nameName (string)required

The name of the device itself. This value will be used as the asset ID in the rest of the API.

collectorCollector (string)required

The name of the collector to which this device is connected.

ingress_validation object

Overrides the site-level ingress validation config for this asset. When set, controls how often measurements are expected during active and inactive transactions. When null, the site-level configuration is used.

anyOf

AssetIngressValidationConfig

with_transaction_expected_measurement_intervalstring<duration>

Expected measurement interval for the asset while it has an active transaction. Measurements arriving less frequently than this are flagged as stale by ingress validation. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so this value should not exceed 5 minutes for assets that participate in the uncontrollable-load computation.

without_transaction_expected_measurement_interval object

Expected measurement interval for the asset when no transaction is active. When null, the asset is always considered valid while idle. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so if this asset contributes to the uncontrollable-load computation it should still report at least every 5 minutes.

anyOf

string

string

null

null

null

null

typeType (string)

Constant value: forecasted_series_3phase

Default value: forecasted_series_3phase

line_currentLine Current (integer)required

The line current in Ampere.

forecast_typeForecastTypeSiteConfiguration (string)required

Defines the type of forecast to be used for this device.

Possible values: [pv, load]

should_be_aggregatedShould Be Aggregated (boolean)

Default value: false

curtailment_modeCurtailmentMode (string)

How the controller may curtail this device's production to respect the grid minimum. NONE never curtails; CONTINUOUS curtails to any level. Only relevant for PV devices.

Possible values: [none, continuous]

Default value: none

BessDevice

phase_permutations object

Specify the phase mapping between this asset (child) and its parent collector (parent). Leave unset when the wiring is unknown; phase-aware control (use_topology) requires every asset's mapping to be declared, so a single unset mapping makes the controller fall back to the worst case.

anyOf

PhasePermutation

parentstring[]required

Possible values: [L1, L2, L3]

childstring[]required

Possible values: [L1, L2, L3]

null

null

nameName (string)required

The name of the device itself. This value will be used as the asset ID in the rest of the API.

collectorCollector (string)required

The name of the collector to which this device is connected.

ingress_validation object

Overrides the site-level ingress validation config for this asset. When set, controls how often measurements are expected during active and inactive transactions. When null, the site-level configuration is used.

anyOf

AssetIngressValidationConfig

with_transaction_expected_measurement_intervalstring<duration>

Expected measurement interval for the asset while it has an active transaction. Measurements arriving less frequently than this are flagged as stale by ingress validation. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so this value should not exceed 5 minutes for assets that participate in the uncontrollable-load computation.

without_transaction_expected_measurement_interval object

Expected measurement interval for the asset when no transaction is active. When null, the asset is always considered valid while idle. Note: the UCL calculation requires measurements at least every 5 minutes to produce accurate results, so if this asset contributes to the uncontrollable-load computation it should still report at least every 5 minutes.

anyOf

string

string

null

null

null

null

typeType (string)

Constant value: battery_energy_storage_system

Default value: battery_energy_storage_system

charging_efficiencyCharging Efficiency (number)

Charging efficiency of the battery [0 < x <= 1].

Possible values: > 0 and <= 1

Default value: 0.95

discharging_efficiencyDischarging Efficiency (number)

Discharging efficiency of the battery [0 < x <= 1].

Possible values: > 0 and <= 1

Default value: 0.95

maximum_charging_powerMaximum Charging Power (number)required

Maximum charging power of the battery in W.

Possible values: > 0

maximum_discharging_powerMaximum Discharging Power (number)required

Maximum discharging power of the battery in W.

Possible values: > 0

operational_battery_capacityOperational Battery Capacity (number)required

The operational battery capacity in Wh.

Possible values: > 0

charging_priorityCharging Priority (integer)

Priority of charging the battery. Default is 10

Possible values: >= 1 and <= 10

Default value: 10

discharging_priorityDischarging Priority (integer)

Priority of discharging the battery. Default is 10

Possible values: >= 1 and <= 10

Default value: 10

policies object[]

List of policies for the BESS device.

Array [

oneOf

ScheduledBessPolicy

typeType (string)

Constant value: schedule

Default value: schedule

schedule objectrequired

The schedule defining when the state of charge should be between minimum_state_of_charge and maximum_state_of_charge.

frequency

The schedule defining when the state of charge should be between minimum_state_of_charge and maximum_state_of_charge.

Possible values: [continuous, once, weekly]

continuous

object

once

date_timesstring<date-time>[]required

List of specific date-times in ISO 8601 format with timezone

Possible values: >= 1

weekly

day_of_weekDayOfWeek (string)[]required

Days of week when the schedule runs

Possible values: [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday], >= 1

timeTime (string)required

Time in HH:MM format (24-hour)

Possible values: Value must match regular expression ^([0-1][0-9]|2[0-3]):[0-5][0-9]$

timezoneTimezone (string)required

IANA timezone identifier

minimum_state_of_chargeMinimum State Of Charge (number)required

The minimum state of charge to reach at the scheduled time. At each timestamp in the schedule, the state of charge will be between minimum_state_of_charge and maximum_state_of_charge.

Possible values: >= 0 and <= 100

maximum_state_of_chargeMaximum State Of Charge (number)required

The maximum state of charge to reach at the scheduled time. At each timestamp in the schedule, the state of charge will be between minimum_state_of_charge and maximum_state_of_charge.

Possible values: >= 0 and <= 100

violation_price_euros_per_mwhViolation Price Euros Per Mwh (number)

Soft-constraint penalty in euros per MWh of state-of-charge band violation. The default acts as a near-hard constraint; lower values let the optimiser cross the band when the expected revenue justifies it.

Possible values: >= 0

Default value: 3000000

BessHysteresisChargePolicy

typeType (string)

Constant value: charge-hysteresis

Default value: charge-hysteresis

start_charging_belowStart Charging Below (number)required

The state of charge at or below which the battery starts charging.

Possible values: >= 0 and <= 100

stop_charging_atStop Charging At (number)required

The state of charge at which the battery stops charging.

Possible values: >= 0 and <= 100

]

]

collector_list object[]required

The site's root collector, its grid connection. A site has exactly one; collectors below the grid connection belong in its children.

Possible values: <= 1

Array [

phase_permutations object

Specify the phase mapping between this asset (child) and its parent collector (parent). Leave unset when the wiring is unknown; phase-aware control (use_topology) requires every asset's mapping to be declared, so a single unset mapping makes the controller fall back to the worst case. The root collector is exempt: it is the grid connection, whose phases are the reference frame every other mapping is expressed against, so the controller always treats it as the identity and it may only be left unset or declared as the identity.

anyOf

PhasePermutation

parentstring[]required

Possible values: [L1, L2, L3]

childstring[]required

Possible values: [L1, L2, L3]

null

null

nameName (string)required

children object

The children of this collector. This is used to create a tree structure.

anyOf

array

Array [

0

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

]

null

null

line_currentLine Current (integer)required

The line current in Ampere.

safe_line_current object

An optional, safer line current in Ampere used by the optimizer instead of line_current when set.

anyOf

integer

integer

null

null

min_phase_current object

An optional lower bound in Ampere per phase. Set it to 0 on the main collector to forbid injection into the grid.

anyOf

number

number

null

null

phase_voltagePhase Voltage (integer)required

The phase voltage is in Volt.

commodityCommodity (string)

Default value: electricity

1P_3PCollectorType (string)

Specifies whether the collector is single-phase (1P) or three-phase (3P).

Possible values: [1P, 3P]

Default value: 3P

]

SiteConfiguration

{
  "device_list": [
    {
      "name": "LR34_001",
      "collector": "main_collector",
      "ingress_validation": {
        "with_transaction_expected_measurement_interval": "string",
        "without_transaction_expected_measurement_interval": "string"
      },
      "type": "charging_pole_3phase",
      "line_current": 32,
      "pin_to_phase_mapping": {
        "pin_list": [
          "pin1"
        ],
        "phase_list": [
          "L1"
        ]
      }
    },
    {
      "phase_permutations": {
        "parent": [
          "L1"
        ],
        "child": [
          "L1"
        ]
      },
      "name": "LR34_001",
      "collector": "main_collector",
      "ingress_validation": {
        "with_transaction_expected_measurement_interval": "string",
        "without_transaction_expected_measurement_interval": "string"
      },
      "type": "dc_charging_pole",
      "max_power": 250000,
      "strategy": "load-balancing"
    },
    {
      "phase_permutations": {
        "parent": [
          "L1"
        ],
        "child": [
          "L1"
        ]
      },
      "name": "LR34_001",
      "collector": "main_collector",
      "ingress_validation": {
        "with_transaction_expected_measurement_interval": "string",
        "without_transaction_expected_measurement_interval": "string"
      },
      "type": "forecasted_series_3phase",
      "line_current": 32,
      "forecast_type": "pv",
      "should_be_aggregated": false,
      "curtailment_mode": "none"
    },
    {
      "phase_permutations": {
        "parent": [
          "L1"
        ],
        "child": [
          "L1"
        ]
      },
      "name": "LR34_001",
      "collector": "main_collector",
      "ingress_validation": {
        "with_transaction_expected_measurement_interval": "string",
        "without_transaction_expected_measurement_interval": "string"
      },
      "type": "battery_energy_storage_system",
      "charging_efficiency": 0.95,
      "discharging_efficiency": 0.95,
      "maximum_charging_power": 50000,
      "maximum_discharging_power": 50000,
      "operational_battery_capacity": 100000,
      "charging_priority": 5,
      "discharging_priority": 5,
      "policies": [
        {
          "type": "schedule",
          "schedule": {
            "frequency": "weekly",
            "day_of_week": [
              "monday",
              "friday"
            ],
            "time": "09:00",
            "timezone": "America/New_York"
          },
          "minimum_state_of_charge": 20,
          "maximum_state_of_charge": 80,
          "violation_price_euros_per_mwh": 3000000
        },
        {
          "type": "charge-hysteresis",
          "start_charging_below": 10,
          "stop_charging_at": 20
        }
      ]
    }
  ],
  "collector_list": [
    {
      "phase_permutations": {
        "parent": [
          "L1"
        ],
        "child": [
          "L1"
        ]
      },
      "name": "main_collector",
      "children": [
        null
      ],
      "line_current": 400,
      "safe_line_current": 300,
      "min_phase_current": 0,
      "phase_voltage": 230,
      "commodity": "electricity",
      "1P_3P": "3P"
    }
  ]
}