Version 3.0

Summary

A quick overview of the available endpoints. For more details, click their names.

Resource	Operation	Description
Accounts	GET /api/v3_0/accounts	List all accounts accessible to the current user.
	GET /api/v3_0/accounts/(id)	Fetch a given account.
	PATCH /api/v3_0/accounts/(id)	Update an account.
	GET /api/v3_0/accounts/(id)/auditlog	Get the history of actions for a specific account.
Assets	GET /api/v3_0/assets	List all assets owned by user’s accounts, or a certain account or all accessible accounts.
	POST /api/v3_0/assets	Creates a new asset.
	DELETE /api/v3_0/assets/(id)	Delete an asset.
	GET /api/v3_0/assets/(id)	Fetch a given asset.
	PATCH /api/v3_0/assets/(id)	Update an asset given its identifier.
	GET /api/v3_0/assets/(id)/auditlog	Get history of asset related actions.
	GET /api/v3_0/assets/(id)/jobs	Get all background jobs related to an asset.
	GET /api/v3_0/assets/(id)/kpis	Get daily KPIs for an asset.
	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 for the current user
	POST /api/v3_0/assets/keep_legends_below_graphs	Toggle whether for the current user legends should always be combined below graphs or shown to the right (per graph) above a certain number.
	GET /api/v3_0/assets/public	Return all public assets.
	GET /api/v3_0/assets/types	Get list of available asset types
Auth	POST /api/requestAuthToken	Obtain authentication token
Charts	GET /api/v3_0/assets/(id)/chart	Download an embeddable chart with time series data
	GET /api/v3_0/assets/(id)/chart_data	Download time series for use in charts
Data	GET /api/v3_0/sensors/(id)/data	Get sensor data
	POST /api/v3_0/sensors/(id)/data	Post sensor data
	POST /api/v3_0/sensors/(id)/data/upload	Upload sensor data by file
	GET /api/v3_0/sensors/(id)/status	Get status of sensor data
Forecasts	GET /api/v3_0/sensors/(sensor)/forecasts/(job_id)	Check forecast job status for a sensor and fetch results.
	POST /api/v3_0/sensors/(sensor)/forecasts/trigger	Trigger forecasting job for one sensor
Public	GET /api/	List available API versions
	GET /api/v3_0	Obtain a service listing for this version
	GET /api/v3_0/health/ready	Check readiness status
Schedules	POST /api/v3_0/assets/(id)/schedules/trigger	Trigger scheduling job for any number of devices
	GET /api/v3_0/sensors/(id)/schedules/(uuid)	Get schedule for one device
	POST /api/v3_0/sensors/(id)/schedules/trigger	Trigger scheduling job for one device
Sensors	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)	Fetch a given 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
Users	GET /api/v3_0/users	List users.
	POST /api/v3_0/users	Create new user
	GET /api/v3_0/users/(id)	Fetch a user
	PATCH /api/v3_0/users/(id)	Update a user
	GET /api/v3_0/users/(id)/auditlog	Get history of user actions.
	PATCH /api/v3_0/users/(id)/password-reset	Password reset

OpenAPI & SwaggerUI

We also provide interactive SwaggerUI documentation with each instance at /api/v3_0/docs. See a screenshot below.

To access it, click on the book icon on the upper right or visit https://<your-instance>/api/v3_0/docs. If authenticated, you can try out the endpoints directly from there.

https://github.com/FlexMeasures/screenshots/raw/main/swagger-ui.png

API Details

Below, each endpoint is described in detail.

Auth

POST /api/requestAuthToken

Obtain a fresh authentication access token.

Retrieve a short-lived authentication token using email and password. The lifetime of this token depends on the current system setting SECURITY_TOKEN_MAX_AGE.

Example request:

POST /api/requestAuthToken HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "email": "string",
    "password": "string"
}

Status Codes:

200 OK –

Token successfully generated

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "authentication_token": "string"
}

400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED

Public

GET /api/

List available API versions

Public endpoint to list all available FlexMeasures API versions.

This can be used to programmatically discover which API versions are currently supported and their base URLs.

Example request:

GET /api/ HTTP/1.1
Host: example.com

Status Codes:

200 OK –

Successfully retrieved available API versions.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "string",
    "versions": [
        "string"
    ],
    "flexmeasures_version": "string"
}

GET /api/v3_0/health/ready

Get readiness status

Health check endpoint to verify if core services required by FlexMeasures are ready.

Example request:

GET /api/v3_0/health/ready HTTP/1.1
Host: example.com

Status Codes:

200 OK –

All required services are operational.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "database_sql": true,
    "database_redis": true
}

Sensors

DELETE /api/v3_0/sensors/{id}

Delete a sensor

This endpoint deletes an existing sensor, as well as all measurements recorded for it.

Parameters:

id (integer)

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

Fetch a given sensor by its ID.

Parameters:

id (integer)

Example request:

GET /api/v3_0/sensors/{id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

One Sensor

price_sensor - A day-ahead price sensor recording 15-minute prices.:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 14,
    "name": "day-ahead electricity price",
    "unit": "EUR/kWh",
    "timezone": "Europe/Amsterdam",
    "event_resolution": "PT15M",
    "entity_address": "ea1.2021-01.io.flexmeasures:fm1.14",
    "generic_asset_id": 1
}

power_sensor - A power sensor recording average consumption every 5 minutes.:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 5,
    "name": "power",
    "unit": "kW",
    "timezone": "Europe/Amsterdam",
    "event_resolution": "PT5M",
    "entity_address": "ea1.2021-01.io.flexmeasures:fm1.5",
    "attributes": {
        "consumption_is_positive": true
    },
    "generic_asset_id": 1
}

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

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.

Parameters:

id (integer)

update_sensor - Update sensor name:

PATCH /api/v3_0/sensors/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "POWER"
}

Status Codes:

200 OK –

Updated Sensor

update_sensor - Update sensor name:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "POWER",
    "unit": "m\u00b3/h",
    "entity_address": "ea1.2023-08.localhost:fm1.1",
    "event_resolution": "PT10M",
    "generic_asset_id": 4,
    "timezone": "UTC",
    "id": 2
}

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

DELETE /api/v3_0/sensors/{id}/data

Delete sensor data

This endpoint deletes all data for a sensor.

Parameters:

id (integer)

Status Codes:

204 No Content – SENSOR_DATA_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}/data

Get sensor data

The unit has to be convertible from the sensor’s unit - e.g. you ask for kW, and the sensor’s unit is MW.

Optional parameters:

“resolution” (read the docs about frequency and resolutions)
“horizon” (read the docs about belief timing)
“prior” (the belief timing docs also apply here)
“source” (read the docs about sources)

An example query to fetch data for sensor with ID=1, for one hour starting June 7th 2021 at midnight, in 15 minute intervals, in m³/h:

?start=2021-06-07T00:00:00+02:00&duration=PT1H&resolution=PT15M&unit=m³/h

(you will probably need to escape the + in the timezone offset, depending on your HTTP client, and other characters like here in the unit, as well).

Note: This endpoint also accepts the query parameters as part of the JSON body. That is not conform to REST architecture, but it is easier for some developers.

Parameters:

id (integer)

Query Parameters:

start (string) – Start time of the first event described in the time series data, in ISO 8601 datetime format. (Required)
duration (string) – Duration of the full set of events described in the time series data, in ISO 8601 duration format. (Required)
horizon (string) – All sensor data has been recorded at least this duration beforehand (for physical event, before the event ended; for economical events, before gate closure).
prior (string) – All sensor data has been recorded prior to this belief time.
unit (string) – The unit of the sensor data, which must be convertible to the sensor unit. (Required)

Example request:

GET /api/v3_0/sensors/{id}/data?start=2025-12-04T02%3A49%3A10.088262&duration=string&unit=string HTTP/1.1
Host: example.com

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/{id}/data

Post sensor data

Send data values via JSON, where the duration and number of values determine the resolution.

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

Parameters:

id (integer)

post_sensor - Post sensor data to FlexMeasures:

POST /api/v3_0/sensors/{id}/data HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "values": [
        -11.28,
        -11.28,
        -11.28,
        -11.28
    ],
    "start": "2021-06-07T00:00:00+02:00",
    "duration": "PT1H",
    "unit": "m\u00b3/h"
}

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/sensors/{id}/schedules/{uuid}

Get schedule for one device

Get a schedule from FlexMeasures.

Optional fields:

“duration” (6 hours by default; can be increased to plan further into the future)

Parameters:

id (int) – ID of the sensor for which to retrieve the schedule.
uuid (string) – UUID of the scheduling job, which was returned by the Sensor scheduling endpoint or the Assets scheduling endpoint.

Query Parameters:

duration (string) – Duration of the schedule to retrieve. If omitted, the default is 6 hours. The maximum allowed value is limited by the FLEXMEASURES_PLANNING_HORIZON configuration option (default: 48 hours). While a full-horizon schedule is available, it is usually not useful to fetch it entirely. A better approach is to request only the near-term part of the schedule, and to refresh the schedule as new information becomes relevant.

Example request:

GET /api/v3_0/sensors/{id}/schedules/{uuid} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

schedule - Schedule response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "values": [
        2.15,
        3,
        2
    ],
    "start": "2015-06-02T10:00:00+00:00",
    "duration": "PT45M",
    "unit": "MW"
}

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

GET /api/v3_0/sensors/{id}/stats

Get sensor stats

This endpoint fetches sensor stats for all the historical data.

Parameters:

id (integer)

Query Parameters:

event_start_time (string) – Start of the period to fetch stats for, in ISO 8601 format.
event_end_time (string) – End of the period to fetch stats for, in ISO 8601 format.
sort_keys (boolean) – Whether to sort the stats by keys.

Example request:

GET /api/v3_0/sensors/{id}/stats HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

successful_response - Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

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

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}/status

Get sensor status

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

Parameters:

id (integer)

Example request:

GET /api/v3_0/sensors/{id}/status HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

successful_response - Successful response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "staleness": "2 hours",
        "stale": true,
        "staleness_since": "2024-01-15T14:30:00+00:00",
        "reason": "data is outdated",
        "source_type": "forecast",
        "id": 64907,
        "name": "temperature",
        "resolution": "5 minutes",
        "asset_name": "Building A",
        "relation": "sensor belongs to this asset"
    }
]

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
404 Not Found – ASSET_NOT_FOUND
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

GET /api/v3_0/sensors

Get list of sensors

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.

Query Parameters:

account_id (integer)
asset_id (integer)
include_consultancy_clients (boolean)
include_public_assets (boolean)
page (integer)
per_page (integer)
filter (string)
unit (string)

Example request:

GET /api/v3_0/sensors HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED - List of sensors (paginated or direct list)

direct_list - Direct sensor list:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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\u00b3/h",
            "id": 2
        }
    ]
}

paginated_response - Paginated sensor list:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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\u00b3/h",
            "id": 2
        }
    ],
    "num-records": 1,
    "filtered-records": 1
}

400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

POST /api/v3_0/sensors

Create a new Sensor

This endpoint creates a new sensor for a given asset.

create_sensor - Create power sensor:

POST /api/v3_0/sensors HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "power",
    "event_resolution": "PT1H",
    "unit": "kWh",
    "generic_asset_id": 1
}

Status Codes:

201 Created –

New Sensor

create_sensor - Power sensor response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "name": "power",
    "unit": "kWh",
    "entity_address": "ea1.2023-08.localhost:fm1.1",
    "event_resolution": "PT1H",
    "generic_asset_id": 1,
    "timezone": "UTC",
    "id": 2
}

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

POST /api/v3_0/sensors/{id}/schedules/trigger

Trigger scheduling job for one device

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 the documentation on describing flexibility. 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: To schedule an EMS with multiple flexible sensors at once, use the Assets scheduling endpoint instead.

About the duration of the schedule and targets within the schedule:

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 the config setting FLEXMEASURES_MAX_PLANNING_HORIZON, which defaults to 2520 steps of the sensor’s resolution. Targets that exceed the max planning horizon are not accepted.

About the scheduling algorithm being used:

The appropriate algorithm is chosen by FlexMeasures (based on asset type).
It’s also possible to use custom schedulers and custom flexibility models.
If you have ideas for algorithms that should be part of FlexMeasures, let us know: https://flexmeasures.io/get-in-touch/

Parameters:

id (integer)

simple_schedule - Simple storage schedule:

POST /api/v3_0/sensors/{id}/schedules/trigger HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "start": "2025-06-02T10:00:00+00:00",
    "flex-context": {
        "consumption-price": ".2 EUR/kWh"
    },
    "flex-model": {
        "soc-at-start": "12.1 kWh",
        "soc-max": "25 kWh"
    }
}

complex_schedule - Complex 24-hour schedule:

POST /api/v3_0/sensors/{id}/schedules/trigger HTTP/1.1
Host: example.com
Content-Type: application/json

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

Status Codes:

200 OK –

PROCESSED

schedule_created - Schedule response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "PROCESSED",
    "schedule": "364bfd06-c1fa-430b-8d25-8f5a547651fb",
    "message": "Request has been processed."
}

400 Bad Request – INVALID_DATA
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

POST /api/v3_0/sensors/{id}/data/upload

Upload sensor data by file

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.

Parameters:

id (integer)

Status Codes:

200 OK –

PROCESSED

new_data - New data:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Request has been processed.",
    "status": "PROCESSED"
}

processed_previously_received - Previously received data:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Some of the data has already been received and successfully processed.",
    "results": "PROCESSED",
    "status": "ALREADY_RECEIVED_AND_SUCCESSFULLY_PROCESSED"
}

returned_graph_data - Returned graph data:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "ts": 1759669200000,
            "sid": 3,
            "val": 12.4,
            "sf": 1.0,
            "src": 1,
            "bh": -427962881
        }
    ],
    "sensors": {
        "3": {
            "name": "TempSensor_A1X",
            "unit": "\u00b0C",
            "description": "TempSensor_A1X (toy-account)",
            "asset_id": 1,
            "asset_description": "toy-account"
        }
    },
    "sources": {
        "1": {
            "name": "toy-user",
            "model": "",
            "type": "other",
            "description": "toy-user"
        }
    }
}

400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

Accounts

GET /api/v3_0/accounts/{id}/auditlog

Get the history of actions for a specific account.

This endpoint retrieves a log of historical actions and events associated with the account, identified by its ID.

Parameters:

id (integer) – The ID of the account whose history is being requested.

Example request:

GET /api/v3_0/accounts/{id}/auditlog HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

account_history_list - A list of account history events:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "event": "User test user deleted",
        "event_datetime": "2021-01-01T00:00:00",
        "active_user_id": 1
    },
    {
        "event": "Account name changed to \"New Corp\"",
        "event_datetime": "2021-01-02T10:30:00",
        "active_user_id": 5
    }
]

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, or UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

GET /api/v3_0/accounts/{id}

Fetch one account.

This endpoint retrieves a single account, given its ID in the path. Access is restricted: only admins, consultants, and users belonging to the account itself are authorized to use this endpoint.

Parameters:

id (integer) – The ID of the account to retrieve.

Example request:

GET /api/v3_0/accounts/{id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "Test Account",
    "account_roles": [
        1,
        3
    ],
    "consultancy_account_id": 2
}

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, or UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

PATCH /api/v3_0/accounts/{id}

Update an existing account.

This endpoint updates the details for an existing account.

In the JSON body, sent in only the fields you want to update.

Restrictions on Fields:

The id field is read-only and cannot be updated.
The consultancy_account_id field can only be edited if the current user has an admin role.

Parameters:

id (integer) – The ID of the account to update.

Example request:

PATCH /api/v3_0/accounts/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Test Account Updated",
    "primary_color": "#1a3443",
    "secondary_color": "#f1a122",
    "logo_url": "https://example.com/logo.png",
    "consultancy_account_id": 2
}

Status Codes:

200 OK –

UPDATED (The entire updated account object is returned)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "name": "Test Account Updated",
    "account_roles": [
        1,
        3
    ],
    "primary_color": "#1a3443",
    "secondary_color": "#f1a122",
    "logo_url": "https://example.com/logo.png",
    "consultancy_account_id": 2
}

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, or UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY (e.g., trying to update ‘consultancy_account_id’ without admin rights)

GET /api/v3_0/accounts

List all accounts accessible to the current user.

This endpoint returns all accounts the current user has access to. Accessible accounts include the user’s own account, accounts for which the user is a consultant, and all accounts if the user has admin privileges.

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

If the page parameter is not provided, all accounts are returned, without pagination information. The result will be a list of accounts.
If a page parameter is provided, the response will be paginated, showing a specific number of accounts 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 accounts where each search term is either present in their name. The response schema for pagination is inspired by DataTables

Query Parameters:

page (integer)
per_page (integer)
filter (string)
sort_by (string)
sort_dir (string)

Example request:

GET /api/v3_0/accounts HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

single_account - One account being returned (no pagination requested):

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "name": "Test Account",
        "account_roles": [
            1,
            3
        ],
        "consultancy_account_id": 2,
        "primary_color": "#1a3443",
        "secondary_color": "#f1a122",
        "logo_url": "https://example.com/logo.png"
    }
]

paginated_accounts - A paginated list of accounts being returned:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "id": 1,
            "name": "Test Account",
            "account_roles": [
                1,
                3
            ],
            "consultancy_account_id": 2,
            "primary_color": "#1a3443",
            "secondary_color": "#f1a122",
            "logo_url": "https://example.com/logo.png"
        }
    ],
    "num-records": 1,
    "filtered-records": 1
}

400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

Users

GET /api/v3_0/users/{id}/auditlog

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

Parameters:

id (integer)

Query Parameters:

page (integer)
per_page (integer)
filter (string)
sort_by (string)
sort_dir (string)

Example request:

GET /api/v3_0/users/{id}/auditlog HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

paginated_response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "event": "User test user deleted",
            "event_datetime": "2021-01-01T00:00:00",
            "active_user_name": "Test user"
        }
    ],
    "num-records": 1,
    "filtered-records": 1
}

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/users/{id}

Get a user

This endpoint gets a user. Only admins or the members of the same account can use this endpoint.

Parameters:

id (integer)

Example request:

GET /api/v3_0/users/{id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

single_user - Single user response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "active": true,
        "email": "test_prosumer@seita.nl",
        "account_id": 1,
        "flexmeasures_roles": [
            1,
            3
        ],
        "id": 1,
        "timezone": "Europe/Amsterdam",
        "username": "Test Prosumer User",
        "last_login_at": "2022-05-09T10:47:13.410321",
        "last_seen_at": "2022-05-09T10:47:13.410321"
    }
}

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}

Update a user.

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

Parameters:

id (integer)

update_active:

PATCH /api/v3_0/users/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "active": false
}

Status Codes:

200 OK –

UPDATED

single_user:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "active": true,
            "email": "test_prosumer@seita.nl",
            "account_id": 1,
            "flexmeasures_roles": [
                1,
                3
            ],
            "id": 1,
            "timezone": "Europe/Amsterdam",
            "username": "Test Prosumer User",
            "last_login_at": "2022-05-09T10:47:13.410321",
            "last_seen_at": "2022-05-09T10:47:13.410321"
        }
    ]
}

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/users

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

Query Parameters:

page (integer)
per_page (integer)
filter (string)
sort_by (string)
sort_dir (string)
account_id (['integer', 'null'])
include_inactive (boolean)

Example request:

GET /api/v3_0/users HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

single_user:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "active": true,
            "email": "test_prosumer@seita.nl",
            "account_id": 13,
            "account": {
                "account_roles": [],
                "consultancy_account_id": null,
                "id": 29,
                "logo_url": null,
                "name": "AutoZoomAccount",
                "primary_color": null,
                "secondary_color": null
            },
            "flexmeasures_roles": [
                1,
                3
            ],
            "id": 1,
            "timezone": "Europe/Amsterdam",
            "username": "Test Prosumer User",
            "last_login_at": "2022-05-09T10:47:13.410321",
            "last_seen_at": "2022-05-09T10:47:13.410321"
        }
    ]
}

400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

POST /api/v3_0/users

Create new user

This endpoint creates a new user.

The following fields are required:

email
username
account_id

Other attributes/fields such as password and roles can be assigned or reset later.

Example request:

POST /api/v3_0/users HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "email": "string",
    "username": "string",
    "account_id": 1
}

Status Codes:

201 Created –

CREATED

single_user:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "data": [
        {
            "active": true,
            "email": "test_user@seita.nl",
            "account_id": 1,
            "flexmeasures_roles": [
                1,
                3
            ],
            "id": 1,
            "timezone": "Europe/Amsterdam",
            "username": "Test User"
        }
    ]
}

400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

PATCH /api/v3_0/users/{id}/password-reset

Password reset

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.

Parameters:

id (integer)

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

Assets

GET /api/v3_0/assets/{id}/sensors

Return 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

Parameters:

id (integer) – ID of the asset to fetch sensors for

Query Parameters:

page (integer)
per_page (integer)
filter (string)
sort_by (string)
sort_dir (string)

Example request:

GET /api/v3_0/assets/{id}/sensors HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

single_asset - One asset being returned in the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "id": 1,
            "name": "Test battery",
            "latitude": 10,
            "longitude": 100,
            "account_id": 2,
            "generic_asset_type": {
                "id": 1,
                "name": "battery"
            }
        }
    ]
}

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

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

GET /api/v3_0/assets/{id}/auditlog

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 DataTables

Parameters:

id (integer) – ID of the asset to get the history for.

Query Parameters:

page (integer)
per_page (integer)
filter (string)
sort_by (string)
sort_dir (string)

Example request:

GET /api/v3_0/assets/{id}/auditlog HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

DELETE /api/v3_0/assets/{id}

Delete an asset.

This endpoint deletes an existing asset, as well as all sensors and measurements recorded for it.

Parameters:

id (integer) – ID of the asset to delete.

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.

Parameters:

id (integer) – ID of the asset to fetch.

Example request:

GET /api/v3_0/assets/{id} HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

single_asset - One asset being returned in the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "generic_asset_type_id": 2,
    "name": "Test battery",
    "id": 1,
    "latitude": 10,
    "longitude": 100,
    "account_id": 1
}

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

Parameters:

id (integer) – ID of the asset to update.

single_asset - One asset being updated:

PATCH /api/v3_0/assets/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "latitude": 11.1,
    "longitude": 99.9
}

Status Codes:

200 OK –

PROCESSED

single_asset - the whole asset is returned in the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "generic_asset_type_id": 2,
    "name": "Test battery",
    "id": 1,
    "latitude": 11.1,
    "longitude": 99.9,
    "account_id": 1,
    "external_id": ""
}

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

Download an embeddable chart with time series data

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 in the developer documentation.

Parameters:

id (integer) – ID of the asset to download a chart for.

Query Parameters:

event_starts_after (string)
event_ends_before (string)
beliefs_after (string)
beliefs_before (string)
include_data (boolean)
combine_legend (boolean)
dataset_name (string)
height (string)
width (string)
chart_type (string)

Example request:

GET /api/v3_0/assets/{id}/chart HTTP/1.1
Host: example.com

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

GET /api/v3_0/assets/{id}/chart_data

Download time series for use in charts

Data for use in charts (in case you have the chart specs already).

Parameters:

id (integer) – ID of the asset to download data for.

Query Parameters:

event_starts_after (string)
event_ends_before (string)
beliefs_after (string)
beliefs_before (string)
most_recent_beliefs_only (boolean)
compress_json (boolean)

Example request:

GET /api/v3_0/assets/{id}/chart_data HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

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}/jobs

Get all background jobs related to 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.

Parameters:

id (integer) – ID of the asset to get the jobs for.

Example request:

GET /api/v3_0/assets/{id}/jobs HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

jobs - List of jobs:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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 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}/kpis

Get daily KPIs for an asset.

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.

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.

Parameters:

id (integer)

Query Parameters:

start (string) – Start time for KPI calculation
end (string) – End time for KPI calculation

Example request:

GET /api/v3_0/assets/{id}/kpis HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

kpi_response - KPI response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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 Bad Request – INVALID_DATA
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD

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 DataTables

Query Parameters:

page (integer)
per_page (integer)
filter (string)
sort_by (string)
sort_dir (string)
account_id (['integer', 'null'])
all_accessible (boolean)
include_public (boolean)

Example request:

GET /api/v3_0/assets HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

single_asset - One asset being returned in the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "id": 1,
            "name": "Test battery",
            "latitude": 10,
            "longitude": 100,
            "account_id": 2,
            "generic_asset_type": {
                "id": 1,
                "name": "battery"
            }
        }
    ]
}

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

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

POST /api/v3_0/assets

Creates a new asset.

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.

single_asset - Request to create a standalone asset:

POST /api/v3_0/assets HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Test battery",
    "generic_asset_type_id": 2,
    "account_id": 2,
    "latitude": 40,
    "longitude": 170.3
}

child_asset - Request to create an asset with a parent:

POST /api/v3_0/assets HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Test battery",
    "generic_asset_type_id": 2,
    "account_id": 2,
    "parent_asset_id": 10,
    "latitude": 40,
    "longitude": 170.3
}

Status Codes:

201 Created –

PROCESSED

single_asset - One asset being returned in the response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "generic_asset_type_id": 2,
    "name": "Test battery",
    "id": 1,
    "latitude": 10,
    "longitude": 100,
    "account_id": 1
}

child_asset - A child asset being returned in the response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "generic_asset_type_id": 2,
    "name": "Test battery",
    "id": 1,
    "latitude": 10,
    "longitude": 100,
    "account_id": 1
}

400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

GET /api/v3_0/assets/public

Return all public assets.

This endpoint returns all public assets.

Example request:

GET /api/v3_0/assets/public HTTP/1.1
Host: example.com

Status Codes:

200 OK – PROCESSED
400 Bad Request – INVALID_REQUEST
401 Unauthorized – UNAUTHORIZED
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

POST /api/v3_0/assets/{id}/schedules/trigger

Trigger scheduling job for any number of devices

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

Parameters:

id (integer) – ID of the asset to schedule.

storage_asset:

POST /api/v3_0/assets/{id}/schedules/trigger HTTP/1.1
Host: example.com
Content-Type: application/json

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

POST /api/v3_0/assets/{id}/schedules/trigger HTTP/1.1
Host: example.com
Content-Type: application/json

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

Status Codes:

200 OK –

PROCESSED

successful_response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "PROCESSED",
    "schedule": "364bfd06-c1fa-430b-8d25-8f5a547651fb",
    "message": "Request has been processed."
}

400 Bad Request – INVALID_DATA
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
422 Unprocessable Entity – UNPROCESSABLE_ENTITY

POST /api/v3_0/assets/default_asset_view

Update the default asset view for the current user

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”

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

POST /api/v3_0/assets/default_asset_view HTTP/1.1
Host: example.com
Content-Type: application/json

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

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

POST /api/v3_0/assets/default_asset_view HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "use_as_default": false
}

status 200:

PROCESSED

message - Message:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Default asset view updated successfully."
}

status 400:

INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

status 401:

UNAUTHORIZED

status 403:

INVALID_SENDER

status 422:

UNPROCESSABLE_ENTITY

POST /api/v3_0/assets/keep_legends_below_graphs

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

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.

Example request:

POST /api/v3_0/assets/keep_legends_below_graphs HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "keep_legends_below_graphs": true
}

Status Codes:

200 OK –

PROCESSED

message - Message:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Legend position preference updated successfully."
}

400 Bad Request – INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

GET /api/v3_0/assets/types

Get list of available asset types

Example request:

GET /api/v3_0/assets/types HTTP/1.1
Host: example.com

Status Codes:

200 OK –

PROCESSED

single_asset_type - One asset type being returned in the response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "name": "solar",
        "description": "solar panel(s)"
    }
]

Version 3.0

Summary

OpenAPI & SwaggerUI

API Details

Auth

Public

Sensors

Accounts

Users

Assets

Example values for default_asset_view:

Example values for `default_asset_view`: