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

Data

GET /api/v3_0/sensors/data

Download sensor data

POST /api/v3_0/sensors/data

Upload sensor data

Schedule

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

Download schedule from the platform

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

Trigger scheduling job

Sensor

GET /api/v3_0/sensors

Download sensor list

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

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

Password reset

API Details

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
Response Headers
Status Codes
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
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/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": 15,
        "generic_asset_id": 1,
        "name": "Gas demand",
        "timezone": "Europe/Amsterdam",
        "unit": "m³/h"
    }
]
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.

The message should contain a flexibility model.

Example request A

This message triggers a schedule starting at 10.00am, at which the state of charge (soc) is 12.1 kWh.

{
    "start": "2015-06-02T10:00:00+00:00",
    "soc-at-start": 12.1,
    "soc-unit": "kWh"
}

Example request B

This message triggers a schedule 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 minimum and maximum soc are set to 10 and 25 kWh, respectively. Roundtrip efficiency for use in scheduling is set to 98%.

{
    "start": "2015-06-02T10:00:00+00:00",
    "soc-at-start": 12.1,
    "soc-unit": "kWh",
    "soc-targets": [
        {
            "value": 25,
            "datetime": "2015-06-02T16:00:00+00:00"
        }
    ],
    "soc-min": 10,
    "soc-max": 25,
    "roundtrip-efficiency": 0.98
}

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/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",
    "unit": "m³/h"
}

The unit has to be convertible from the sensor’s unit.

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

Request Headers
Response Headers
Status Codes
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
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 user themselves 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. Any subset of user fields can be sent. Only the user themselves or admins are allowed to update its data, while a non-admin can only edit a few of their own fields.

The following fields are not allowed to be updated:
  • 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
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