Version 3.0
Summary
Resource |
Operation |
Description |
---|---|---|
Asset |
Download asset list |
|
Create a new asset |
||
Delete an asset |
||
Get an asset |
||
Update an asset |
||
Return all public assets. |
||
Chart |
Download a chart with time series |
|
Download time series for use in charts |
||
Data |
Download sensor data |
|
Upload sensor data |
||
Health |
Get readiness status |
|
Public |
List available API versions |
|
Obtain an authentication token |
||
Obtain a service listing for this version |
||
Schedule |
Download schedule from the platform |
|
Trigger scheduling job |
||
Sensor |
Download sensor list |
|
Create a new Sensor |
||
Delete a sensor |
||
Get a sensor |
||
Update a sensor |
||
User |
Download user list |
|
Get a user |
||
Patch data for an existing user |
||
Password reset |
API Details
- GET /api/
Public endpoint to list API versions.
- POST /api/requestAuthToken
API endpoint to get a fresh authentication access token. Be aware that this fresh token has a limited lifetime (which depends on the current system setting SECURITY_TOKEN_MAX_AGE).
Pass the email parameter to identify the user. Pass the password parameter to authenticate the user (if not already authenticated in current session)
- GET /api/v3_0
API endpoint to get a service listing for this version.
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
- GET /api/v3_0/assets
List all assets owned by a certain account.
This endpoint returns all accessible assets for the account of the user. The account_id query parameter can be used to list assets from a different account.
Example response
An example of one asset being returned:
[ { "id": 1, "name": "Test battery", "latitude": 10, "longitude": 100, "account_id": 2, "generic_asset_type_id": 1 } ]
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- POST /api/v3_0/assets
Create new asset.
This endpoint creates a new asset.
Example request
{ "name": "Test battery", "generic_asset_type_id": 2, "account_id": 2, "latitude": 40, "longitude": 170.3, }
The newly posted asset is returned in the response.
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
201 Created – CREATED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- DELETE /api/v3_0/assets/(id)
Delete an asset given its identifier.
This endpoint deletes an existing asset, as well as all sensors and measurements recorded for it.
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
204 No Content – DELETED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/assets/(id)
Fetch a given asset.
This endpoint gets an asset.
Example response
{ "generic_asset_type_id": 2, "name": "Test battery", "id": 1, "latitude": 10, "longitude": 100, "account_id": 1, }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- PATCH /api/v3_0/assets/(id)
Update an asset given its identifier.
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
Example request
{ "latitude": 11.1, "longitude": 99.9, }
Example response
The whole asset is returned in the response:
{ "generic_asset_type_id": 2, "id": 1, "latitude": 11.1, "longitude": 99.9, "name": "Test battery", "account_id": 2, }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – UPDATED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/assets/(id)/chart/
GET from /assets/<id>/chart
- GET /api/v3_0/assets/(id)/chart_data/
GET from /assets/<id>/chart_data
Data for use in charts (in case you have the chart specs already).
- GET /api/v3_0/assets/public
Return all public assets.
This endpoint returns all public assets.
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/health/ready
Get readiness status
Example response:
{ 'database_sql': True, 'database_redis': False }
- GET /api/v3_0/sensors
API endpoint to list all sensors of an account.
This endpoint returns all accessible sensors. Accessible sensors are sensors in the same account as the current user. Only admins can use this endpoint to fetch sensors from a different account (by using the account_id query parameter).
Example response
An example of one sensor being returned:
[ { "entity_address": "ea1.2021-01.io.flexmeasures.company:fm1.42", "event_resolution": PT15M, "generic_asset_id": 1, "name": "Gas demand", "timezone": "Europe/Amsterdam", "unit": "m³/h" "id": 2 } ]
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- POST /api/v3_0/sensors
Create new asset.
This endpoint creates a new Sensor.
Example request
{ "name": "power", "event_resolution": "PT1H", "unit": "kWh", "generic_asset_id": 1, }
Example response
The whole sensor is returned in the response:
{ "name": "power", "unit": "kWh", "entity_address": "ea1.2023-08.localhost:fm1.1", "event_resolution": "PT1H", "generic_asset_id": 1, "timezone": "UTC", "id": 2 }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
201 Created – CREATED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- DELETE /api/v3_0/sensors/(id)
Delete a sensor given its identifier.
This endpoint deletes an existing sensor, as well as all measurements recorded for it.
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
204 No Content – DELETED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/sensors/(id)
Fetch a given sensor.
This endpoint gets a sensor.
Example response
{ "name": "some gas sensor", "unit": "m³/h", "entity_address": "ea1.2023-08.localhost:fm1.1", "event_resolution": "PT10M", "generic_asset_id": 4, "timezone": "UTC", "id": 2 }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- PATCH /api/v3_0/sensors/(id)
Update a sensor given its identifier.
This endpoint updates the descriptive data of an existing sensor.
Any subset of sensor fields can be sent. However, the following fields are not allowed to be updated: - id - generic_asset_id - entity_address
Only admin users have rights to update the sensor fields. Be aware that changing unit, event resolution and knowledge horizon should currently only be done on sensors without existing belief data (to avoid a serious mismatch), or if you really know what you are doing.
Example request
{ "name": "POWER", }
Example response
The whole sensor is returned in the response:
{ "name": "some gas sensor", "unit": "m³/h", "entity_address": "ea1.2023-08.localhost:fm1.1", "event_resolution": "PT10M", "generic_asset_id": 4, "timezone": "UTC", "id": 2 }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – UPDATED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/sensors/(id)/schedules/(uuid)
Get a schedule from FlexMeasures.
Optional fields
“duration” (6 hours by default; can be increased to plan further into the future)
Example response
This message contains a schedule indicating to consume at various power rates from 10am UTC onwards for a duration of 45 minutes.
{ "values": [ 2.15, 3, 2 ], "start": "2015-06-02T10:00:00+00:00", "duration": "PT45M", "unit": "MW" }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_TIMEZONE, INVALID_DOMAIN, INVALID_UNIT, UNKNOWN_SCHEDULE, UNRECOGNIZED_CONNECTION_GROUP
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- POST /api/v3_0/sensors/(id)/schedules/trigger
Trigger FlexMeasures to create a schedule.
Trigger FlexMeasures to create a schedule for this sensor. The assumption is that this sensor is the power sensor on a flexible asset.
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 model for the sensor (state and constraint variables, e.g. current state of charge of a battery, or connection capacity)
the flexibility context which the sensor operates in (other sensors under the same EMS which are relevant, e.g. prices)
For details on flexibility model and context, see Describing flexibility. Below, we’ll also list some examples.
Note
This endpoint does not support to schedule an EMS with multiple flexible sensors at once. This will happen in another endpoint. See https://github.com/FlexMeasures/flexmeasures/issues/485. Until then, it is possible to call this endpoint for one flexible endpoint at a time (considering already scheduled sensors as inflexible).
The length of the schedule can be set explicitly through the ‘duration’ field. Otherwise, it is set by the config setting 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 max_planning_horizon_config, which defaults to 2520 steps of the 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 Customizations.
If you have ideas for algorithms that should be part of FlexMeasures, let us know: https://flexmeasures.io/get-in-touch/
Example request A
This message triggers a schedule for a storage asset, starting at 10.00am, at which the state of charge (soc) is 12.1 kWh.
{ "start": "2015-06-02T10:00:00+00:00", "flex-model": { "soc-at-start": 12.1, "soc-unit": "kWh" } }
Example request B
This message triggers a 24-hour schedule for a storage asset, starting at 10.00am, at which the state of charge (soc) is 12.1 kWh, with a target state of charge of 25 kWh at 4.00pm.
The charging efficiency is constant (120%) and the discharging efficiency is determined by the contents of sensor with id 98. If just the
roundtrip-efficiency
is known, it can be described with its own field. The global minimum and maximum soc are set to 10 and 25 kWh, respectively. To guarantee a minimum SOC in the period prior to 4.00pm, local minima constraints are imposed (via soc-minima) at 2.00pm and 3.00pm, for 15kWh and 20kWh, respectively. Storage efficiency is set to 99.99%, denoting the state of charge left after each time step equal to the sensor’s resolution. 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 and 15 (plus the flexible sensor being optimized, of course).The battery consumption power capacity is limited by sensor 42 and the production capacity is constant (30 kW).
Note that, if forecasts for sensors 13, 14 and 15 are not available, a schedule cannot be computed.
{ "start": "2015-06-02T10:00:00+00:00", "duration": "PT24H", "flex-model": { "soc-at-start": 12.1, "soc-unit": "kWh", "soc-targets": [ { "value": 25, "datetime": "2015-06-02T16:00:00+00:00" }, ], "soc-minima": [ { "value": 15, "start": "2015-06-02T14:00:00+00:00", "end": "2015-06-02T15:00:00+00:00" } ], "soc-min": 10, "soc-max": 25, "charging-efficiency": "120%", "discharging-efficiency": {"sensor" : 98}, "storage-efficiency": 0.9999, "power-capacity": "25kW", "consumption-capacity" : {"sensor" : 42}, "production-capacity" : "30 kW" }, "flex-context": { "consumption-price-sensor": 9, "production-price-sensor": 10, "inflexible-device-sensors": [13, 14, 15], "site-power-capacity": "100kW", "site-production-capacity": "80kW", "site-consumption-capacity": "100kW" } }
Example response
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: see /sensors/<id>/schedules/<uuid>.
{ "status": "PROCESSED", "schedule": "364bfd06-c1fa-430b-8d25-8f5a547651fb", "message": "Request has been processed." }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_DATA
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/sensors/data
Get sensor data from FlexMeasures.
Example request
{ "sensor": "ea1.2021-01.io.flexmeasures:fm1.1", "start": "2021-06-07T00:00:00+02:00", "duration": "PT1H", "resolution": "PT15M", "unit": "m³/h" }
The unit has to be convertible from the sensor’s unit.
Optional fields
“resolution” (see Frequency and resolution)
“horizon” (see Tracking the recording time of beliefs)
“prior” (see Tracking the recording time of beliefs)
“source” (see Sources)
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- POST /api/v3_0/sensors/data
Post sensor data to FlexMeasures.
Example request
{ "sensor": "ea1.2021-01.io.flexmeasures:fm1.1", "values": [-11.28, -11.28, -11.28, -11.28], "start": "2021-06-07T00:00:00+02:00", "duration": "PT1H", "unit": "m³/h" }
The above request posts four values for a duration of one hour, where the first event start is at the given start time, and subsequent events start in 15 minute intervals throughout the one hour duration.
The sensor is the one with ID=1. The unit has to be convertible to the sensor’s unit. The resolution of the data has to match the sensor’s required resolution, but FlexMeasures will attempt to upsample lower resolutions. The list of values may include null values.
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/users
API endpoint to list all users of an account.
This endpoint returns all accessible users. By default, only active users are returned. The include_inactive query parameter can be used to also fetch inactive users. Accessible users are users in the same account as the current user. Only admins can use this endpoint to fetch users from a different account (by using the account_id query parameter).
Example response
An example of one user being returned:
[ { 'active': True, 'email': 'test_prosumer@seita.nl', 'account_id': 13, 'flexmeasures_roles': [1, 3], 'id': 1, 'timezone': 'Europe/Amsterdam', 'username': 'Test Prosumer User' } ]
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v3_0/users/(id)
API endpoint to get a user.
This endpoint gets a user. Only admins or the members of the same account can use this endpoint.
Example response
{ 'account_id': 1, 'active': True, 'email': 'test_prosumer@seita.nl', 'flexmeasures_roles': [1, 3], 'id': 1, 'timezone': 'Europe/Amsterdam', 'username': 'Test Prosumer User' }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- PATCH /api/v3_0/users/(id)
API endpoint to patch user data.
This endpoint sets data for an existing user. It has to be used by the user themselves, admins or account-admins (of the same account). Any subset of user fields can be sent. If the user is not an (account-)admin, they can only edit a few of their own fields.
- The following fields are not allowed to be updated at all:
id
account_id
Example request
{ "active": false, }
Example response
The following user fields are returned:
{ 'account_id': 1, 'active': True, 'email': 'test_prosumer@seita.nl', 'flexmeasures_roles': [1, 3], 'id': 1, 'timezone': 'Europe/Amsterdam', 'username': 'Test Prosumer User' }
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – UPDATED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- PATCH /api/v3_0/users/(id)/password-reset
API endpoint to reset the user’s current password, cookies and auth tokens, and to email a password reset link to the user.
Reset the user’s password, and send them instructions on how to reset the password. This endpoint is useful from a security standpoint, in case of worries the password might be compromised. It sets the current password to something random, invalidates cookies and auth tokens, and also sends an email for resetting the password to the user.
Users can reset their own passwords. Only admins can use this endpoint to reset passwords of other users.
- Request Headers:
Authorization – The authentication token
Content-Type – application/json
- Response Headers:
Content-Type – application/json
- Status Codes:
200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY