flexmeasures.api.v3_0.assets

Classes

class flexmeasures.api.v3_0.assets.AssetAPI

This API view exposes generic assets.

— get:

summary: Return all sensors under an asset. description: |

This endpoint returns all sensors under an asset.

The endpoint supports pagination of the asset list using the page and per_page query parameters.

If the page parameter is not provided, all sensors are returned, without pagination information. The result will be a list of sensors.

If a page parameter is provided, the response will be paginated, showing a specific number of assets per page as defined by per_page (default is 10).

The response schema for pagination is inspired by https://datatables.net/manual/server-side#Returned-data

security:

ApiKeyAuth: []

parameters:

in: path name: id description: ID of the asset to fetch sensors for schema:

type: integer

in: query schema: AssetPaginationSchema

responses:

200:
description: PROCESSED content:

application/json:

examples:

single_asset:
summary: One asset being returned in the response value:

data: - id: 1

name: Test battery latitude: 10 longitude: 100 account_id: 2 generic_asset_type:

id: 1 name: battery

paginated_assets:
summary: A paginated list of assets being returned in the response value:

data: - id: 1

name: Test battery latitude: 10 longitude: 100 account_id: 2 generic_asset_type:

id: 1 name: battery

num-records: 1 filtered-records: 1

400:
description: INVALID_REQUEST

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

— get:

summary: Get history of asset related actions. description: |

The endpoint is paginated and supports search filters.

If the page parameter is not provided, all audit logs are returned paginated by per_page (default is 10).

If a page parameter is provided, the response will be paginated, showing a specific number of assets per page as defined by per_page (default is 10).

If sort_by (field name) and sort_dir (“asc” or “desc”) are provided, the list will be sorted.

If a search ‘filter’ is provided, the response will filter out audit logs where each search term is either present in the event or active user name. The response schema for pagination is inspired by [DataTables](https://datatables.net/manual/server-side)

security:

ApiKeyAuth: []

parameters:

in: path name: id required: true description: ID of the asset to get the history for. schema:

type: integer

in: query schema: AssetAuditLogPaginationSchema

responses:

200:
description: PROCESSED content:

application/json:

schema:
type: object examples:

pagination:
summary: Pagination response value:

data:

event: Asset test asset deleted event_datetime: “2021-01-01T00:00:00” active_user_name: ‘Test user’

num_records: 1, filtered_records: 1

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

delete(id: int, asset: GenericAsset)

— delete:

summary: Delete an asset. description: This endpoint deletes an existing asset, as well as all sensors and measurements recorded for it. security:

ApiKeyAuth: []

parameters:

in: path name: id description: ID of the asset to delete. schema:

type: integer

responses:

204:
description: DELETED

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

fetch_one(id, asset)

— get:

summary: Fetch a given asset. description: This endpoint gets an asset. security:

ApiKeyAuth: []

parameters:

in: path name: id description: ID of the asset to fetch. schema:

type: integer

responses:

200:
description: PROCESSED content:

application/json:

examples:

single_asset:
summary: One asset being returned in the response value:

generic_asset_type_id: 2 name: Test battery id: 1 latitude: 10 longitude: 100 account_id: 1

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

get_chart(id: int, asset: GenericAsset, **kwargs)

— get:

summary: Download an embeddable chart with time series data description: |

This endpoint returns a chart with time series for an asset.

The response contains the HTML and JavaScript needed to embedded and render the chart in an HTML page. This is used by the FlexMeasures UI.

To learn how to embed the response in your web page, see [this section](https://flexmeasures.readthedocs.io/latest/tut/building_uis.html#embedding-charts) in the developer documentation.

security:

ApiKeyAuth: []

parameters:

in: path name: id description: ID of the asset to download a chart for. schema:

type: integer

in: query schema: AssetChartKwargsSchema

responses:

200:
description: PROCESSED

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

get_chart_data(id: int, asset: GenericAsset, **kwargs)

— get:

summary: Download time series for use in charts description: Data for use in charts (in case you have the chart specs already). security:

ApiKeyAuth: []

parameters:

in: path name: id description: ID of the asset to download data for. schema:

type: integer

in: query schema: AssetChartDataKwargsSchema

responses:

200:
description: PROCESSED content:

application/json:

schema:
type: object

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

get_jobs(id: int, asset: GenericAsset)

— get:

summary: Get all background jobs related to an asset. description: |

The response will be a list of jobs. Note that jobs in Redis have a limited TTL, so not all past jobs will be listed.

security:

ApiKeyAuth: []

parameters:

in: path name: id required: true description: ID of the asset to get the jobs for. schema:

type: integer

responses:

200:
description: PROCESSED content:

application/json:

examples:

jobs:
summary: List of jobs value:

jobs:

job_id: 1 queue: scheduling asset_or_sensor_type: asset asset_id: 1 status: finished err: null enqueued_at: “2023-10-01T00:00:00” metadata_hash: abc123

redis_connection_err: null

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

get_kpis(id: int, asset: GenericAsset, start, end)

— get:

summary: Get daily KPIs for an asset. description: |

Gets statistics for sensors for the given time range. The asset attribute sensors_to_show_as_kpis determines which sensors are considered. Read more [here](https://flexmeasures.readthedocs.io/latest/views/asset-data.html#showing-daily-kpis).

The sensors are expected to have a daily resolution, suitable for KPIs. Each sensor has a preferred function to downsample the daily values to the KPI value.

This endpoint returns a list of KPIs for the asset.

security:

ApiKeyAuth: []

parameters:

in: path name: id required: true schema:

type: integer

in: query name: start schema:

type: string format: date-time

description: Start time for KPI calculation example: “2015-06-02T00:00:00+00:00”

in: query name: end schema:

type: string format: date-time

description: End time for KPI calculation example: “2015-06-09T00:00:00+00:00”

responses:

200:
description: PROCESSED content:

application/json:

examples:

kpi_response:
summary: KPI response value:

data:

sensor: 145046 title: My KPI unit: MW downsample_value: 0 downsample_function: sum

sensor: 141053 title: Raw PowerKPI unit: kW downsample_value: 816.67 downsample_function: sum

400:
description: INVALID_DATA

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

405:
description: INVALID_METHOD

tags:

Assets

— get:

summary: List all assets owned by user’s accounts, or a certain account or all accessible accounts. description: |

This endpoint returns all accessible assets by accounts.

The account_id query parameter can be used to list assets from any account (if the user is allowed to read them). Per default, the user’s account is used.

Alternatively, the all_accessible query parameter can be used to list assets from all accounts the current_user has read-access to, plus all public assets. Defaults to false.

The include_public query parameter can be used to include public assets in the response. Defaults to false.

The endpoint supports pagination of the asset list using the page and per_page query parameters.

If the page parameter is not provided, all assets are returned, without pagination information. The result will be a list of assets.

If a page parameter is provided, the response will be paginated, showing a specific number of assets per page as defined by per_page (default is 10).

If a search ‘filter’ such as ‘solar “ACME corp”’ is provided, the response will filter out assets where each search term is either present in their name or account name.

The response schema for pagination is inspired by [DataTables](https://datatables.net/manual/server-side#Returned-data)

security:

ApiKeyAuth: []

parameters:

in: query schema: AssetAPIQuerySchema

responses:

200:
description: PROCESSED content:

application/json:

examples:

single_asset:
summary: One asset being returned in the response value:

data: - id: 1

name: Test battery latitude: 10 longitude: 100 account_id: 2 generic_asset_type:

id: 1 name: battery

paginated_assets:
summary: A paginated list of assets being returned in the response value:

data: - id: 1

name: Test battery latitude: 10 longitude: 100 account_id: 2 generic_asset_type:

id: 1 name: battery

num-records: 1 filtered-records: 1

400:
description: INVALID_REQUEST

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

patch(asset_data: dict, id: int, db_asset: GenericAsset)

— patch:

summary: Update an asset given its identifier. description: |

This endpoint sets data for an existing asset. Any subset of asset fields can be sent.

The following fields are not allowed to be updated: - id - account_id

security:

ApiKeyAuth: []

parameters:

in: path name: id description: ID of the asset to update. schema:

type: integer

requestBody:

content:

application/json:
schema: AssetSchema examples:

single_asset:
summary: One asset being updated value:

latitude: 11.1 longitude: 99.9

responses:

200:
description: PROCESSED content:

application/json:

examples:

single_asset:
summary: the whole asset is returned in the response value:

generic_asset_type_id: 2 name: Test battery id: 1 latitude: 11.1 longitude: 99.9 account_id: 1 external_id: “”

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

post(asset_data: dict)

— post:

summary: Creates a new asset. description: |

This endpoint creates a new asset.

To establish a hierarchical relationship, you can optionally include the parent_asset_id in the request body to make the new asset a child of an existing asset.

security:

ApiKeyAuth: []

requestBody:

content:

application/json:
schema: AssetSchema examples:

single_asset:
summary: Request to create a standalone asset value:

name: Test battery generic_asset_type_id: 2 account_id: 2 latitude: 40 longitude: 170.3

child_asset:
summary: Request to create an asset with a parent value:

name: Test battery generic_asset_type_id: 2 account_id: 2 parent_asset_id: 10 latitude: 40 longitude: 170.3

responses:

201:
description: PROCESSED content:

application/json:

examples:

single_asset:
summary: One asset being returned in the response value:

generic_asset_type_id: 2 name: Test battery id: 1 latitude: 10 longitude: 100 account_id: 1

child_asset:
summary: A child asset being returned in the response value:

generic_asset_type_id: 2 name: Test battery id: 1 latitude: 10 longitude: 100 account_id: 1

400:
description: INVALID_REQUEST

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

public()

— get:

summary: Return all public assets. description: This endpoint returns all public assets. security:

ApiKeyAuth: []

responses:

200:
description: PROCESSED

400:
description: INVALID_REQUEST

401:
description: UNAUTHORIZED

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

trigger_schedule(asset: GenericAsset, start_of_schedule: datetime, duration: timedelta, belief_time: datetime | None = None, flex_model: dict | None = None, flex_context: dict | None = None, sequential: bool = False, **kwargs)

— post:

summary: Trigger scheduling job for any number of devices description: |

Trigger FlexMeasures to create a schedule for this asset. The flex-model needs to reference the power sensors of flexible devices, which must belong to the given asset, either directly or indirectly, by being assigned to one of the asset’s (grand)children.

In this request, you can describe:

the schedule’s main features (when does it start, what unit should it report, prior to what time can we assume knowledge)

the flexibility models for the asset’s relevant sensors (state and constraint variables, e.g. current state of charge of a battery, or connection capacity)

the flexibility context which the asset operates in (other sensors under the same EMS which are relevant, e.g. prices)

For details on flexibility model and context, [see describing_flexibility](https://flexmeasures.readthedocs.io/stable/features/scheduling.html#describing-flexibility). Below, we’ll also list some examples. The schemas we use in this endpoint documentation do not describe the full flexibility model and context (as the docs do), as these are very flexible (e.g. fixed values or sensors). The examples below illustrate how to describe a flexibility model and context.

> Note: This endpoint supports scheduling an EMS with multiple flexible devices at once. > It can do so jointly (the default) or sequentially > (considering previously scheduled sensors as inflexible). > To use sequential scheduling, use sequential=true in the JSON body.

The length of the schedule can be set explicitly through the ‘duration’ field. Otherwise, it is set by [a config setting](https://flexmeasures.readthedocs.io/stable/configuration.html#flexmeasures-planning-horizon), which defaults to 48 hours. If the flex-model contains targets that lie beyond the planning horizon, the length of the schedule is extended to accommodate them. Finally, the schedule length is limited by [a config setting](https://flexmeasures.readthedocs.io/stable/configuration.html#flexmeasures-max-planning-horizon), which defaults to 2520 steps of each sensor’s resolution. Targets that exceed the max planning horizon are not accepted.

The appropriate algorithm is chosen by FlexMeasures (based on asset type). It’s also possible to use custom schedulers and custom flexibility models, [see plugin_customization](https://flexmeasures.readthedocs.io/stable/plugin/customisation.html#plugin-customization).

If you have ideas for algorithms that should be part of FlexMeasures, let us know: [https://flexmeasures.io/get-in-touch/](https://flexmeasures.io/get-in-touch/)

security:

ApiKeyAuth: []

parameters:

in: path name: id required: true description: ID of the asset to schedule. schema:

type: integer

requestBody:

content:

application/json:
schema: AssetTriggerOpenAPISchema examples:

storage_asset:

description: |
This message triggers a schedule for a storage asset (with power sensor 931), starting at 10.00am, with the state of charge (soc) sensor being 74. This also schedules a curtailable production asset (with power sensor 932), whose production forecasts are recorded under sensor 760.

Aggregate consumption (of all devices within this EMS) should be priced by sensor 9, and aggregate production should be priced by sensor 10, where the aggregate power flow in the EMS is described by the sum over sensors 13, 14, 15, and the two power sensors (931 and 932) of the flexible devices being optimized (referenced in the flex-model).

The battery consumption power capacity is limited by sensor 42 and the production capacity is constant (30 kW). Finally, the site consumption capacity is limited by sensor 32.

value:
start: “2015-06-02T10:00:00+00:00” flex-model:

sensor: 931 soc-at-start: 12.1 kWh state-of-charge: {sensor: 74} power-capacity: 25 kW consumption-capacity: {sensor: 42} production-capacity: 30 kW

sensor: 932 consumption-capacity: 0 kW production-capacity: {sensor: 760}

flex-context:
consumption-price: {sensor: 9} production-price: {sensor: 10} inflexible-device-sensors: [13, 14, 15] site-power-capacity: 100 kVA site-production-capacity: 80 kW site-consumption-capacity: {sensor: 32}

heating_system:

description: |
This message triggers a schedule, starting at 10.00am, for a heating system that consists of a heat pump (with power sensor 931) and a heat buffer (with thermal state of charge sensor 74). This also schedules a curtailable production asset (with power sensor 932), whose production forecasts are recorded under sensor 760.

Aggregate consumption (of all devices within this EMS) should be priced by sensor 9, and aggregate production should be priced by sensor 10, where the aggregate power flow in the EMS is described by the sum over sensors 13, 14, 15, and the two power sensors (931 and 932) of the flexible devices being optimized (referenced in the flex-model).

The heat pump’s consumption power capacity is limited by sensor 42, and it cannot produce electricity (only heat). It turns power to heat with a Coefficient of Performance (COP) of 4. The heat buffer has a constant heat demand of 5 kW thermal, and a storage efficiency of 99.7%. Finally, the site consumption capacity is limited by sensor 32.

value:
start: “2015-06-02T10:00:00+00:00” flex-model:

sensor: 931 soc-at-start: 12.1 kWh state-of-charge: {sensor: 74} power-capacity: 25 kW consumption-capacity: {sensor: 42} production-capacity: 0 kW soc-usage:

“5 kW”

charging-efficiency: “4” # COP storage-efficiency: 99.7%

sensor: 932 consumption-capacity: 0 kW production-capacity: {sensor: 760}

flex-context:
consumption-price: {sensor: 9} production-price: {sensor: 10} inflexible-device-sensors: [13, 14, 15] site-power-capacity: 100 kVA site-production-capacity: 80 kW site-consumption-capacity: {sensor: 32}

responses:

200:
description: PROCESSED content:

application/json:

schema:
type: object

examples:

successful_response:

description: |
This message indicates that the scheduling request has been processed without any error. A scheduling job has been created with some Universally Unique Identifier (UUID), which will be picked up by a worker. The given UUID may be used to obtain the resulting schedule for each flexible device: [see /sensors/schedules/.](#/Sensors/get_api_v3_0_sensors__id__schedules__uuid_).

value:
status: PROCESSED schedule: “364bfd06-c1fa-430b-8d25-8f5a547651fb” message: “Request has been processed.”

400:
description: INVALID_DATA

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

405:
description: INVALID_METHOD

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

update_default_asset_view(**kwargs)

— post:

summary: Update the default asset view for the current user description: |

Update which asset page is shown to the current user per default. For instance, the user would see graphs per default when clicking on an asset (now the default is the Context page).

This endpoint sets the default asset view for the current user session if use_as_default is true. If use_as_default is false, it clears the session variable for the default asset view.

## Example values for default_asset_view: - “Audit Log” - “Context” - “Graphs” - “Properties” - “Status”

security:

ApiKeyAuth: []

requestBody:
required: true content:

application/json:
schema: DefaultAssetViewJSONSchema examples:

default_asset_view:
summary: Setting the user’s default asset view to “Graphs” value:

default_asset_view: “Graphs” use_as_default: true

resetting_default_view:
summary: resetting the user’s default asset view (will return to use system default) value:

use_as_default: false

responses:

200:
description: PROCESSED content:

application/json:

examples:

message:
summary: Message value:

message: “Default asset view updated successfully.”

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

401:
description: UNAUTHORIZED

403:
description: INVALID_SENDER

422:
description: UNPROCESSABLE_ENTITY

tags:

Assets

update_keep_legends_below_graphs(**kwargs)

— post:

summary: Toggle whether for the current user legends should always be combined below graphs or shown to the right (per graph) above a certain number. description: |

This endpoint toggles whether the legend position for graphs is always at the bottom, even with many plots. The default is False, meaning that from 7 sensors or above, the legends will be shown to the right of graphs, for better readability. On narrow screens, users might want to turn this to True.

security:

ApiKeyAuth: []

requestBody:
required: true content:

application/json:

schema:
type: object properties:

keep_legends_below_graphs:
type: boolean

required:

keep_legends_below_graphs

responses:

200:
description: PROCESSED content:

application/json:

examples:

message:
summary: Message value:

message: “Legend position preference updated successfully.”

400:
description: INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

tags:

Assets

class flexmeasures.api.v3_0.assets.AssetAuditLogPaginationSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)

class flexmeasures.api.v3_0.assets.AssetChartDataKwargsSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)

class flexmeasures.api.v3_0.assets.AssetChartKwargsSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)

class flexmeasures.api.v3_0.assets.AssetTriggerOpenAPISchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)

class flexmeasures.api.v3_0.assets.AssetTypesAPI

This API view exposes generic asset types.

index()

— get:

summary: Get list of available asset types security:

ApiKeyAuth: []

responses:

200:
description: PROCESSED content:

application/json:

examples:

single_asset_type:
summary: One asset type being returned in the response value:

id: 1 name: solar description: solar panel(s)

tags:

Assets

class flexmeasures.api.v3_0.assets.DefaultAssetViewJSONSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)

class flexmeasures.api.v3_0.assets.KPIKwargsSchema(*, only: types.StrSequenceOrSet | None = None, exclude: types.StrSequenceOrSet = (), many: bool | None = None, context: dict | None = None, load_only: types.StrSequenceOrSet = (), dump_only: types.StrSequenceOrSet = (), partial: bool | types.StrSequenceOrSet | None = None, unknown: str | None = None)