Resources¶

A Resource is a physical electrical asset registered in the platform — a generator, battery, EV, charging station, water heater, or general consumption/production installation. Resources:

Are associated with a meter (CPE or internal) to take part in operations
Are owned by one or more members (fractional ownership supported)
Can receive setpoints from the energy management system (OSTEC)
Are the unit of granularity for settlement results

Resource Types¶

Type	Direction	Description
`IU`	Consume + Generate	Utilization Installation — generic prosumer unit (e.g. household with PV panels). Most common type for aggregated entities
`IC`	Consume only	Consumption Installation — consumer-only unit (e.g. household without generation)
`SCPU`	Generate only	Self-Consumption Production Unit — dedicated generation asset (PV plant)
`STORAGE`	Consume + Generate	Battery Storage — supports charge/discharge (Li-ion, VRFB, etc.)
`EV`	Consume (+ Generate if V2G)	Electric Vehicle — EV charger, with optional Vehicle-to-Grid capability
`EWH`	Consume only	Electric Water Heater — controllable thermal storage
`HP`	Consume only	Heat Pump — controllable heating load (specification in development)

Resource Fields¶

Field	Required	Description
`name`	✅	Resource name, unique within the community
`type`	✅	Resource type — see table above. Fixed after creation
`status`	✅	`ACTIVE` or `INACTIVE` for this period
`meter_id`	—	UUID of the meter directly above the resource. Without it the resource is view-only
`start_date`	✅	First day (inclusive, Europe/Lisbon) on which this resource version applies
`end_date`	—	Last day (inclusive) on which this resource version applies. `null` = open-ended

Resource Validity¶

A resource's type is fixed. Its name, status, meter and every type-specific field below are dated. An update with PUT /resources/{resource_id} requires start_date and changes the resource only from that day (or for [start_date, end_date]). For example, to record a battery upgrade from 5 kW to 10 kW on January 14, send the new max_power with start_date: 2026-01-14. Days before January 14 keep using 5 kW.

The general fields, the type-specific details, the meter assignment and the ownership list are saved together as one dated change, so they can never get out of sync.

A meter can only have one resource on any given day (409 Conflict). Put each extra resource behind its own internal meter.
A resource version with no meter_id is allowed but excluded from market, settlement, EMS and sizing until a later version assigns a meter.
GET /resources/available-meters?start_date=...&end_date=... lists meters free for the whole period.
DELETE /resources/{resource_id}?effective_at=YYYY-MM-DD ends the resource from that day. It is refused while the resource still has ownerships on or after that day.
To change type, end the resource and create a new one.

See Business Validity.

Resource-Specific Fields¶

IU / IC (Utilization & Consumption Installations)SCPU (Solar PV)STORAGE (Battery)EV (Electric Vehicle)EWH (Electric Water Heater)HP (Heat Pump)

Field	Unit	Required	Description
`sum_certified_power`	kW	—	Sum of all installed power across the assets that make up the unit
`ic_voltage_level`	—	—	Voltage level of the resource (`MAT`, `AT`, `MT`, `BT`)

Field	Unit	Required	Description
`generation_capacity`	kW	—	Nominal installed generation capacity

Field	Unit	Required	Description
`nominal_capacity`	kWh	✅	Total energy the battery can store
`max_power`	kW	✅	Maximum instantaneous charge/discharge power
`charging_efficiency`	%	—	Charging efficiency (battery + inverter)
`discharging_efficiency`	%	—	Discharging efficiency (battery + inverter)
`min_SOC`	%	—	Minimum admissible state-of-charge
`max_SOC`	%	—	Maximum admissible state-of-charge
`deg_cost`	€/kWh	—	Degradation cost per kWh discharged (relevant for Li-ion)

Field	Unit	Required	Description
`nominal_capacity`	kWh	✅	Total EV battery capacity
`max_power`	kW	✅	Maximum charge/discharge power
`charging_efficiency`	%	—	Charging efficiency
`discharging_efficiency`	%	—	Discharging efficiency (V2G)
`min_SOC`	%	—	Minimum state-of-charge
`max_SOC`	%	—	Maximum state-of-charge
`desired_min_SOC`	%	—	Minimum SOC the EV must retain at end of charging session
`deg_cost`	€/kWh	—	Degradation cost per kWh discharged

Field	Unit	Required	Description
`power`	kW	✅	Rated heater power
`capacity`	kWh	—	Total thermal energy storage capacity
`max_temp`	°C	—	Maximum water storage temperature
`default_start_temp`	°C	—	Temperature at which the thermostat activates heating
`target_temp`	°C	—	Temperature at which the thermostat deactivates

Specification in development

The Heat Pump data definition is not final. Fields, units and descriptions may change before the specification is released.

Field	Unit	Required	Description
`power_rated`	kW	—	Rated power of the heat pump
`capacity_tank`	kg	—	Water tank capacity
`temp_inlet`	°C	—	Inlet water temperature
`temp_desired`	°C	—	Desired water temperature
`temp_out_init`	°C	—	Initial outlet temperature
`temp_out_min`	°C	—	Minimum outlet temperature
`temp_out_max`	°C	—	Maximum outlet temperature
`temp_indoor_init`	°C	—	Initial indoor temperature
`temp_indoor_final`	°C	—	Final indoor temperature
`temp_indoor_min`	°C	—	Minimum indoor temperature
`temp_indoor_max`	°C	—	Maximum indoor temperature
`u_value`	kW/°C	—	Building heat loss coefficient
`thermal_resistance`	—	—	Building thermal resistance coefficient
`h_rad`	kW/m²·°C	—	Convective heat transfer coefficient of the radiator
`area_rad`	m²	—	Radiator surface area

Ownerships¶

A resource can be owned by multiple members (fractional ownership). The Ownership model records the perc_ownership each member owns of a resource for settlement purposes.

Field	Required	Description
`user_id`	✅	UUID of the owning member
`perc_ownership`	✅	Share of the resource owned by the member (greater than 0, at most 100)
`start_date`	✅	First day (inclusive, Europe/Lisbon) on which this share applies
`end_date`	—	Last day (inclusive) on which this share applies. `null` = open-ended

Ownership shares are dated, so a resource can change hands or be split differently from a given day. The total of all shares of a resource must not exceed 100% on any day; less than 100% is allowed. DELETE /ownerships/{user_id}/{resource_id}?effective_at=YYYY-MM-DD ends a member's share from that day.

graph LR
    R[Resource: Solar PV] -->|70%| M1[Member A]
    R -->|30%| M2[Member B]

Any compensation—whether paid or received—resulting from a transaction is allocated to the members who own the resource, in proportion to their ownership shares.