Download OpenAPI specification:
Return asset status entries for one or more assets.
With latest=true, returns the most recent status per asset.
With from/to, returns a paginated history of status changes.
At least one of latest or from/to is required.
params : StatusGetQueryParams Validated query parameters including asset_ids, latest, from/to, limit, offset, and optional status filter. service : StatusService Injected via FastAPI dependency.
StatusListResponse Paginated status entries for the requested assets.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| latest | boolean (Latest) Default: false |
From (string) or From (null) (From) | |
To (string) or To (null) (To) | |
Array of Status (strings) or Status (null) (Status) |
{- "limit": 0,
- "offset": 0,
- "statuses": [
- {
- "asset_id": "string",
- "status": "UNKNOWN",
- "effective_at": "2019-08-24T14:15:22Z",
- "reasons": [
- {
- "category": "UNKNOWN",
- "detail": "string",
- "source": "string",
- "attributes": { }
}
], - "created_at": "2019-08-24T14:15:22Z"
}
]
}Return status lock rows for one or more assets, newest first.
With active=true, returns only locks still in force (an asset is
pinned to UNAVAILABLE while it has one); without it, cleared locks are
included as the audit history. Locks are cleared exclusively via
PUT /asset/v1/asset-actions/{asset_id}/unlock.
params : GetStatusLocksQueryParams Validated query parameters: asset_ids, active, limit, offset. service : StatusLockService Injected via FastAPI dependency.
GetStatusLocksResponse Paginated status lock rows for the requested assets.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| active | boolean (Active) Default: false |
{- "limit": 0,
- "offset": 0,
- "status_locks": [
- {
- "id": "string",
- "asset_id": "string",
- "reason": "NOT_FOLLOWING_DISPATCH",
- "attributes": { },
- "locked_at": "2019-08-24T14:15:22Z",
- "cleared_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}Return the dispatch-reaction exclusion list, oldest first.
Assets on the list are still evaluated every cycle (their verdicts
keep flowing to logs and metrics), but a would-be status lock is
suppressed and counted as lock_skipped_excluded instead of
written — so a known-noisy asset cannot be flipped to UNAVAILABLE by
the dispatch-reaction monitor.
GetStatusLockExclusionsResponse The current exclusion list with each entry's creation time.
{- "exclusions": [
- {
- "asset_id": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}Add assets to, or remove them from, the dispatch-reaction exclusion list.
excluded=true inserts the assets, excluded=false removes
them; both directions are idempotent, and the request is
all-or-nothing (an unknown asset id fails the whole call with 404).
Intended for ops only — excluding an asset silences a safety
monitor.
request : PutStatusLockExclusionsRequest Asset ids and the desired exclusion state. service : StatusLockService Injected via FastAPI dependency.
| asset_ids required | Array of strings (Asset Ids) non-empty |
| excluded required | boolean (Excluded) |
{- "asset_ids": [
- "string"
], - "excluded": true
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Create a new asset master record.
body : CreateAssetRequest Asset creation payload. service : AssetService Injected via FastAPI dependency.
AssetResponse The created asset master record with a system-generated asset_id.
| code required | string (Code) non-empty |
| name required | string (Name) |
| type required | string (AssetType) Enum: "BESS" "VBAT" "PV" "DAA_SWAP" "DAA_SWAP_VBAT" "GREY_COLOCATION_BESS" "GREEN_COLOCATION_BESS" Supported asset types. |
| region required | string (Region) Enum: "DE" "PL" Enum of available regions. |
| delivery_area required | string (DeliveryArea) Enum: "50HZ" "AMPN" "TNBW" "TNNT" "PSE" Enum of available delivery areas. |
| provider required | string (Provider) Enum: "ENERGIEKOPPLER" "ENTELIOS" "EBX" "TERRALAYR" "TRANSITION_TECHNOLOGIES" "ASSET_SIMULATOR" "NFT" "TESVOLT" "PSE_WIRE" Energy market providers. |
{- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "provider": "ENERGIEKOPPLER"
}{- "id": "string",
- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "lifecycle": "DRAFT",
- "provider": "ENERGIEKOPPLER",
- "go_live_date": "2019-08-24",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Return all asset master records with optional filters.
params : AssetListQueryParams
Optional query parameters: type, region, lifecycle.
service : AssetService
Injected via FastAPI dependency.
AssetListResponse Matching asset master records.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
AssetType (string) or Type (null) (Type) | |
Region (string) or Region (null) (Region) | |
AssetLifecycle (string) or Lifecycle (null) (Lifecycle) | |
DeliveryArea (string) or Delivery Area (null) (Delivery Area) | |
Provider (string) or Provider (null) (Provider) |
{- "limit": 0,
- "offset": 0,
- "assets": [
- {
- "id": "string",
- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "lifecycle": "DRAFT",
- "provider": "ENERGIEKOPPLER",
- "go_live_date": "2019-08-24",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Return a single asset master record by asset_id.
asset_id : str
System-generated unique asset identifier (e.g. DE_50HZ_WU_1).
service : AssetService
Injected via FastAPI dependency.
AssetResponse The matching asset master record.
| asset_id required | string (Asset Id) |
{- "id": "string",
- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "lifecycle": "DRAFT",
- "provider": "ENERGIEKOPPLER",
- "go_live_date": "2019-08-24",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Apply a partial update to an asset master record.
Only provided fields are applied. Lifecycle transitions must use the dedicated asset-actions endpoints.
asset_id : str System-generated unique asset identifier. body : PatchAssetRequest Fields to update; omitted fields are left untouched. service : AssetService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
Name (string) or Name (null) (Name) | |
AssetType (string) or null | |
Go Live Date (string) or Go Live Date (null) (Go Live Date) | |
Provider (string) or null |
{- "name": "string",
- "type": "BESS",
- "go_live_date": "2019-08-24",
- "provider": "ENERGIEKOPPLER"
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Delete an asset master record.
Deletion is only permitted for assets in the draft lifecycle
state; any other state answers 409.
asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return the latest operational status of an asset.
asset_id : str
Unique identifier of the asset (e.g. DE_50HZ_DK_1).
service : StatusService
Injected via FastAPI dependency.
AssetStatusEntry Latest status entry for the asset.
| asset_id required | string (Asset Id) |
{- "asset_id": "string",
- "status": "UNKNOWN",
- "effective_at": "2019-08-24T14:15:22Z",
- "reasons": [
- {
- "category": "UNKNOWN",
- "detail": "string",
- "source": "string",
- "attributes": { }
}
], - "created_at": "2019-08-24T14:15:22Z"
}Customer-facing usage and history derived from the customer_events log: limitation quota usage and history, the full customer-events audit trail, and reservation usage and history. All are scoped per customer (customer_name).
Return the customer's limitation quota usage for a year.
total_utilized_periods weights the latest event per delivery period
by when it was submitted relative to the T-1 14:45 Europe/Berlin
deadline (1 before, 3 after up to 7 minutes before delivery; deletes
after the deadline also count 3). max_allowed_periods is 10% of the
year's quarter-hour periods. year defaults to the current German
trading year.
| asset_id required | string (Asset Id) |
| customer_name required | string (Customer Name) non-empty |
Year (integer) or Year (null) (Year) |
{- "asset_id": "string",
- "customer_name": "string",
- "year": 0,
- "total_utilized_periods": 0,
- "max_allowed_periods": 0,
- "red_button_used": 0,
- "red_button_max": 0
}Return the latest applied limitation per period in [from, to).
One data point per delivery period, using the latest event for that period; a period whose latest event is a delete is omitted. The window must not exceed 31 days.
| asset_id required | string (Asset Id) |
| customer_name required | string (Customer Name) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "limitations": [
- {
- "delivery_day": "2019-08-24",
- "delivery_start": "2019-08-24T14:15:22Z",
- "delivery_end": "2019-08-24T14:15:22Z",
- "max_charge": {
- "amount": "string",
- "unit": "MW"
}, - "max_discharge": {
- "amount": "string",
- "unit": "MW"
}
}
]
}Return the paginated customer-events audit trail for a customer.
Events with occurred_at in [from, to) (window capped at 365
days), most recent first. customer, asset_ids and
event_type are all optional filters (omitting customer spans
every customer; omitting asset_ids spans every asset).
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
Customer (string) or Customer (null) (Customer) | |
Array of Asset Ids (strings) or Asset Ids (null) (Asset Ids) | |
Array of Event Type (strings) or Event Type (null) (Event Type) | |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "limit": 0,
- "offset": 0,
- "events": [
- {
- "source_event_id": "string",
- "event_type": "string",
- "asset_id": "string",
- "customer_name": "string",
- "occurred_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "delivery_day": "2019-08-24",
- "period_start": "2019-08-24T14:15:22Z",
- "period_end": "2019-08-24T14:15:22Z",
- "range_start": "2019-08-24T14:15:22Z",
- "range_end": "2019-08-24T14:15:22Z",
- "max_charge": {
- "amount": "string",
- "unit": "MW"
}, - "max_discharge": {
- "amount": "string",
- "unit": "MW"
}, - "payload": { }
}
]
}Return how many delivery days are currently reserved in a year.
total_reservations is the count of delivery days whose latest
reservation event is a create (a later cancel, or no event, drops the
day) — the same rule as the reservations history, returned as a count.
year defaults to the current German trading year.
| asset_id required | string (Asset Id) |
| customer_name required | string (Customer Name) non-empty |
Year (integer) or Year (null) (Year) |
{- "asset_id": "string",
- "customer_name": "string",
- "year": 0,
- "total_reservations": 0
}Return the delivery days the asset is reserved in [from, to).
A day whose latest reservation event is a cancel is omitted. The window must not exceed 365 days.
| asset_id required | string (Asset Id) |
| customer_name required | string (Customer Name) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "reserved_days": [
- "2019-08-24"
]
}Lifecycle transitions (commission, decommission, etc.). Each endpoint covers exactly one transition between adjacent lifecycle states.
Transition the asset from DRAFT to COMMISSIONING.
asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Transition the asset from COMMISSIONING to LIVE.
Sets go_live_date to today (UTC) if it is not already set.
asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Transition the asset from LIVE to SUSPENDED.
asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Transition the asset from SUSPENDED back to LIVE.
asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Transition the asset from LIVE to DECOMMISSIONED.
asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Clear the asset's dispatch-reaction status lock.
The only way to release a lock created by the dispatch-reaction monitor: the asset's status returns to normal rule evaluation on the next monitor cycle, and the evaluator re-arms. Unlocking an asset with no active lock is an idempotent no-op.
asset_id : str System-generated unique asset identifier. service : StatusLockService Injected via FastAPI dependency.
| asset_id required | string (Asset Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Enable or disable dispatch control for a site or an asset.
Sets control_enabled on the target's adapter config row, which is
what the provider's control run dispatches from. An asset that belongs to
a site is controlled through its site, so enabling the asset or its site
has the same effect. An asset without a site must be a BESS, grey
co-location BESS or VBAT. The provider is the asset's provider; a site's
is its first member asset's. A target without an adapter config row for
that provider is rejected (422); control already in the requested state
is rejected (409). The provider's Parameter Store control list, the
control run's fallback, is updated afterwards on a best-effort basis.
target_id : str
Site id or asset id to control.
body : ControlRequest
The desired enabled state.
service : AssetControlService
Injected via FastAPI dependency.
| target_id required | string (Target Id) |
| enabled required | boolean (Enabled) |
{- "enabled": true
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Historical per-asset dispatch commands. Read-only — writes happen via the event-driven ingestion worker, not over HTTP.
Return a paginated history of dispatch commands.
Used by Operators and the Optimisation service for audit trails, monitoring, and debugging anomalies (e.g. slow-ramp investigation).
params : DispatchListQueryParams
Required asset_ids, from and to, plus optional
sources, limit and offset. Without sources only each
asset's official provider is returned.
service : DispatchService
Injected via FastAPI dependency.
DispatchListResponse Matching dispatch records with pagination metadata.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
Array of Sources (strings) or Sources (null) (Sources) |
{- "dispatches": [
- {
- "source": "string",
- "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
- "published_at": "2019-08-24T14:15:22Z",
- "asset_id": "string",
- "dispatch_time": "2019-08-24T14:15:22Z",
- "delivery_period_start": "2019-08-24T14:15:22Z",
- "target_power": {
- "amount": "string",
- "unit": "MW"
}, - "nominal_power": {
- "amount": "string",
- "unit": "MW"
}, - "power_imbalance": {
- "amount": "string",
- "unit": "MW"
}, - "soc_imbalance": {
- "amount": "string",
- "unit": "MW"
}
}
], - "limit": 0,
- "offset": 0
}Batch upsert state snapshots.
Inserts or overwrites state snapshots for one or more assets. The entire batch succeeds or none of it is written (single atomic statement).
On conflict on (asset_id, effective_at), the energy fields and
updated_at are overwritten. created_at is never modified.
Returns 422 if any asset_id in the batch does not exist, identifying
all offending IDs.
required | Array of objects (State Snapshots) non-empty |
{- "state_snapshots": [
- {
- "asset_id": "string",
- "effective_at": "2019-08-24T14:15:22Z",
- "stored_energy": {
- "amount": 0,
- "unit": "MW"
}, - "reading_quality": "VALID",
- "current_battery_power": {
- "amount": 0,
- "unit": "MW"
}, - "current_poc_power": {
- "amount": 0,
- "unit": "MW"
}, - "current_pv_power": {
- "amount": 0,
- "unit": "MW"
}
}
]
}{- "state_snapshots": [
- {
- "asset_id": "string",
- "effective_at": "2019-08-24T14:15:22Z",
- "stored_energy": {
- "amount": "string",
- "unit": "MW"
}, - "reading_quality": "VALID",
- "current_battery_power": {
- "amount": "string",
- "unit": "MW"
}, - "current_poc_power": {
- "amount": "string",
- "unit": "MW"
}, - "current_pv_power": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Retrieve state snapshots for one or more assets.
Latest mode (latest=true): returns the single most recent snapshot
per asset. Cannot be combined with from or to.
Time-range mode (default): returns all snapshots with
effective_at in [from, to), ordered effective_at ASC,
paginated via limit/offset. to defaults to now() when
omitted. Unknown asset_ids return an empty list silently.
| asset_ids required | Array of strings (Asset Ids) non-empty |
| latest | boolean (Latest) Default: false |
From (string) or From (null) (From) | |
To (string) or To (null) (To) | |
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
{- "state_snapshots": [
- {
- "asset_id": "string",
- "effective_at": "2019-08-24T14:15:22Z",
- "stored_energy": {
- "amount": "string",
- "unit": "MW"
}, - "reading_quality": "VALID",
- "charged_energy": {
- "amount": "string",
- "unit": "MW"
}, - "discharged_energy": {
- "amount": "string",
- "unit": "MW"
}, - "current_battery_power": {
- "amount": "string",
- "unit": "MW"
}, - "current_poc_power": {
- "amount": "string",
- "unit": "MW"
}, - "current_pv_power": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "limit": 0,
- "offset": 0,
- "total_charged_energy": {
- "amount": "string",
- "unit": "MW"
}, - "total_discharged_energy": {
- "amount": "string",
- "unit": "MW"
}
}Period limits per asset per 15-min slot — charge/discharge power, energy bands, trading lock. Multi-source with computed most-restrictive values.
Batch partial-update period limits for one or more assets.
Each entry specifies a UTC time-of-day window (start_time-
end_time) and a date range (valid_from-valid_until). The
server expands each entry into individual 15-minute delivery period rows
for every day in [valid_from, valid_until]. delivery_day is
derived server-side from each row's start_time — do not pass it in
the request.
On conflict on (asset_id, start_time, source) the upsert is
partial — every nullable field (power_charge,
power_discharge, energy_low, energy_high,
trading_locked) is overwritten only when the incoming value is
non-null; null preserves the existing column. To clear
trading_locked send an explicit false; to clear a constraint
column issue DELETE on the (asset, period range, source).
end_time, delivery_day and updated_at always overwrite;
created_at is never modified.
Returns 404 if any referenced asset_id does not exist.
required | Array of objects (Limits) non-empty |
{- "limits": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "recurrent": false,
- "source": "REPORTED",
- "power_charge": {
- "amount": 0,
- "unit": "MW"
}, - "power_discharge": {
- "amount": 0,
- "unit": "MW"
}, - "energy_low": {
- "amount": 0,
- "unit": "MW"
}, - "energy_high": {
- "amount": 0,
- "unit": "MW"
}, - "trading_locked": true
}
]
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated period limits for one or more assets.
Retrieves all period limit rows within [from, to) for the given
assets. Results are grouped by (asset_id, start_time) and include
both per-source raw values and derived computed limits.
Computed limits represent the most-restrictive value across all sources:
power_charge (max), power_discharge (min), energy_low (max),
energy_high (min), trading_locked (any).
Optionally filter by sources (comma-separated or repeated).
A trade-blocked period has 0 computed power limits unless
enforce_trade_blocked=false, which keeps the power band so reserved
power can still be dispatched (control paths).
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
Array of Sources (strings) or Sources (null) (Sources) | |
| enforce_trade_blocked | boolean (Enforce Trade Blocked) Default: true |
{- "limit": 0,
- "offset": 0,
- "limits": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "delivery_day": "2019-08-24",
- "computed_limits": {
- "power_charge": {
- "amount": "string",
- "unit": "MW"
}, - "power_discharge": {
- "amount": "string",
- "unit": "MW"
}, - "energy_low": {
- "amount": "string",
- "unit": "MW"
}, - "energy_high": {
- "amount": "string",
- "unit": "MW"
}, - "trading_locked": true
}, - "sources": [
- {
- "source": "REPORTED",
- "power_charge": {
- "amount": "string",
- "unit": "MW"
}, - "power_discharge": {
- "amount": "string",
- "unit": "MW"
}, - "energy_low": {
- "amount": "string",
- "unit": "MW"
}, - "energy_high": {
- "amount": "string",
- "unit": "MW"
}, - "trading_locked": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
]
}Clear constraint contributions for a source within a time range.
For each row matching start_time in [start_time, end_time)
for the given asset_id and source:
power_charge, power_discharge, energy_low and
energy_high are set to NULL.trading_locked is preserved — DELETE does not clear a
lock. To clear trading_locked send a PATCH with an explicit
trading_locked=false.NULL and trading_locked not TRUE) are
removed from the table.This lets customer-side limits and customer-side reservation locks
share a source=CUSTOMER row without a DELETE on one wiping the
other.
| asset_id required | string (Asset Id) |
| start_time required | string <date-time> (Start Time) |
| end_time required | string <date-time> (End Time) |
| source required | string (LimitSource) Enum: "REPORTED" "OPERATIONS" "CUSTOMER" "PV" "REDISPATCH" "FCA" "AVAILABILITY" "IMPOSED" Controlled vocabulary for limit submission sources. |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Batch upsert forecast periods for one or more assets.
Each entry specifies a UTC [start_time, end_time) window and the
forecasted generation and consumption for that period. The
natural key is (asset_id, start_time) — re-submitting the same key
overwrites the row's forecast values and updated_at; created_at
is never modified. delivery_day is derived server-side and must
not be supplied by the client.
Returns 404 if any referenced asset_id does not exist.
required | Array of objects (Forecasts) non-empty |
{- "forecasts": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "generation": {
- "amount": 0,
- "unit": "MW"
}, - "consumption": {
- "amount": 0,
- "unit": "MW"
}, - "import_from_grid_fee": 0
}
]
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated forecast periods for one or more assets.
Retrieves forecast rows with start_time in [from, to) for the
given assets, ordered by (asset_id, start_time).
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "limit": 0,
- "offset": 0,
- "forecasts": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "delivery_day": "2019-08-24",
- "generation": {
- "amount": "string",
- "unit": "MW"
}, - "consumption": {
- "amount": "string",
- "unit": "MW"
}, - "import_from_grid_fee": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Net market positions per (asset, period, market, source) — from optimisation, external sources, or DAA swaps.
Batch-write reservation periods in mode overwrite or cumulative.
Each entry specifies a UTC [start_time, end_time) window, a
market string and a source. The natural key is
(asset_id, start_time, market, source). delivery_day is
derived server-side from start_time and must not be supplied by
the client. The batch is applied atomically in both modes; rows not in
the payload are left untouched.
overwrite (the default when mode is omitted, so existing
callers are unchanged): all four numeric fields (power in MW;
energy_change, energy_buffer_low, energy_buffer_high in
MWh) are required, natural keys must be unique (422 otherwise) and
re-submitting a key overwrites every value column. created_at is
never modified.cumulative (Generalised Asset API incremental mode, temporary):
each numeric field is a signed delta added to the stored row; a
missing row starts from zero. Only power is required; an omitted
energy field adds zero. Entries sharing a natural key are summed
first and must share end_time. Amounts may have at most 4 decimal
places and unknown fields are rejected.Idempotency-Key is required for cumulative (422 without it) and
ignored for overwrite. A key already applied (in the last 3 days) with
a byte-identical body is a no-op returning 204; the same key with a
different body returns 409. Keys are scoped to this method + path.
Returns 204. Returns 404 if any referenced asset_id does not
exist, and 422 if an accumulated total overflows the stored precision.
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) |
| mode | string (Mode) Default: "overwrite" Value: "overwrite" |
required | Array of objects (Reservations) [ 1 .. 1000 ] items |
{- "mode": "overwrite",
- "reservations": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "market": "AFRR-EP",
- "source": "OPTIMISATION",
- "power": {
- "amount": 0,
- "unit": "MW"
}, - "energy_change": {
- "amount": 0,
- "unit": "MW"
}, - "energy_buffer_low": {
- "amount": 0,
- "unit": "MW"
}, - "energy_buffer_high": {
- "amount": 0,
- "unit": "MW"
}
}
]
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated reservation periods for one or more assets.
Retrieves reservation rows with start_time in [from, to) for
the given assets, ordered by (asset_id, start_time, market, source). Optionally filter by markets and/or sources
(comma-separated or repeated query parameters).
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
Array of Markets (strings) or Markets (null) (Markets) | |
Array of Sources (strings) or Sources (null) (Sources) |
{- "limit": 0,
- "offset": 0,
- "reservations": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "delivery_day": "2019-08-24",
- "market": "string",
- "source": "OPTIMISATION",
- "power": {
- "amount": "string",
- "unit": "MW"
}, - "energy_change": {
- "amount": "string",
- "unit": "MW"
}, - "energy_buffer_low": {
- "amount": "string",
- "unit": "MW"
}, - "energy_buffer_high": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Upsert a versioned technical spec for one asset.
The natural key is (asset_id, valid_from). Re-submitting the
same key applies a partial update — fields omitted from the
request preserve the existing column value. Otherwise a new row
is inserted, inheriting any omitted field from the most recent
prior version (so a new version never nulls columns the previous
one carried; an explicit value, including explicit null,
overrides). For BESS specs (valid_to omitted/null) the
currently-active row, if any, is closed by setting its
valid_to to the new valid_from; the new valid_from
must be strictly after the existing active spec.
For vBat specs (explicit valid_to) the database EXCLUDE
constraint rejects any window that partially overlaps an existing
spec; full overlap on the same valid_from is handled as the
partial-update case above.
Returns 404 if the referenced asset_id does not exist, 422 if
the BESS ordering rule or the vBat overlap rule is violated.
| asset_id required | string (Asset Id) |
Valid From (string) or Valid From (null) (Valid From) | |
Valid To (string) or Valid To (null) (Valid To) | |
Quantity (object) or null | |
Quantity (object) or null | |
Quantity (object) or null | |
Quantity (object) or null | |
Quantity (object) or null | |
Ramp Rate (number) or Ramp Rate (string) or Ramp Rate (null) (Ramp Rate) | |
Ramp Type (string) or Ramp Type (null) (Ramp Type) | |
Charge Efficiency (number) or Charge Efficiency (string) or Charge Efficiency (null) (Charge Efficiency) | |
Discharge Efficiency (number) or Discharge Efficiency (string) or Discharge Efficiency (null) (Discharge Efficiency) | |
Quantity (object) or null | |
Quantity (object) or null | |
Quantity (object) or null | |
Quantity (object) or null |
{- "asset_id": "string",
- "valid_from": "2019-08-24T14:15:22Z",
- "valid_to": "2019-08-24T14:15:22Z",
- "rated_power": {
- "amount": 0,
- "unit": "MW"
}, - "usable_charge_power": {
- "amount": 0,
- "unit": "MW"
}, - "usable_discharge_power": {
- "amount": 0,
- "unit": "MW"
}, - "grid_connection_max_power": {
- "amount": 0,
- "unit": "MW"
}, - "max_capacity": {
- "amount": 0,
- "unit": "MW"
}, - "ramp_rate": 0,
- "ramp_type": "string",
- "charge_efficiency": 0,
- "discharge_efficiency": 0,
- "daily_cycle_energy_limit": {
- "amount": 0,
- "unit": "MW"
}, - "prequalified_fcr": {
- "amount": 0,
- "unit": "MW"
}, - "prequalified_afrr_charge": {
- "amount": 0,
- "unit": "MW"
}, - "prequalified_afrr_discharge": {
- "amount": 0,
- "unit": "MW"
}
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated spec versions for one or more assets.
Rows are ordered by (asset_id, valid_from DESC). latest=true
collapses to one row per asset; active=true returns the spec in
effect now per asset and takes precedence over latest. from and to bound
valid_from inclusive on both ends; the combined span is
capped at 31 days to bound query cost.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| latest | boolean (Latest) Default: false |
| active | boolean (Active) Default: false |
From (string) or From (null) (From) | |
To (string) or To (null) (To) |
{- "limit": 0,
- "offset": 0,
- "specs": [
- {
- "asset_id": "string",
- "valid_from": "2019-08-24T14:15:22Z",
- "valid_to": "2019-08-24T14:15:22Z",
- "rated_power": {
- "amount": "string",
- "unit": "MW"
}, - "usable_charge_power": {
- "amount": "string",
- "unit": "MW"
}, - "usable_discharge_power": {
- "amount": "string",
- "unit": "MW"
}, - "grid_connection_max_power": {
- "amount": "string",
- "unit": "MW"
}, - "max_capacity": {
- "amount": "string",
- "unit": "MW"
}, - "ramp_rate": "string",
- "ramp_type": "string",
- "charge_efficiency": "string",
- "discharge_efficiency": "string",
- "daily_cycle_energy_limit": {
- "amount": "string",
- "unit": "MW"
}, - "prequalified_fcr": {
- "amount": "string",
- "unit": "MW"
}, - "prequalified_afrr_charge": {
- "amount": "string",
- "unit": "MW"
}, - "prequalified_afrr_discharge": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Device telemetry per asset at native resolution (up to 1 sample/second). Read-only — writes happen via the event-driven ingestion worker, not over HTTP. For non-time-critical use (reporting, analysis); not a real-time / control path.
Backfill / correct a batch of historical telemetry readings.
Internal-only ops endpoint (same exposure as PATCH /limits and
POST /state-snapshots), used when a provider replays a telemetry gap,
restates a window with corrected values, or to recover readings dropped as
permanent worker failures. Bulk-overwrites up to 1000 readings on
(asset_id, telemetry_timestamp): an existing row is overwritten with
the submitted values, a missing one is inserted. Re-sending is idempotent
(same input, same stored data).
Each reading is validated per-row; a rejected one is reported in the
errors list (with its submitted index, identity, and reason) while
the rest are still written, so one bad row never blocks the batch. Fix the
reported rows and re-send the file. The response returns received,
written, and rejected counts. A reading is rejected when its
telemetry_timestamp is not UTC, is in the future, or is older than the
7-day retention window; when it carries no values; when a value overflows
NUMERIC(18, 6); when its asset_id does not exist; or when its daily
partition has not been created yet. Two readings sharing the same
(asset_id, telemetry_timestamp) are rejected wholesale with 422.
required | Array of objects (Telemetry) [ 1 .. 1000 ] items |
{- "telemetry": [
- {
- "provider": "ENERGIEKOPPLER",
- "asset_id": "string",
- "telemetry_timestamp": "2019-08-24T14:15:22Z",
- "reading_quality": "VALID",
- "fcr_reserved_positive_power": 0,
- "fcr_reserved_negative_power": 0,
- "fcr_dispatch_power": 0,
- "afrr_reserved_positive_power": 0,
- "afrr_reserved_negative_power": 0,
- "afrr_target_power": 0,
- "afrr_dispatch_power": 0,
- "wholesale_target_power": 0,
- "wholesale_dispatch_power": 0,
- "total_dispatch_power": 0,
- "available_discharge_power": 0,
- "available_charge_power": 0,
- "total_available_energy": 0,
- "min_soc": 0,
- "stored_energy": 0,
- "curtailed_charge_power": 0,
- "curtailed_discharge_power": 0,
- "aux_power": 0,
- "grid_frequency": 0,
- "pv_export_curtailment_dso": 0,
- "pv_irradiance": 0,
- "pv_power_dc_actual": 0,
- "net_grid_export": 0,
- "poc_power_actual_ac": 0,
- "export_curtailment_dso": 0,
- "import_curtailment_dso": 0,
- "discharge_throughput": 0,
- "charge_throughput": 0
}
]
}{- "received": 0,
- "written": 0,
- "rejected": 0,
- "errors": [
- {
- "index": 0,
- "asset_id": "string",
- "telemetry_timestamp": "2019-08-24T14:15:22Z",
- "reason": "not_utc",
- "field": "string"
}
]
}Return telemetry for one or more assets: a window, or the latest row each.
Latest mode (latest=true): returns the single most recent
reading per asset — the row with the greatest telemetry_timestamp
(provider measurement time), so a backfilled old reading never shows up
as latest. Cannot be combined with from or to; limit and
offset are ignored. Unknown assets and assets without telemetry are
silently absent. A reading is only as fresh as ingest: judge its age
from telemetry_timestamp, never from the time of the call.
Time-range mode (default): rows are stored at native resolution
(one row per asset per reading instant) and ordered by
(asset_id, telemetry_timestamp) ascending. from and to bound
telemetry_timestamp as a half-open [from, to) window; the span
is capped at 2 days to bound query cost.
params : GetTelemetryQueryParams
Required filter asset_ids plus either latest=true or
from/to, and optional limit and offset.
service : TelemetryService
Injected via FastAPI dependency.
GetTelemetryResponse Matching telemetry rows with pagination metadata.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| latest | boolean (Latest) Default: false |
From (string) or From (null) (From) | |
To (string) or To (null) (To) |
{- "limit": 0,
- "offset": 0,
- "telemetry": [
- {
- "provider": "string",
- "asset_id": "string",
- "telemetry_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "reading_quality": "VALID",
- "fcr_reserved_positive_power": "string",
- "fcr_reserved_negative_power": "string",
- "fcr_dispatch_power": "string",
- "afrr_reserved_positive_power": "string",
- "afrr_reserved_negative_power": "string",
- "afrr_target_power": "string",
- "afrr_dispatch_power": "string",
- "wholesale_target_power": "string",
- "wholesale_dispatch_power": "string",
- "total_dispatch_power": "string",
- "available_discharge_power": "string",
- "available_charge_power": "string",
- "total_available_energy": "string",
- "min_soc": "string",
- "stored_energy": "string",
- "curtailed_charge_power": "string",
- "curtailed_discharge_power": "string",
- "aux_power": "string",
- "grid_frequency": "string",
- "pv_export_curtailment_dso": "string",
- "pv_irradiance": "string",
- "pv_power_dc_actual": "string",
- "net_grid_export": "string",
- "poc_power_actual_ac": "string",
- "export_curtailment_dso": "string",
- "import_curtailment_dso": "string",
- "discharge_throughput": "string",
- "charge_throughput": "string"
}
]
}Versioned Flexible Connection Agreement rules per asset. Each rule configures how forecast sources reduce to a metric and how that metric maps to battery charge / discharge availability; the FCA engine evaluates all active rules into source=FCA limits.
Upsert a versioned FCA rule for one asset.
The natural key is (asset_id, name, valid_from). Re-submitting
the same key fully replaces the rule configuration. Otherwise a new
version is inserted; for an open-ended rule (valid_to omitted)
the currently-active version, if any, is closed by setting its
valid_to to the new valid_from — the new valid_from
must be strictly after the active version's.
The configuration is validated against the FCA contract: declared
sources must be unique, the metric may only reference declared
sources, CAPACITY_FACTOR requires installed_capacity on
every referenced source, breakpoints must be strictly increasing in
x with availabilities in [0, 1].
Returns 404 if the referenced asset_id does not exist, 422 if
the configuration is invalid or the validity window overlaps an
existing version.
Array of objects (Sources) | |
required | any (Metric) |
required | object (PowerCurveConfig-Input) The charge and discharge availability curves of a rule. |
| role | string (RuleRole) Default: "CAP" Enum: "CAP" "FLOOR" Which way a rule pushes the combined envelope.
|
ActiveWindow (object) or null | |
Array of Zones (objects) or Zones (null) (Zones) | |
Decisive Lead Minutes (integer) or Decisive Lead Minutes (null) (Decisive Lead Minutes) | |
| asset_id required | string (Asset Id) |
| name required | string (Name) [ 1 .. 100 ] characters ^[a-z0-9]+(-[a-z0-9]+)*$ Kebab-case rule identifier, stable across versions. |
| valid_from required | string <date-time> (Valid From) |
Valid To (string) or Valid To (null) (Valid To) | |
| enabled | boolean (Enabled) Default: true |
{- "sources": [
- {
- "source": "WIND",
- "forecast_provider": "ENERGY_WEATHER",
- "forecast_type": "EW_WIND_FORECAST",
- "forecast_asset_id": "string",
- "installed_capacity": {
- "amount": 0,
- "unit": "MW"
}
}
], - "metric": {
- "sources": [
- "WIND"
], - "type": "CAPACITY_FACTOR"
}, - "power_curve": {
- "charge": {
- "interpolation": "LINEAR",
- "breakpoints": [
- [
- 0,
- 0
]
], - "outside_range": "CLAMP"
}, - "discharge": {
- "interpolation": "LINEAR",
- "breakpoints": [
- [
- 0,
- 0
]
], - "outside_range": "CLAMP"
}
}, - "role": "CAP",
- "active_window": {
- "from": "14:15:22Z",
- "to": "14:15:22Z"
}, - "zones": [
- {
- "x_from": 0,
- "x_to": 0,
- "name": "string",
- "direction": "TOWARDS_DISCHARGE"
}
], - "decisive_lead_minutes": 1,
- "asset_id": "string",
- "name": "string",
- "valid_from": "2019-08-24T14:15:22Z",
- "valid_to": "2019-08-24T14:15:22Z",
- "enabled": true
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated FCA rule versions.
With no filters, pages through every rule version across all
assets. Rows are ordered by (asset_id, name, valid_from DESC).
asset_ids restricts to specific assets, name to one rule,
active_at keeps versions whose validity window contains the
timestamp, enabled filters on the operational switch, and
latest=true collapses to the most recent version per
(asset_id, name).
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
Array of Asset Ids (strings) or Asset Ids (null) (Asset Ids) | |
Name (string) or Name (null) (Name) | |
Active At (string) or Active At (null) (Active At) | |
Enabled (boolean) or Enabled (null) (Enabled) | |
| latest | boolean (Latest) Default: false |
{- "limit": 0,
- "offset": 0,
- "rules": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "asset_id": "string",
- "name": "string",
- "enabled": true,
- "valid_from": "2019-08-24T14:15:22Z",
- "valid_to": "2019-08-24T14:15:22Z",
- "sources": [
- {
- "source": "WIND",
- "forecast_provider": "ENERGY_WEATHER",
- "forecast_type": "EW_WIND_FORECAST",
- "forecast_asset_id": "string",
- "installed_capacity": {
- "amount": "string",
- "unit": "MW"
}
}
], - "metric": {
- "sources": [
- "WIND"
], - "type": "CAPACITY_FACTOR"
}, - "power_curve": {
- "charge": {
- "interpolation": "LINEAR",
- "breakpoints": [
- [
- "string",
- "string"
]
], - "outside_range": "CLAMP"
}, - "discharge": {
- "interpolation": "LINEAR",
- "breakpoints": [
- [
- "string",
- "string"
]
], - "outside_range": "CLAMP"
}
}, - "role": "CAP",
- "active_window": {
- "from": "14:15:22Z",
- "to": "14:15:22Z"
}, - "zones": [
- {
- "x_from": "string",
- "x_to": "string",
- "name": "string",
- "direction": "TOWARDS_DISCHARGE"
}
], - "decisive_lead_minutes": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Toggle the operational switch of one rule version.
Pausing a rule (enabled=false) removes it from engine
evaluation without creating a new version or touching its validity
window — intended for short operational interruptions. Returns 404
if no rule version exists with the given id.
| rule_id required | string <uuid> (Rule Id) |
| enabled required | boolean (Enabled) |
{- "enabled": true
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Delete one rule version by id.
Intended for correcting configuration mistakes. Ending an agreement
should instead close its validity window (PUT with
valid_to), which preserves history. Returns 404 if no rule
version exists with the given id.
| rule_id required | string <uuid> (Rule Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated FCA band evaluations.
The FCA engine's per-period evidence trail: one row per evaluation
of one delivery period at one moment, appended every run. Rows are
ordered by (asset_id, period_start, evaluated_at DESC).
asset_ids (required) restricts to specific assets; from /
to bound period_start (half-open, max 365 days);
evaluated_before / evaluated_after bound the evaluation
time (an as-of reconstruction). latest=true collapses to the
newest evaluation per period; decisive=true to the newest
evaluation strictly before each period's decisive moment
(period_start - decisive_lead), which requires every requested
asset to carry a rule with decisive_lead_minutes and is
computed against the current lead configuration. The two modes are
mutually exclusive.
Returns 422 if the window or mode combination violates the query
contract, or if decisive is requested for an asset without a
decisive lead.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
Evaluated Before (string) or Evaluated Before (null) (Evaluated Before) | |
Evaluated After (string) or Evaluated After (null) (Evaluated After) | |
| latest | boolean (Latest) Default: false |
| decisive | boolean (Decisive) Default: false |
{- "limit": 0,
- "offset": 0,
- "evaluations": [
- {
- "asset_id": "string",
- "period_start": "2019-08-24T14:15:22Z",
- "evaluated_at": "2019-08-24T14:15:22Z",
- "evaluation_results": [
- { }
], - "zone_name": "string",
- "zone_direction": "string",
- "combined_envelope_charge": "string",
- "combined_envelope_discharge": "string"
}
]
}Create a new site record.
body : CreateSiteRequest Site creation payload. service : SiteService Injected via FastAPI dependency.
SiteResponse The created site record with a system-generated id.
| name required | string (Name) |
| code required | string (Code) |
| region required | string (Region) Enum: "DE" "PL" Enum of available regions. |
| delivery_area required | string (DeliveryArea) Enum: "50HZ" "AMPN" "TNBW" "TNNT" "PSE" Enum of available delivery areas. |
| type required | string (SiteType) Enum: "STANDALONE_BESS" "STANDALONE_VBAT" "GREY_COLOCATION" "GREEN_COLOCATION" Topology of a site: what Entrix controls and how it is connected. |
Dso (string) or Dso (null) (Dso) Distribution system operator at the site's point of connection. | |
object (DispatchMode-Input) Dispatch mode configuration for a site. | |
DaaSwap (object) or null Day-ahead swap: the virtual battery a partner trades day-ahead on. Null when the site is not swapped. | |
required | object (Quantity-Input) Static point-of-connection limit on power drawn from the grid — the asset charge direction. Positive magnitude in MW. A STANDALONE_VBAT site has no physical point of connection: the value is the pool's static ceiling. |
required | object (Quantity-Input) Static point-of-connection limit on power fed into the grid — the asset discharge / generation direction. Positive magnitude in MW. A STANDALONE_VBAT site has no physical point of connection: the value is the pool's static ceiling. |
{- "name": "string",
- "code": "string",
- "region": "DE",
- "delivery_area": "50HZ",
- "type": "STANDALONE_BESS",
- "dso": "string",
- "dispatch_mode": {
- "name": "BESS_ONLY",
- "floor_price": {
- "amount": 0,
- "unit": "MW"
}, - "strike_price": {
- "amount": 0,
- "unit": "MW"
}
}, - "daa_swap": {
- "vbat_asset_id": "string"
}, - "max_import_from_grid": {
- "amount": 0,
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": 0,
- "unit": "MW"
}
}{- "id": "string",
- "name": "string",
- "code": "string",
- "region": "DE",
- "delivery_area": "50HZ",
- "type": "STANDALONE_BESS",
- "dso": "string",
- "dispatch_mode": {
- "name": "BESS_ONLY",
- "floor_price": {
- "amount": "string",
- "unit": "MW"
}, - "strike_price": {
- "amount": "string",
- "unit": "MW"
}
}, - "daa_swap": {
- "vbat_asset_id": "string"
}, - "max_import_from_grid": {
- "amount": "string",
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "inverters": [
- {
- "id": "string",
- "site_id": "string",
- "rated_power": {
- "amount": "string",
- "unit": "MW"
}, - "charge_efficiency": "string",
- "discharge_efficiency": "string",
- "asset_ids": [
- "string"
], - "assets": [
- {
- "id": "string",
- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "lifecycle": "DRAFT",
- "provider": "ENERGIEKOPPLER",
- "go_live_date": "2019-08-24",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
]
}Return all site records with optional filters.
params : SiteListQueryParams
Optional query parameters: region, delivery_area, type,
asset_id, expand (inverters embeds the inverters with
their attached assets).
service : SiteService
Injected via FastAPI dependency.
SiteListResponse Matching site records.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
Region (string) or Region (null) (Region) | |
DeliveryArea (string) or Delivery Area (null) (Delivery Area) | |
SiteType (string) or Type (null) (Type) | |
Asset Id (string) or Asset Id (null) (Asset Id) | |
Expand (string) or Expand (null) (Expand) |
{- "limit": 0,
- "offset": 0,
- "sites": [
- {
- "id": "string",
- "name": "string",
- "code": "string",
- "region": "DE",
- "delivery_area": "50HZ",
- "type": "STANDALONE_BESS",
- "dso": "string",
- "dispatch_mode": {
- "name": "BESS_ONLY",
- "floor_price": {
- "amount": "string",
- "unit": "MW"
}, - "strike_price": {
- "amount": "string",
- "unit": "MW"
}
}, - "daa_swap": {
- "vbat_asset_id": "string"
}, - "max_import_from_grid": {
- "amount": "string",
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "inverters": [
- {
- "id": "string",
- "site_id": "string",
- "rated_power": {
- "amount": "string",
- "unit": "MW"
}, - "charge_efficiency": "string",
- "discharge_efficiency": "string",
- "asset_ids": [
- "string"
], - "assets": [
- {
- "id": "string",
- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "lifecycle": "DRAFT",
- "provider": "ENERGIEKOPPLER",
- "go_live_date": "2019-08-24",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
]
}
]
}Return a single site record by site_id.
site_id : str
System-generated unique site identifier (e.g. DE_AMPN_IMMST_SITE_1).
service : SiteService
Injected via FastAPI dependency.
SiteResponse
The matching site record with its inverters embedded, each listing
the attached assets (assets) next to their ids.
| site_id required | string (Site Id) |
{- "id": "string",
- "name": "string",
- "code": "string",
- "region": "DE",
- "delivery_area": "50HZ",
- "type": "STANDALONE_BESS",
- "dso": "string",
- "dispatch_mode": {
- "name": "BESS_ONLY",
- "floor_price": {
- "amount": "string",
- "unit": "MW"
}, - "strike_price": {
- "amount": "string",
- "unit": "MW"
}
}, - "daa_swap": {
- "vbat_asset_id": "string"
}, - "max_import_from_grid": {
- "amount": "string",
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "inverters": [
- {
- "id": "string",
- "site_id": "string",
- "rated_power": {
- "amount": "string",
- "unit": "MW"
}, - "charge_efficiency": "string",
- "discharge_efficiency": "string",
- "asset_ids": [
- "string"
], - "assets": [
- {
- "id": "string",
- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "lifecycle": "DRAFT",
- "provider": "ENERGIEKOPPLER",
- "go_live_date": "2019-08-24",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
]
}Apply a partial update to a site record.
Only provided fields are applied. Fields that form the site id (code, region, delivery_area) are immutable.
site_id : str System-generated unique site identifier. body : PatchSiteRequest Fields to update; omitted fields are left untouched. service : SiteService Injected via FastAPI dependency.
| site_id required | string (Site Id) |
Name (string) or Name (null) (Name) | |
Dso (string) or Dso (null) (Dso) Distribution system operator at the site's point of connection. | |
DaaSwap (object) or null Day-ahead swap: the virtual battery a partner trades day-ahead on. Null when the site is not swapped. | |
DispatchModeName (string) or null | |
Quantity (object) or null | |
Quantity (object) or null | |
Quantity (object) or null Static point-of-connection limit on power drawn from the grid — the asset charge direction. Positive magnitude in MW. A STANDALONE_VBAT site has no physical point of connection: the value is the pool's static ceiling. | |
Quantity (object) or null Static point-of-connection limit on power fed into the grid — the asset discharge / generation direction. Positive magnitude in MW. A STANDALONE_VBAT site has no physical point of connection: the value is the pool's static ceiling. |
{- "name": "string",
- "dso": "string",
- "daa_swap": {
- "vbat_asset_id": "string"
}, - "dispatch_mode_name": "BESS_ONLY",
- "dispatch_mode_floor_price": {
- "amount": 0,
- "unit": "MW"
}, - "dispatch_mode_strike_price": {
- "amount": 0,
- "unit": "MW"
}, - "max_import_from_grid": {
- "amount": 0,
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": 0,
- "unit": "MW"
}
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Delete a site record.
site_id : str System-generated unique site identifier. service : SiteService Injected via FastAPI dependency.
| site_id required | string (Site Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated PoC limits for a site within a time window.
Several sources can limit a site (REDISPATCH: the DSO redispatch
sync, the static limits with the current curtailment applied;
OPERATIONS: operational restrictions such as maintenance). One entry
is returned per period with at least one source row, ordered by
start_time; pagination counts periods.
sources — the raw limits of each source for the period.computed_limits — the most restrictive limits across the sources:
the minimum of max_import_from_grid and of max_export_to_grid.max_import_from_grid / max_export_to_grid — always equal to
computed_limits; kept for readers from before sources existed.Optionally filter by sources (comma-separated or repeated); the
computed limits then use the given sources only.
site_id : str
System-generated unique site identifier.
params : SiteLimitsQueryParams
Required query parameters: from, to (max 31-day window).
Optional: sources, limit, offset.
service : SiteService
Injected via FastAPI dependency.
SiteLimitsResponse Paginated limit periods for the site.
| site_id required | string (Site Id) |
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
Array of Sources (strings) or Sources (null) (Sources) |
{- "limit": 0,
- "offset": 0,
- "limits": [
- {
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "max_import_from_grid": {
- "amount": "string",
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": "string",
- "unit": "MW"
}, - "delivery_day": "2019-08-24",
- "computed_limits": {
- "max_import_from_grid": {
- "amount": "string",
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": "string",
- "unit": "MW"
}
}, - "sources": [
- {
- "source": "REDISPATCH",
- "max_import_from_grid": {
- "amount": "string",
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": "string",
- "unit": "MW"
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}
]
}Upsert PoC limits for a site.
Each entry carries the source that sets it (default REDISPATCH)
and expands into one row per 15-minute period. Rows with a matching
(start_time, source) are overwritten; other sources and periods
outside the submitted set are left untouched. Returns 422 when two
entries of the request overlap on the same source.
site_id : str System-generated unique site identifier. body : PutSiteLimitsRequest List of limit periods to upsert. service : SiteService Injected via FastAPI dependency.
| site_id required | string (Site Id) |
required | Array of objects (Limits) non-empty |
{- "limits": [
- {
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "max_import_from_grid": {
- "amount": 0,
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": 0,
- "unit": "MW"
}, - "source": "REDISPATCH"
}
]
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Delete one source's PoC limits for a site within a time window.
Removes the source's limit periods whose start_time falls in
[start_time, end_time) (UTC, 15-minute boundaries, max 31-day
window). Other sources and periods outside the window are left
untouched; clearing a window with no stored periods is a no-op.
site_id : str
System-generated unique site identifier.
params : DeleteSiteLimitsQueryParams
Required query parameters: start_time, end_time (max 31-day
window) and source.
service : SiteService
Injected via FastAPI dependency.
| site_id required | string (Site Id) |
| start_time required | string <date-time> (Start Time) |
| end_time required | string <date-time> (End Time) |
| source required | string (SiteLimitSource) Enum: "REDISPATCH" "OPERATIONS" Who set a site limit. The values match :class:
|
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Add a new inverter to a site.
site_id : str System-generated unique site identifier. body : CreateSiteInverterRequest Inverter creation payload. service : SiteService Injected via FastAPI dependency.
SiteInverterResponse The created inverter record with a system-generated id.
| site_id required | string (Site Id) |
required | object (Quantity-Input) A physical amount paired with its unit. |
required | Charge Efficiency (number) or Charge Efficiency (string) (Charge Efficiency) |
required | Discharge Efficiency (number) or Discharge Efficiency (string) (Discharge Efficiency) |
| asset_ids required | Array of strings (Asset Ids) non-empty |
{- "rated_power": {
- "amount": 0,
- "unit": "MW"
}, - "charge_efficiency": 0,
- "discharge_efficiency": 0,
- "asset_ids": [
- "string"
]
}{- "id": "string",
- "site_id": "string",
- "rated_power": {
- "amount": "string",
- "unit": "MW"
}, - "charge_efficiency": "string",
- "discharge_efficiency": "string",
- "asset_ids": [
- "string"
], - "assets": [
- {
- "id": "string",
- "code": "string",
- "name": "string",
- "type": "BESS",
- "region": "DE",
- "delivery_area": "50HZ",
- "lifecycle": "DRAFT",
- "provider": "ENERGIEKOPPLER",
- "go_live_date": "2019-08-24",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Apply a partial update to a site inverter.
site_id : str System-generated unique site identifier. inverter_id : str System-generated unique inverter identifier. body : PatchSiteInverterRequest Fields to update; omitted fields are left untouched. service : SiteService Injected via FastAPI dependency.
| site_id required | string (Site Id) |
| inverter_id required | string (Inverter Id) |
Quantity (object) or null | |
Charge Efficiency (number) or Charge Efficiency (string) or Charge Efficiency (null) (Charge Efficiency) | |
Discharge Efficiency (number) or Discharge Efficiency (string) or Discharge Efficiency (null) (Discharge Efficiency) | |
Array of Asset Ids (strings) or Asset Ids (null) (Asset Ids) |
{- "rated_power": {
- "amount": 0,
- "unit": "MW"
}, - "charge_efficiency": 0,
- "discharge_efficiency": 0,
- "asset_ids": [
- "string"
]
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Delete a site inverter.
site_id : str System-generated unique site identifier. inverter_id : str System-generated unique inverter identifier. service : SiteService Injected via FastAPI dependency.
| site_id required | string (Site Id) |
| inverter_id required | string (Inverter Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return paginated limits for a site inverter within a time window.
site_id : str
System-generated unique site identifier.
inverter_id : str
System-generated unique inverter identifier.
params : SiteInverterLimitsQueryParams
Required query parameters: from, to (max 7-day window).
Optional: limit, offset.
service : SiteService
Injected via FastAPI dependency.
SiteInverterLimitsResponse Paginated limit periods for the inverter.
| site_id required | string (Site Id) |
| inverter_id required | string (Inverter Id) |
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "limit": 0,
- "offset": 0,
- "limits": [
- {
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "max_import_from_grid": {
- "amount": "string",
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": "string",
- "unit": "MW"
}
}
]
}Upsert limits for a site inverter.
Existing periods with a matching start_time are overwritten.
Periods outside the submitted set are left untouched.
site_id : str System-generated unique site identifier. inverter_id : str System-generated unique inverter identifier. body : PutSiteInverterLimitsRequest List of limit periods to upsert. service : SiteService Injected via FastAPI dependency.
| site_id required | string (Site Id) |
| inverter_id required | string (Inverter Id) |
required | Array of objects (Limits) non-empty |
{- "limits": [
- {
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "max_import_from_grid": {
- "amount": 0,
- "unit": "MW"
}, - "max_export_to_grid": {
- "amount": 0,
- "unit": "MW"
}
}
]
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Historical per-site dispatch commands (control mode, PoC and BESS setpoints). Read-only — writes happen via the event-driven ingestion worker, not over HTTP.
Return a paginated history of site dispatch commands.
Used by Operators to audit how co-location sites were driven — the control mode plus the PoC/BESS setpoints sent per delivery period.
params : SiteDispatchListQueryParams
Required filter site_ids plus from, to, limit, and
offset.
service : SiteDispatchService
Injected via FastAPI dependency.
SiteDispatchListResponse Matching site dispatch records with pagination metadata.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| site_ids required | Array of strings (Site Ids) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "dispatches": [
- {
- "source": "string",
- "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
- "published_at": "2019-08-24T14:15:22Z",
- "site_id": "string",
- "dispatch_time": "2019-08-24T14:15:22Z",
- "delivery_period_start": "2019-08-24T14:15:22Z",
- "control_mode": "PASSIVE",
- "bess_power": {
- "amount": "string",
- "unit": "MW"
}, - "poc_power": {
- "amount": "string",
- "unit": "MW"
}, - "power_imbalance": {
- "amount": "string",
- "unit": "MW"
}, - "soc_imbalance": {
- "amount": "string",
- "unit": "MW"
}
}
], - "limit": 0,
- "offset": 0
}Derived 15-minute operational facts per asset — energies, throughput meter readings, stored energy, availability, maintenance — computed from raw telemetry every five minutes and correctable via upsert. The shared source for warranty tracking and reporting.
Return derived 15-minute asset metrics.
asset_ids (comma-separated), from, and to are all
required; the window is half-open on start_time (UTC). Energies and
throughput meter readings are MWh quantities; availabilities are
fractions in [0, 1] — technical of each side's usable power
(SoC-edge tapers forgiven), commercial of rated power. Rows are derived from
telemetry every five minutes for the two most recently started
periods, so values younger than ~30 minutes may still be revised.
Returns 200 with an empty asset_metrics list when nothing
matches.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "limit": 0,
- "offset": 0,
- "asset_metrics": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "end_time": "2019-08-24T14:15:22Z",
- "stored_energy": {
- "amount": "string",
- "unit": "MW"
}, - "energy_charged": {
- "amount": "string",
- "unit": "MW"
}, - "energy_discharged": {
- "amount": "string",
- "unit": "MW"
}, - "charge_throughput": {
- "amount": "string",
- "unit": "MW"
}, - "discharge_throughput": {
- "amount": "string",
- "unit": "MW"
}, - "meter_energy_charged": {
- "amount": "string",
- "unit": "MW"
}, - "meter_energy_discharged": {
- "amount": "string",
- "unit": "MW"
}, - "technical_charge_availability": "string",
- "technical_discharge_availability": "string",
- "commercial_charge_availability": "string",
- "commercial_discharge_availability": "string",
- "charge_discharge_cycles": {
- "amount": "string",
- "unit": "CYCLES"
}, - "discharge_only_cycles": {
- "amount": "string",
- "unit": "CYCLES"
}, - "maintenance": "NONE",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "total": 0
}Upsert metric periods (manual corrections and virtual-asset ingest).
(asset_id, start_time) is the natural key; an existing
row is fully replaced with the provided values. Intended for
forcing correct values on settled periods when telemetry was wrong;
corrections inside the derivation lookback (~30 minutes) are
overwritten by the next derivation run by design.
Two callers use this endpoint:
DAA_SWAP_VBAT asset (EX-7859). A virtual battery has no
measurements, so its accepted and validated DAA-swap schedule is
its state: on every accepted submission customer-api writes one
row per D+1 delivery period for the virtual asset id. These rows
are scheduled state written at D-1, so unlike derived rows they
legitimately carry a start_time in the future, and they are
rewritten wholesale by a second-window resubmission. The
derivation worker never competes for them: DAA_SWAP_VBAT is
excluded from DERIVED_ASSET_TYPES and must stay that way.Returns 204 on success, 404 if a referenced asset does not exist, 422 when entries are invalid or duplicate the same period.
required | Array of objects (Asset Metrics) non-empty |
{- "asset_metrics": [
- {
- "asset_id": "string",
- "start_time": "2019-08-24T14:15:22Z",
- "stored_energy": {
- "amount": 0,
- "unit": "MW"
}, - "energy_charged": {
- "amount": 0,
- "unit": "MW"
}, - "energy_discharged": {
- "amount": 0,
- "unit": "MW"
}, - "charge_throughput": {
- "amount": 0,
- "unit": "MW"
}, - "discharge_throughput": {
- "amount": 0,
- "unit": "MW"
}, - "meter_energy_charged": {
- "amount": 0,
- "unit": "MW"
}, - "meter_energy_discharged": {
- "amount": 0,
- "unit": "MW"
}, - "technical_charge_availability": 0,
- "technical_discharge_availability": 0,
- "commercial_charge_availability": 0,
- "commercial_discharge_availability": 0,
- "maintenance": "NONE"
}
]
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Contractual cycling warranty constraints per asset — static (anchored warranty-year) and rolling (moving window) cycle limits. Terms are contract configuration; runtime tracking against them is a separate follow-up.
Return warranty terms across one or more assets.
asset_ids is required (comma-separated) — unbounded queries
across all assets are not permitted. status is accepted for
forward compatibility but is a no-op until warranty tracking is
implemented; for the same reason current_window is always
null in this iteration.
Returns 200 with an empty warranty_terms list when nothing
matches.
| asset_ids required | Array of strings (Asset Ids) non-empty |
ConstraintType (string) or Constraint Type (null) (Constraint Type) | |
Status (string) or Status (null) (Status) |
{- "warranty_terms": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "asset_id": "string",
- "constraint_type": "STATIC_CYCLING",
- "constraint_limit": {
- "amount": "string",
- "unit": "CYCLES"
}, - "constraint_window": {
- "amount": "string",
- "unit": "HOURS"
}, - "increment": {
- "amount": "string",
- "unit": "HOURS"
}, - "cycle_definition": "CHARGE_DISCHARGE",
- "warranty_start_date": "2019-08-24",
- "warranty_end_date": "2019-08-24",
- "alarm_threshold": "string",
- "initial_cycles": "string",
- "initial_cycles_as_of": "2019-08-24T14:15:22Z",
- "warranty_capacity": {
- "amount": "string",
- "unit": "MW"
}, - "current_window": null,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Create a warranty term for an asset.
The term is validated against the warranty contract:
STATIC_CYCLING terms derive anchored reset windows solely from
increment (1 YEARS = yearly reset, 1 DAYS = daily reset
per German trading day, which is 23 or 25 hours on DST switch days;
no constraint_window); ROLLING_CYCLING terms require a
constraint_window that is a positive multiple of increment
(both in HOURS/MINUTES, fixed durations). Quantity units
are stored and echoed back verbatim.
warranty_start_date and warranty_end_date are both
inclusive trading days: a term from 2026-01-01 to
2026-12-31 covers every delivery period of 2026, Berlin time.
warranty_capacity (optional, MWh) is the capacity the contract
counts cycles against; without it the asset spec's
max_capacity is used.
Returns 201 with the created resource and a Location header,
404 if the referenced asset_id does not exist, 422 if the term
configuration is invalid.
| asset_id required | string (Asset Id) [ 1 .. 128 ] characters |
| constraint_type required | string (ConstraintType) Enum: "STATIC_CYCLING" "ROLLING_CYCLING" Controlled vocabulary of warranty constraint behaviours. |
required | object (CycleQuantity-Input) A cycle amount paired with its (fixed) unit. |
WindowQuantity (object) or null | |
required | object (IncrementQuantity-Input) A tracking increment paired with its contractual unit. |
| cycle_definition required | string (CycleDefinition) Enum: "CHARGE_DISCHARGE" "DISCHARGE_ONLY" Controlled vocabulary of equivalent-cycle calculation methods. Different OEM contracts define "one cycle" differently; the member makes the method explicit and auditable per term.
|
| warranty_start_date required | string <date> (Warranty Start Date) First German trading day covered by the warranty (inclusive). Tracking windows are anchored at the start of this day, Berlin time. |
Warranty End Date (string) or Warranty End Date (null) (Warranty End Date) Last German trading day covered by the warranty (inclusive): the term covers every delivery period up to the end of this day, Berlin time. Equal to warranty_start_date for a single-day term. null means open-ended. | |
Alarm Threshold (number) or Alarm Threshold (string) (Alarm Threshold) Default: "0.97" | |
Initial Cycles (number) or Initial Cycles (string) (Initial Cycles) Default: "0" | |
Initial Cycles As Of (string) or Initial Cycles As Of (null) (Initial Cycles As Of) | |
Quantity (object) or null Capacity in MWh that the warranty contract divides energy by to count cycles. When null, the asset spec's max_capacity valid at each period is used. Amending it reprices the in-progress window from its start on the next evaluation; windows already finished keep their stored usage. |
{- "asset_id": "string",
- "constraint_type": "STATIC_CYCLING",
- "constraint_limit": {
- "amount": 0,
- "unit": "CYCLES"
}, - "constraint_window": {
- "amount": 0,
- "unit": "HOURS"
}, - "increment": {
- "amount": 1,
- "unit": "HOURS"
}, - "cycle_definition": "CHARGE_DISCHARGE",
- "warranty_start_date": "2019-08-24",
- "warranty_end_date": "2019-08-24",
- "alarm_threshold": "0.97",
- "initial_cycles": "0",
- "initial_cycles_as_of": "2019-08-24T14:15:22Z",
- "warranty_capacity": {
- "amount": 0,
- "unit": "MW"
}
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "asset_id": "string",
- "constraint_type": "STATIC_CYCLING",
- "constraint_limit": {
- "amount": "string",
- "unit": "CYCLES"
}, - "constraint_window": {
- "amount": "string",
- "unit": "HOURS"
}, - "increment": {
- "amount": "string",
- "unit": "HOURS"
}, - "cycle_definition": "CHARGE_DISCHARGE",
- "warranty_start_date": "2019-08-24",
- "warranty_end_date": "2019-08-24",
- "alarm_threshold": "string",
- "initial_cycles": "string",
- "initial_cycles_as_of": "2019-08-24T14:15:22Z",
- "warranty_capacity": {
- "amount": "string",
- "unit": "MW"
}, - "current_window": null,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Return a single warranty term by id.
Returns 404 if no term exists with the given id.
| warranty_term_id required | string <uuid> (Warranty Term Id) |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "asset_id": "string",
- "constraint_type": "STATIC_CYCLING",
- "constraint_limit": {
- "amount": "string",
- "unit": "CYCLES"
}, - "constraint_window": {
- "amount": "string",
- "unit": "HOURS"
}, - "increment": {
- "amount": "string",
- "unit": "HOURS"
}, - "cycle_definition": "CHARGE_DISCHARGE",
- "warranty_start_date": "2019-08-24",
- "warranty_end_date": "2019-08-24",
- "alarm_threshold": "string",
- "initial_cycles": "string",
- "initial_cycles_as_of": "2019-08-24T14:15:22Z",
- "warranty_capacity": {
- "amount": "string",
- "unit": "MW"
}, - "current_window": null,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Apply a partial update to one warranty term (merge-patch semantics).
Amendable fields: constraint_limit, warranty_end_date
(last covered trading day, inclusive; null makes the term
open-ended again), alarm_threshold, initial_cycles /
initial_cycles_as_of, and warranty_capacity (null falls
back to the spec's max_capacity). Only fields present in the
request body are touched. All other fields are immutable — they
define how tracking windows are derived, so changing them would
retroactively re-anchor the term; delete and recreate instead. The
merged term is re-validated against the same contract as creation.
An amendment reprices the in-progress window from its start on the next evaluation run. Finished windows keep their stored usage.
Returns 204 on success, 404 if no term exists with the given id, 422 if an immutable or unknown field is sent or the merged term would violate the warranty term contract.
| warranty_term_id required | string <uuid> (Warranty Term Id) |
CycleQuantity (object) or null | |
Warranty End Date (string) or Warranty End Date (null) (Warranty End Date) Last German trading day covered by the warranty (inclusive): the term covers every delivery period up to the end of this day, Berlin time. Equal to warranty_start_date for a single-day term. null means open-ended. | |
Alarm Threshold (number) or Alarm Threshold (string) or Alarm Threshold (null) (Alarm Threshold) | |
Initial Cycles (number) or Initial Cycles (string) or Initial Cycles (null) (Initial Cycles) | |
Initial Cycles As Of (string) or Initial Cycles As Of (null) (Initial Cycles As Of) | |
Quantity (object) or null Capacity in MWh that the warranty contract divides energy by to count cycles. When null, the asset spec's max_capacity valid at each period is used. Amending it reprices the in-progress window from its start on the next evaluation; windows already finished keep their stored usage. |
{- "constraint_limit": {
- "amount": 0,
- "unit": "CYCLES"
}, - "warranty_end_date": "2019-08-24",
- "alarm_threshold": 0,
- "initial_cycles": 0,
- "initial_cycles_as_of": "2019-08-24T14:15:22Z",
- "warranty_capacity": {
- "amount": 0,
- "unit": "MW"
}
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Delete one warranty term by id.
Intended for correcting configuration mistakes. Ending a warranty
contractually should instead set warranty_end_date via
PATCH, which preserves the term. Returns 404 if no term
exists with the given id.
| warranty_term_id required | string <uuid> (Warranty Term Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Return evaluated warranty tracking windows.
asset_ids (comma-separated), from, and to are required;
the window is half-open on window_start (UTC).
warranty_term_ids narrows to specific terms and status
filters on the derived status (e.g. BREACHED for every window
where a warranty limit was exceeded). Each window appears once per
calculation basis (SOC, THROUGHPUT) with consumed cycles,
the term's limit and alarm threshold, utilization, status, and the
metric-period coverage counts.
There is no write endpoint: usage is derived data — correct telemetry or asset metrics and replay the evaluation instead.
Returns 200 with an empty warranty_usage list when nothing
matches.
| limit | integer (Limit) [ 1 .. 1000 ] Default: 50 |
| offset | integer (Offset) >= 0 Default: 0 |
| asset_ids required | Array of strings (Asset Ids) non-empty |
Array of Warranty Term Ids (strings) or Warranty Term Ids (null) (Warranty Term Ids) | |
UsageStatus (string) or Status (null) (Status) | |
| from required | string <date-time> (From) |
| to required | string <date-time> (To) |
{- "limit": 0,
- "offset": 0,
- "warranty_usage": [
- {
- "warranty_term_id": "2ab35ff6-0064-4c14-8614-e28f0cdc9bf4",
- "asset_id": "string",
- "window_start": "2019-08-24T14:15:22Z",
- "window_end": "2019-08-24T14:15:22Z",
- "basis": "SOC",
- "cycles_consumed": {
- "amount": "string",
- "unit": "CYCLES"
}, - "cycle_limit": {
- "amount": "string",
- "unit": "CYCLES"
}, - "alarm_threshold": "string",
- "utilization": "string",
- "status": "OK",
- "periods_with_data": 0,
- "periods_expected": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
], - "total": 0
}Create an adapter config with monitoring and control disabled.
A config is created once the provider's own id for the target is known. Returns 201 with the created config, 404 if the target is neither a site nor an asset, 409 if the target already has a config for the provider, 422 if the target is an asset of a site or the provider has no adapter.
body : CreateAdapterConfigRequest Target, provider and optional external id. service : AdapterConfigService Injected via FastAPI dependency.
AdapterConfigResponse The created config.
| target_id required | string (Target Id) [ 1 .. 128 ] characters Site id, or id of an asset that belongs to no site. |
| provider required | string (Provider) Enum: "ENERGIEKOPPLER" "ENTELIOS" "EBX" "TERRALAYR" "TRANSITION_TECHNOLOGIES" "ASSET_SIMULATOR" "NFT" "TESVOLT" "PSE_WIRE" Energy market providers. |
| external_id required | string (External Id) [ 1 .. 256 ] characters The provider's own id for the target. |
{- "target_id": "string",
- "provider": "ENERGIEKOPPLER",
- "external_id": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "target_id": "string",
- "provider": "ENERGIEKOPPLER",
- "external_id": "string",
- "monitoring_enabled": true,
- "control_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Return adapter configs matching the filters.
A target_id naming an asset of a site returns its site's configs.
params : AdapterConfigListQueryParams Filters and pagination. service : AdapterConfigService Injected via FastAPI dependency.
AdapterConfigListResponse The matching configs, ordered by target and provider.
Target Id (string) or Target Id (null) (Target Id) | |
Provider (string) or Provider (null) (Provider) | |
Monitoring Enabled (boolean) or Monitoring Enabled (null) (Monitoring Enabled) | |
Control Enabled (boolean) or Control Enabled (null) (Control Enabled) | |
| limit | integer (Limit) [ 1 .. 1000 ] Default: 100 |
| offset | integer (Offset) >= 0 Default: 0 |
{- "limit": 0,
- "offset": 0,
- "adapter_configs": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "target_id": "string",
- "provider": "ENERGIEKOPPLER",
- "external_id": "string",
- "monitoring_enabled": true,
- "control_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}Return one adapter config.
config_id : uuid.UUID Config id. service : AdapterConfigService Injected via FastAPI dependency.
AdapterConfigResponse The config.
| config_id required | string <uuid> (Config Id) |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "target_id": "string",
- "provider": "ENERGIEKOPPLER",
- "external_id": "string",
- "monitoring_enabled": true,
- "control_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Change only the fields sent: external id, monitoring and control flags.
No field accepts null. The control runs dispatch from
control_enabled, so patching it changes control, but it leaves the
Parameter Store fallback list as it is:
PUT /asset/v1/asset-actions/{target_id}/control changes both and is
the way to switch control; patching the flag is for filling or correcting
the table. Returns 204, 404 if no config has the
id or its target no longer exists, 422 when enabling control for a
provider that is not controllable or an asset that cannot be controlled
on its own.
config_id : uuid.UUID Config id. body : PatchAdapterConfigRequest Fields to change. service : AdapterConfigService Injected via FastAPI dependency.
| config_id required | string <uuid> (Config Id) |
External Id (string) or External Id (null) (External Id) The provider's own id for the target. | |
Monitoring Enabled (boolean) or Monitoring Enabled (null) (Monitoring Enabled) | |
Control Enabled (boolean) or Control Enabled (null) (Control Enabled) The control runs dispatch the rows with this flag set. Patching it leaves the Parameter Store fallback list as it is; use the control action to switch control. |
{- "external_id": "string",
- "monitoring_enabled": true,
- "control_enabled": true
}{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}Delete an adapter config, whatever its flags.
Stops control for the target, since the control runs dispatch from the rows; the Parameter Store fallback list is left as it is. Returns 204, or 404 if no config has the id.
config_id : uuid.UUID Config id. service : AdapterConfigService Injected via FastAPI dependency.
| config_id required | string <uuid> (Config Id) |
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string",
- "input": null,
- "ctx": { }
}
]
}