Asset Service API (0.1.0)

Download OpenAPI specification:

Status

Latest operational status per asset (e.g. online/offline, mode).

Get Status List

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.

Parameters

params : StatusGetQueryParams Validated query parameters including asset_ids, latest, from/to, limit, offset, and optional status filter. service : StatusService Injected via FastAPI dependency.

Returns

StatusListResponse Paginated status entries for the requested assets.

Authorizations:
entrixOAuth
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
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "statuses": [
    ]
}

Get Status Locks

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.

Parameters

params : GetStatusLocksQueryParams Validated query parameters: asset_ids, active, limit, offset. service : StatusLockService Injected via FastAPI dependency.

Returns

GetStatusLocksResponse Paginated status lock rows for the requested assets.

Authorizations:
entrixOAuth
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
active
boolean (Active)
Default: false

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "status_locks": [
    ]
}

Get Status Lock Exclusions

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.

Returns

GetStatusLockExclusionsResponse The current exclusion list with each entry's creation time.

Authorizations:
entrixOAuth

Responses

Response samples

Content type
application/json
{
  • "exclusions": [
    ]
}

Put Status Lock Exclusions

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.

Parameters

request : PutStatusLockExclusionsRequest Asset ids and the desired exclusion state. service : StatusLockService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
asset_ids
required
Array of strings (Asset Ids) non-empty
excluded
required
boolean (Excluded)

Responses

Request samples

Content type
application/json
{
  • "asset_ids": [
    ],
  • "excluded": true
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Assets

Asset master records — create, list, fetch, update.

Create Asset

Create a new asset master record.

Parameters

body : CreateAssetRequest Asset creation payload. service : AssetService Injected via FastAPI dependency.

Returns

AssetResponse The created asset master record with a system-generated asset_id.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "name": "string",
  • "type": "BESS",
  • "region": "DE",
  • "delivery_area": "50HZ",
  • "provider": "ENERGIEKOPPLER"
}

Response samples

Content type
application/json
{
  • "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"
}

List Assets

Return all asset master records with optional filters.

Parameters

params : AssetListQueryParams Optional query parameters: type, region, lifecycle. service : AssetService Injected via FastAPI dependency.

Returns

AssetListResponse Matching asset master records.

Authorizations:
entrixOAuth
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "assets": [
    ]
}

Get Asset

Return a single asset master record by asset_id.

Parameters

asset_id : str System-generated unique asset identifier (e.g. DE_50HZ_WU_1). service : AssetService Injected via FastAPI dependency.

Returns

AssetResponse The matching asset master record.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "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"
}

Patch Asset

Apply a partial update to an asset master record.

Only provided fields are applied. Lifecycle transitions must use the dedicated asset-actions endpoints.

Parameters

asset_id : str System-generated unique asset identifier. body : PatchAssetRequest Fields to update; omitted fields are left untouched. service : AssetService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)
Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "BESS",
  • "go_live_date": "2019-08-24",
  • "provider": "ENERGIEKOPPLER"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Asset

Delete an asset master record.

Deletion is only permitted for assets in the draft lifecycle state; any other state answers 409.

Parameters

asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Asset Status

Return the latest operational status of an asset.

Parameters

asset_id : str Unique identifier of the asset (e.g. DE_50HZ_DK_1). service : StatusService Injected via FastAPI dependency.

Returns

AssetStatusEntry Latest status entry for the asset.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "asset_id": "string",
  • "status": "UNKNOWN",
  • "effective_at": "2019-08-24T14:15:22Z",
  • "reasons": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Features Quotas

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).

Get Limitations Usage

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.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)
query Parameters
customer_name
required
string (Customer Name) non-empty
Year (integer) or Year (null) (Year)

Responses

Response samples

Content type
application/json
{
  • "asset_id": "string",
  • "customer_name": "string",
  • "year": 0,
  • "total_utilized_periods": 0,
  • "max_allowed_periods": 0,
  • "red_button_used": 0,
  • "red_button_max": 0
}

Get Limitations History

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.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)
query Parameters
customer_name
required
string (Customer Name) non-empty
from
required
string <date-time> (From)
to
required
string <date-time> (To)

Responses

Response samples

Content type
application/json
{
  • "limitations": [
    ]
}

Get Customer Events

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).

Authorizations:
entrixOAuth
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "events": [
    ]
}

Get Reservations Usage

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.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)
query Parameters
customer_name
required
string (Customer Name) non-empty
Year (integer) or Year (null) (Year)

Responses

Response samples

Content type
application/json
{
  • "asset_id": "string",
  • "customer_name": "string",
  • "year": 0,
  • "total_reservations": 0
}

Get Reservations History

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.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)
query Parameters
customer_name
required
string (Customer Name) non-empty
from
required
string <date-time> (From)
to
required
string <date-time> (To)

Responses

Response samples

Content type
application/json
{
  • "reserved_days": [
    ]
}

Asset Actions

Lifecycle transitions (commission, decommission, etc.). Each endpoint covers exactly one transition between adjacent lifecycle states.

Commission Asset

Transition the asset from DRAFT to COMMISSIONING.

Parameters

asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Go Live Asset

Transition the asset from COMMISSIONING to LIVE.

Sets go_live_date to today (UTC) if it is not already set.

Parameters

asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Suspend Asset

Transition the asset from LIVE to SUSPENDED.

Parameters

asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Resume Asset

Transition the asset from SUSPENDED back to LIVE.

Parameters

asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Decommission Asset

Transition the asset from LIVE to DECOMMISSIONED.

Parameters

asset_id : str System-generated unique asset identifier. service : AssetService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Unlock Asset Status

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.

Parameters

asset_id : str System-generated unique asset identifier. service : StatusLockService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
asset_id
required
string (Asset Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Set Dispatch Control

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.

Parameters

target_id : str Site id or asset id to control. body : ControlRequest The desired enabled state. service : AssetControlService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
target_id
required
string (Target Id)
Request Body schema: application/json
required
enabled
required
boolean (Enabled)

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Asset Dispatches

Historical per-asset dispatch commands. Read-only — writes happen via the event-driven ingestion worker, not over HTTP.

List Dispatches

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).

Parameters

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.

Returns

DispatchListResponse Matching dispatch records with pagination metadata.

Authorizations:
entrixOAuth
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 Sources (strings) or Sources (null) (Sources)

Responses

Response samples

Content type
application/json
{
  • "dispatches": [
    ],
  • "limit": 0,
  • "offset": 0
}

State Snapshots

Stored-energy state-of-charge snapshots (read latest / time-range, plus upsert).

Create State Snapshots

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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
required
Array of objects (State Snapshots) non-empty

Responses

Request samples

Content type
application/json
{
  • "state_snapshots": [
    ]
}

Response samples

Content type
application/json
{
  • "state_snapshots": [
    ]
}

Get State Snapshots

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.

Authorizations:
entrixOAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "state_snapshots": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "total_charged_energy": {
    },
  • "total_discharged_energy": {
    }
}

Limits

Period limits per asset per 15-min slot — charge/discharge power, energy bands, trading lock. Multi-source with computed most-restrictive values.

Upsert Limits

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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
required
Array of objects (Limits) non-empty

Responses

Request samples

Content type
application/json
{
  • "limits": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Limits

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).

Authorizations:
entrixOAuth
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 Sources (strings) or Sources (null) (Sources)
enforce_trade_blocked
boolean (Enforce Trade Blocked)
Default: true

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "limits": [
    ]
}

Delete Limits

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.
  • Rows that end up with no contribution at all (all four constraints 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.

Authorizations:
entrixOAuth
query Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Forecasts

Forecasted generation/consumption per asset per period.

Upsert Forecasts

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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
required
Array of objects (Forecasts) non-empty

Responses

Request samples

Content type
application/json
{
  • "forecasts": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Forecasts

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).

Authorizations:
entrixOAuth
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "forecasts": [
    ]
}

Reservations

Net market positions per (asset, period, market, source) — from optimisation, external sources, or DAA swaps.

Upsert Reservations

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.

Authorizations:
entrixOAuth
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
Request Body schema: application/json
required
One of
mode
string (Mode)
Default: "overwrite"
Value: "overwrite"
required
Array of objects (Reservations) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
Example
{
  • "mode": "overwrite",
  • "reservations": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Reservations

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).

Authorizations:
entrixOAuth
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "reservations": [
    ]
}

Specs

Versioned technical specifications per asset.

Upsert Spec

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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "asset_id": "string",
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_to": "2019-08-24T14:15:22Z",
  • "rated_power": {
    },
  • "usable_charge_power": {
    },
  • "usable_discharge_power": {
    },
  • "grid_connection_max_power": {
    },
  • "max_capacity": {
    },
  • "ramp_rate": 0,
  • "ramp_type": "string",
  • "charge_efficiency": 0,
  • "discharge_efficiency": 0,
  • "daily_cycle_energy_limit": {
    },
  • "prequalified_fcr": {
    },
  • "prequalified_afrr_charge": {
    },
  • "prequalified_afrr_discharge": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Specs

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.

Authorizations:
entrixOAuth
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
latest
boolean (Latest)
Default: false
active
boolean (Active)
Default: false
From (string) or From (null) (From)
To (string) or To (null) (To)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "specs": [
    ]
}

Telemetry

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.

Write Telemetry

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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
required
Array of objects (Telemetry) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "telemetry": [
    ]
}

Response samples

Content type
application/json
{
  • "received": 0,
  • "written": 0,
  • "rejected": 0,
  • "errors": [
    ]
}

Get Telemetry

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.

Parameters

params : GetTelemetryQueryParams Required filter asset_ids plus either latest=true or from/to, and optional limit and offset. service : TelemetryService Injected via FastAPI dependency.

Returns

GetTelemetryResponse Matching telemetry rows with pagination metadata.

Authorizations:
entrixOAuth
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
latest
boolean (Latest)
Default: false
From (string) or From (null) (From)
To (string) or To (null) (To)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "telemetry": [
    ]
}

FCA

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 Rule

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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
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.

CAP is a restriction ("at most this much") — caps combine most-restrictively, protecting the grid. FLOOR is a guarantee ("at least this much, whatever the caps say") — floors are applied after the caps and only ever widen the envelope back up to the guaranteed level, protecting the asset owner. A floor with no applicable cap writes nothing: FCA limits are restrictions, and a guarantee alone has nothing to prop open.

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

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "metric": {
    },
  • "power_curve": {
    },
  • "role": "CAP",
  • "active_window": {
    },
  • "zones": [
    ],
  • "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
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Rules

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).

Authorizations:
entrixOAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "rules": [
    ]
}

Patch Rule

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.

Authorizations:
entrixOAuth
path Parameters
rule_id
required
string <uuid> (Rule Id)
Request Body schema: application/json
required
enabled
required
boolean (Enabled)

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Rule

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.

Authorizations:
entrixOAuth
path Parameters
rule_id
required
string <uuid> (Rule Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Evaluations

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.

Authorizations:
entrixOAuth
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)
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

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "evaluations": [
    ]
}

Sites

Site master data and per-site inverter configuration.

Create Site

Create a new site record.

Parameters

body : CreateSiteRequest Site creation payload. service : SiteService Injected via FastAPI dependency.

Returns

SiteResponse The created site record with a system-generated id.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "region": "DE",
  • "delivery_area": "50HZ",
  • "type": "STANDALONE_BESS",
  • "dso": "string",
  • "dispatch_mode": {
    },
  • "daa_swap": {
    },
  • "max_import_from_grid": {
    },
  • "max_export_to_grid": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "code": "string",
  • "region": "DE",
  • "delivery_area": "50HZ",
  • "type": "STANDALONE_BESS",
  • "dso": "string",
  • "dispatch_mode": {
    },
  • "daa_swap": {
    },
  • "max_import_from_grid": {
    },
  • "max_export_to_grid": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "inverters": [
    ]
}

List Sites

Return all site records with optional filters.

Parameters

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.

Returns

SiteListResponse Matching site records.

Authorizations:
entrixOAuth
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "sites": [
    ]
}

Get Site

Return a single site record by site_id.

Parameters

site_id : str System-generated unique site identifier (e.g. DE_AMPN_IMMST_SITE_1). service : SiteService Injected via FastAPI dependency.

Returns

SiteResponse The matching site record with its inverters embedded, each listing the attached assets (assets) next to their ids.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "code": "string",
  • "region": "DE",
  • "delivery_area": "50HZ",
  • "type": "STANDALONE_BESS",
  • "dso": "string",
  • "dispatch_mode": {
    },
  • "daa_swap": {
    },
  • "max_import_from_grid": {
    },
  • "max_export_to_grid": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "inverters": [
    ]
}

Patch Site

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.

Parameters

site_id : str System-generated unique site identifier. body : PatchSiteRequest Fields to update; omitted fields are left untouched. service : SiteService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "dso": "string",
  • "daa_swap": {
    },
  • "dispatch_mode_name": "BESS_ONLY",
  • "dispatch_mode_floor_price": {
    },
  • "dispatch_mode_strike_price": {
    },
  • "max_import_from_grid": {
    },
  • "max_export_to_grid": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Site

Delete a site record.

Parameters

site_id : str System-generated unique site identifier. service : SiteService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Site Limits

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.

Parameters

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.

Returns

SiteLimitsResponse Paginated limit periods for the site.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "limits": [
    ]
}

Put Site Limits

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.

Parameters

site_id : str System-generated unique site identifier. body : PutSiteLimitsRequest List of limit periods to upsert. service : SiteService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
Request Body schema: application/json
required
required
Array of objects (Limits) non-empty

Responses

Request samples

Content type
application/json
{
  • "limits": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Site Limits

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.

Parameters

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.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
query Parameters
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:app.schemas.limit.LimitSource; sites accept a subset of it.

  • REDISPATCH — the DSO redispatch sync: the static PoC limits with the current curtailment applied (0 % curtailment writes the static limits).
  • OPERATIONS — operational restrictions such as site maintenance.

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Add Site Inverter

Add a new inverter to a site.

Parameters

site_id : str System-generated unique site identifier. body : CreateSiteInverterRequest Inverter creation payload. service : SiteService Injected via FastAPI dependency.

Returns

SiteInverterResponse The created inverter record with a system-generated id.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "rated_power": {
    },
  • "charge_efficiency": 0,
  • "discharge_efficiency": 0,
  • "asset_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "site_id": "string",
  • "rated_power": {
    },
  • "charge_efficiency": "string",
  • "discharge_efficiency": "string",
  • "asset_ids": [
    ],
  • "assets": [
    ]
}

Patch Site Inverter

Apply a partial update to a site inverter.

Parameters

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.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
inverter_id
required
string (Inverter Id)
Request Body schema: application/json
required
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)

Responses

Request samples

Content type
application/json
{
  • "rated_power": {
    },
  • "charge_efficiency": 0,
  • "discharge_efficiency": 0,
  • "asset_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Site Inverter

Delete a site inverter.

Parameters

site_id : str System-generated unique site identifier. inverter_id : str System-generated unique inverter identifier. service : SiteService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
inverter_id
required
string (Inverter Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Site Inverter Limits

Return paginated limits for a site inverter within a time window.

Parameters

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.

Returns

SiteInverterLimitsResponse Paginated limit periods for the inverter.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
inverter_id
required
string (Inverter Id)
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "limits": [
    ]
}

Put Site Inverter Limits

Upsert limits for a site inverter.

Existing periods with a matching start_time are overwritten. Periods outside the submitted set are left untouched.

Parameters

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.

Authorizations:
entrixOAuth
path Parameters
site_id
required
string (Site Id)
inverter_id
required
string (Inverter Id)
Request Body schema: application/json
required
required
Array of objects (Limits) non-empty

Responses

Request samples

Content type
application/json
{
  • "limits": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Site Dispatches

Historical per-site dispatch commands (control mode, PoC and BESS setpoints). Read-only — writes happen via the event-driven ingestion worker, not over HTTP.

List Site Dispatches

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.

Parameters

params : SiteDispatchListQueryParams Required filter site_ids plus from, to, limit, and offset. service : SiteDispatchService Injected via FastAPI dependency.

Returns

SiteDispatchListResponse Matching site dispatch records with pagination metadata.

Authorizations:
entrixOAuth
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "dispatches": [
    ],
  • "limit": 0,
  • "offset": 0
}

Asset Metrics

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.

Get Asset Metrics

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.

Authorizations:
entrixOAuth
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "asset_metrics": [
    ],
  • "total": 0
}

Upsert Asset Metrics

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:

  • Operators, correcting settled periods of a telemetry-derived asset (the original purpose).
  • customer-api, ingesting the scheduled state of a 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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
required
Array of objects (Asset Metrics) non-empty

Responses

Request samples

Content type
application/json
{
  • "asset_metrics": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Warranties

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.

Get Warranty Terms

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.

Authorizations:
entrixOAuth
query Parameters
asset_ids
required
Array of strings (Asset Ids) non-empty
ConstraintType (string) or Constraint Type (null) (Constraint Type)
Status (string) or Status (null) (Status)

Responses

Response samples

Content type
application/json
{
  • "warranty_terms": [
    ]
}

Create Warranty Term

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.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
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.

  • CHARGE_DISCHARGE — full equivalent cycles: (charged + discharged) / (2 * capacity)
  • DISCHARGE_ONLY — cycles counted on discharge only: discharged / capacity

capacity is the term's warranty_capacity when set, else the asset spec's max_capacity.

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.

Responses

Request samples

Content type
application/json
{
  • "asset_id": "string",
  • "constraint_type": "STATIC_CYCLING",
  • "constraint_limit": {
    },
  • "constraint_window": {
    },
  • "increment": {
    },
  • "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": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "asset_id": "string",
  • "constraint_type": "STATIC_CYCLING",
  • "constraint_limit": {
    },
  • "constraint_window": {
    },
  • "increment": {
    },
  • "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": {
    },
  • "current_window": null,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Warranty Term

Return a single warranty term by id.

Returns 404 if no term exists with the given id.

Authorizations:
entrixOAuth
path Parameters
warranty_term_id
required
string <uuid> (Warranty Term Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "asset_id": "string",
  • "constraint_type": "STATIC_CYCLING",
  • "constraint_limit": {
    },
  • "constraint_window": {
    },
  • "increment": {
    },
  • "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": {
    },
  • "current_window": null,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Patch Warranty Term

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.

Authorizations:
entrixOAuth
path Parameters
warranty_term_id
required
string <uuid> (Warranty Term Id)
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "constraint_limit": {
    },
  • "warranty_end_date": "2019-08-24",
  • "alarm_threshold": 0,
  • "initial_cycles": 0,
  • "initial_cycles_as_of": "2019-08-24T14:15:22Z",
  • "warranty_capacity": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Warranty Term

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.

Authorizations:
entrixOAuth
path Parameters
warranty_term_id
required
string <uuid> (Warranty Term Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Warranty Usage

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.

Authorizations:
entrixOAuth
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
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)

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "warranty_usage": [
    ],
  • "total": 0
}

Adapter Configs

Create Adapter Config

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.

Parameters

body : CreateAdapterConfigRequest Target, provider and optional external id. service : AdapterConfigService Injected via FastAPI dependency.

Returns

AdapterConfigResponse The created config.

Authorizations:
entrixOAuth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "target_id": "string",
  • "provider": "ENERGIEKOPPLER",
  • "external_id": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

List Adapter Configs

Return adapter configs matching the filters.

A target_id naming an asset of a site returns its site's configs.

Parameters

params : AdapterConfigListQueryParams Filters and pagination. service : AdapterConfigService Injected via FastAPI dependency.

Returns

AdapterConfigListResponse The matching configs, ordered by target and provider.

Authorizations:
entrixOAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "adapter_configs": [
    ]
}

Get Adapter Config

Return one adapter config.

Parameters

config_id : uuid.UUID Config id. service : AdapterConfigService Injected via FastAPI dependency.

Returns

AdapterConfigResponse The config.

Authorizations:
entrixOAuth
path Parameters
config_id
required
string <uuid> (Config Id)

Responses

Response samples

Content type
application/json
{
  • "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"
}

Patch Adapter Config

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.

Parameters

config_id : uuid.UUID Config id. body : PatchAdapterConfigRequest Fields to change. service : AdapterConfigService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
config_id
required
string <uuid> (Config Id)
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "monitoring_enabled": true,
  • "control_enabled": true
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Adapter Config

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.

Parameters

config_id : uuid.UUID Config id. service : AdapterConfigService Injected via FastAPI dependency.

Authorizations:
entrixOAuth
path Parameters
config_id
required
string <uuid> (Config Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Health

Return service health status.

Returns

dict[str, str] A mapping {"status": "ok"} when the service is running.

Authorizations:
entrixOAuth

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}