Version 3.0

Summary

Resource

Operation

Description

Asset

GET /api/v3_0/assets

Download asset list

POST /api/v3_0/assets

Create a new asset

DELETE /api/v3_0/assets/(id)

Delete an asset

GET /api/v3_0/assets/(id)

Get an asset

PATCH /api/v3_0/assets/(id)

Update an asset

GET /api/v3_0/assets/(id)/auditlog

Get audit log

GET /api/v3_0/assets/(id)/jobs

Get asset jobs

GET /api/v3_0/assets/(id)/kpis

Get asset KPIs

GET /api/v3_0/assets/(id)/sensors

Return all sensors under an asset.

POST /api/v3_0/assets/default_asset_view

Update the default asset view

GET /api/v3_0/assets/public

Return all public assets.

Chart

GET /api/v3_0/assets/(id)/chart

Download a chart with time series

GET /api/v3_0/assets/(id)/chart_data

Download time series for use in charts

Data

POST /api/v3_0/sensors/(id)/data/upload

Upload sensor data by file

GET /api/v3_0/sensors/data

Download sensor data

POST /api/v3_0/sensors/data

Upload sensor data

Health

GET /api/v3_0/health/ready

Get readiness status

Public

GET /api/

List available API versions

POST /api/requestAuthToken

Obtain an authentication token

GET /api/v3_0

Obtain a service listing for this version

Schedule

POST /api/v3_0/assets/(id)/schedules/trigger

Trigger scheduling job for any number of devices

GET /api/v3_0/sensors/(id)/schedules/(uuid)

Download schedule for one device

POST /api/v3_0/sensors/(id)/schedules/trigger

Trigger scheduling job for one device

Sensor

GET /api/v3_0/sensors

Get list of sensors

POST /api/v3_0/sensors

Create a new Sensor

DELETE /api/v3_0/sensors/(id)

Delete a sensor

GET /api/v3_0/sensors/(id)

Get a sensor

PATCH /api/v3_0/sensors/(id)

Update a sensor

DELETE /api/v3_0/sensors/(id)/data

Delete sensor data

GET /api/v3_0/sensors/(id)/stats

Get sensor stats

GET /api/v3_0/sensors/(id)/status

Get sensor status

User

GET /api/v3_0/users

Download user list

GET /api/v3_0/users/(id)

Get a user

PATCH /api/v3_0/users/(id)

Patch data for an existing user

GET /api/v3_0/users/(id)/auditlog

Get audit log

PATCH /api/v3_0/users/(id)/password-reset

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:
Status Codes:
GET /api/v3_0/assets

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

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 https://datatables.net/manual/server-side#Returned-data

Example response

An example of one asset being returned in a paginated response:

{
    "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

}

If no pagination is requested, the response only consists of the list under the “data” key.

Request Headers:
Response Headers:
Status Codes:
POST /api/v3_0/assets

Create new asset.

This endpoint creates a new asset.

Example request A

{
    "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.

Example request B

Alternatively, set the parent_asset_id to make the new asset a child of another asset. For example, to set asset 10 as its parent:

{
    "name": "Test battery",
    "generic_asset_type_id": 2,
    "account_id": 2,
    "parent_asset_id": 10,
    "latitude": 40,
    "longitude": 170.3,
}
Request Headers:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
GET /api/v3_0/assets/(id)/auditlog

API endpoint to get history of asset related actions.

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 https://datatables.net/manual/server-side

Example response

Request Headers:
Response Headers:
Status Codes:
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/(id)/jobs

API endpoint to get all jobs of an asset.

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.

Example response

Request Headers:
Response Headers:
Status Codes:
GET /api/v3_0/assets/(id)/kpis

API endpoint to get KPIs for an asset.

Gets statistics for sensors for the given time range. 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.

Example request

{
    "start": "2015-06-02T10:00:00+00:00",
    "end": "2015-06-02T12:00:00+00:00"
}

Example response

{
    "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",
        }
    ]
}

This endpoint returns a list of kpis for the asset.

Request Headers:
Response Headers:
Status Codes:
POST /api/v3_0/assets/(id)/schedules/trigger

Trigger FlexMeasures to create a schedule for a collection of flexible and inflexible devices.

Trigger FlexMeasures to create a schedule for this asset. The flex-model references 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. Below, we’ll also list some examples.

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

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

Example request

This message triggers a schedule for a storage asset (with power sensor 931), starting at 10.00am, when the state of charge (soc) should be assumed to be 12.1 kWh, and 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.

{
    "start": "2015-06-02T10:00:00+00:00",
    "flex-model": [
        {
            "sensor": 931,
            "soc-at-start": 12.1,
            "soc-unit": "kWh",
            "power-capacity": "25kW",
            "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": "100kW",
        "site-production-capacity": "80kW",
        "site-consumption-capacity": {"sensor": 32}
    }
}

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 for each flexible device: see /sensors/<id>/schedules/<uuid>.

{
    "status": "PROCESSED",
    "schedule": "364bfd06-c1fa-430b-8d25-8f5a547651fb",
    "message": "Request has been processed."
}
Request Headers:
Response Headers:
Status Codes:
GET /api/v3_0/assets/(id)/sensors

List all sensors under an asset.

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

Example response

An example of one asset being returned in a paginated response:

{
    "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

}

If no pagination is requested, the response only consists of the list under the “data” key.

Request Headers:
Response Headers:
Status Codes:
POST /api/v3_0/assets/default_asset_view

Update the default asset view for the current user session.

Example request

{
    "default_asset_view": "Graphs",
    "use_as_default": true
}

Example response

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.

Request Headers:
Response Headers:
Status Codes:
GET /api/v3_0/assets/public

Return all public assets.

This endpoint returns all public assets.

Request Headers:
Response Headers:
Status Codes:
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. By default, “accessible sensors” means all sensors in the same account as the current user (if they have read permission to the account).

You can also specify an account (an ID parameter), if the user has read access to that account. In this case, all assets under the specified account will be retrieved, and the sensors associated with these assets will be returned.

Alternatively, you can filter by asset hierarchy by providing the asset parameter (ID). When this is set, all sensors on the specified asset and its sub-assets are retrieved, provided the user has read access to the asset.

NOTE: You can’t set both account and asset at the same time, you can only have one set. The only exception is if the asset being specified is part of the account that was set, then we allow to see sensors under that asset but then ignore the account (account = None).

Finally, you can use the include_consultancy_clients parameter to include sensors from accounts for which the current user account is a consultant. This is only possible if the user has the role of a consultant.

Only admins can use this endpoint to fetch sensors from a different account (by using the account_id query parameter).

The filter parameter allows you to search for sensors by name or account name. The unit parameter allows you to filter by unit.

For the pagination of the sensor list, you can use the page and per_page query parameters, the page parameter is used to trigger pagination, and the per_page parameter is used to specify the number of records per page. The default value for page is 1 and for per_page is 10.

Example response

An example of one sensor being returned:

{
    "data" : [
        {
            "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
        }
    ],
    "num-records" : 1,
    "filtered-records" : 1
}

If no pagination is requested, the response only consists of the list under the “data” key.

Request Headers:
Response Headers:
Status Codes:
POST /api/v3_0/sensors

Create new sensor.

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:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
DELETE /api/v3_0/sensors/(id)/data

Delete all data for a sensor.

This endpoint deletes all data for a sensor.

Request Headers:
Response Headers:
Status Codes:
POST /api/v3_0/sensors/(id)/data/upload

Post sensor data to FlexMeasures by file upload.

** Example request **

{
    "data": [
        {
            "uploaded-files": "["file1.csv", "file2.csv"]"
        }
    ]
}

The file should have columns for a timestamp (event_start) and a value (event_value). The timestamp should be in ISO 8601 format. The value should be a numeric value.

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:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
POST /api/v3_0/sensors/(id)/schedules/trigger

Trigger FlexMeasures to create a schedule for a single flexible device, possibly taking into account inflexible devices.

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

To schedule an EMS with multiple flexible sensors at once, use this endpoint instead.

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

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 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, the sensor with ID 300 contains beliefs 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, 15, and the power sensor of the flexible device being optimized (referenced in the endpoint URL).

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

Finally, the (contractual and physical) situation of the site is part of the flex-context. The site has a physical power capacity of 100 kVA, but the production capacity is limited to 80 kW, while the consumption capacity is limited by a dynamic capacity contract whose values are recorded under sensor 32. Breaching either capacity is penalized heavily in the optimization problem, with a price of 1000 EUR/kW. Finally, peaks over 50 kW in either direction are penalized with a price of 260 EUR/MW. These penalties can be used to steer the schedule into a certain behaviour (e.g. avoiding breaches and peaks), even if no direct financial impacts are expected at the given prices in the real world. For example, site owners may be requested by their network operators to reduce stress on the grid, be it explicitly or under a social contract.

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 kWh",
        "state-of-charge" : {"sensor" : 24},
        "soc-targets": [
            {
                "value": "25 kWh",
                "datetime": "2015-06-02T16:00:00+00:00"
            },
        ],
        "soc-minima": {"sensor" : 300},
        "soc-min": "10 kWh",
        "soc-max": "25 kWh",
        "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": "100 kVA",
        "site-production-capacity": "80 kW",
        "site-consumption-capacity": {"sensor": 32},
        "site-production-breach-price": "1000 EUR/kW",
        "site-consumption-breach-price": "1000 EUR/kW",
        "site-peak-consumption": "50 kW",
        "site-peak-production": "50 kW",
        "site-peak-consumption-price": "260 EUR/MW",
        "site-peak-production-price": "260 EUR/MW"
    }
}

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:
Response Headers:
Status Codes:
GET /api/v3_0/sensors/(id)/stats

Fetch stats for a given sensor.

This endpoint fetches sensor stats for all the historical data.

Example response

{
    "some data source": {
        "First event start": "2015-06-02T10:00:00+00:00",
        "Last event end": "2015-10-02T10:00:00+00:00",
        "Last recorded": "2015-10-02T10:01:12+00:00",
        "Min value": 0.0,
        "Max value": 100.0,
        "Mean value": 50.0,
        "Sum over values": 500.0,
        "Number of values": 10
    }
}
Request Headers:
Response Headers:
Status Codes:
GET /api/v3_0/sensors/(id)/status

Fetch the current status for a given sensor.

This endpoint fetches the current status data for the specified sensor. The status includes information about the sensor’s status, staleness and resolution.

Example response:

[
    {
        'staleness': None,
        'stale': True,
        'staleness_since': None,
        'reason': 'no data recorded',
        'source_type': None,
        'id': 64906,
        'name': 'power',
        'resolution': '15 minutes',
        'asset_name': 'Location 1',
        'relation': 'sensor belongs to this asset'
    }
]
Request Headers:
Response Headers:
Status Codes:
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

Request Headers:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
GET /api/v3_0/users

API endpoint to list all users.

This endpoint returns all accessible users. By default, only active users are returned. The account_id query parameter can be used to filter the users of a given account. 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:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes:
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, consultant 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. User roles cannot be updated by everyone - it requires certain access levels (roles, account), with the general rule that you need a higher access level than the role being updated.

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:
Response Headers:
Status Codes:
GET /api/v3_0/users/(id)/auditlog

API endpoint to get history of user actions.

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 audit logs 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 https://datatables.net/manual/server-side

Example response

Request Headers:
Response Headers:
Status Codes:
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:
Response Headers:
Status Codes: