API endpoint for scheduling asset

documentation/api/change_log.rst

@@ -5,6 +5,12 @@ API change log
 
 .. note:: The FlexMeasures API follows its own versioning scheme. This is also reflected in the URL (e.g. `/api/v3_0`), allowing developers to upgrade at their own pace.
 
+v3.0-24 | 2025-06-10
+""""""""""""""""""""
+- New API endpoint `[POST] /assets/(id)/schedules/trigger <api/v3_0.html#post--api-v3_0-assets-(id)-schedules-trigger>`_ to schedule a site with multiple flexible devices.
+- Updated message for 404 Not Found on endpoints for managing assets: `/assets` (GET, POST) and `/assets/<id>` (GET, PATCH, DELETE).
+
+
 v3.0-23 | 2025-04-08
 """"""""""""""""""""
 

documentation/changelog.rst

@@ -14,6 +14,7 @@ v0.27.0 | August XX, 2025
 New features
 -------------
 
+* New API endpoint `[POST] /assets/(id)/schedules/trigger <api/v3_0.html#post--api-v3_0-assets-(id)-schedules-trigger>`_ to schedule a site with multiple flexible devices [see `PR #1065 <https://github.com/FlexMeasures/flexmeasures/pull/1065/>`_]
 * Add form to upload sensor data to the database [see `PR #1481 <https://github.com/FlexMeasures/flexmeasures/pull/1481>`_]
 * Allow editing users in the UI [see `PR #1502 <https://github.com/FlexMeasures/flexmeasures/pull/1502>`_]
 * Move various warnings to toast notifications [see `PR #1529 <https://github.com/FlexMeasures/flexmeasures/pull/1529>`_]

documentation/features/scheduling.rst

@@ -44,7 +44,7 @@ For more details on the possible formats for field values, see :ref:`variable_qu
 
 Where should you set these fields?
 Within requests to the API or by editing the relevant asset in the UI.
-If they are not sent in via the API (the endpoint triggering schedule computation), the scheduler will look them up on the `flex-context` field of the asset.
+If they are not sent in via the API (one of the endpoints triggering schedule computation), the scheduler will look them up on the `flex-context` field of the asset.
 And if the asset belongs to a larger system (a hierarchy of assets), the scheduler will also search if parent assets have them set.
 
 
@@ -156,7 +156,7 @@ The process scheduler is suitable for shiftable, breakable and inflexible loads,
 
 
 We describe the respective flex models below.
-At the moment, they have to be sent through the API (the endpoint to trigger schedule computation, or using the FlexMeasures client) or through the CLI (the command to add schedules).
+At the moment, they have to be sent through the API (one of the endpoints to trigger schedule computation, or using the FlexMeasures client) or through the CLI (the command to add schedules).
 We will soon work on the possibility to store (a subset of) these fields on the data model and edit them in the UI.
 
 
@@ -275,7 +275,7 @@ depending on the first target state of charge and the capabilities of the asset.
 
 Of course, we also log a failure in the scheduling job, so it's important to take note of these failures. Often, mis-configured flex models are the reason.
 
-For a hands-on tutorial on using some of the storage flex-model fields, head over to :ref:`tut_v2g` use case and `the API documentation for triggering schedules <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_.
+For a hands-on tutorial on using some of the storage flex-model fields, head over to :ref:`tut_v2g` use case and `the API documentation for triggering schedules <../api/v3_0.html#post--api-v3_0-assets-(id)-schedules-trigger>`_.
 
 Finally, are you interested in the linear programming details behind the storage scheduler?
 Then head over to :ref:`storage_device_scheduler`!

documentation/tut/forecasting_scheduling.rst

@@ -99,7 +99,7 @@ It usually involves a linear program that combines a state of energy flexibility
 There are two ways to queue a scheduling job:
 
 First, we can add a scheduling job to the queue via the API.
-We already learned about the `[POST] /schedules/trigger <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_ endpoint in :ref:`posting_flex_states`, where we saw how to post a flexibility state (in this case, the state of charge of a battery at a certain point in time).
+We already learned about the `[POST] /schedules/trigger <../api/v3_0.html#post--api-v3_0-assets-(id)-schedules-trigger>`_ endpoint in :ref:`posting_flex_states`, where we saw how to post a flexibility state (in this case, the state of charge of a battery at a certain point in time).
 
 Here, we extend that (storage) example with an additional target value, representing a desired future state of charge.
 
@@ -108,6 +108,7 @@ Here, we extend that (storage) example with an additional target value, represen
     {
         "start": "2015-06-02T10:00:00+00:00",
         "flex-model": {
+            "sensor": 15,
             "soc-at-start": "12.1 kWh",
             "soc-targets": [
                 {
@@ -130,7 +131,7 @@ A second way to add scheduling jobs is via the CLI, so this is available for peo
 
 .. code-block:: bash
 
-    $ flexmeasures add schedule for-storage --sensor 1 --consumption-price-sensor 2 \
+    $ flexmeasures add schedule for-storage --sensor 15 --consumption-price-sensor 2 \
         --start 2022-07-05T07:00+01:00 --duration PT12H \
         --soc-at-start 50% --roundtrip-efficiency 90% --as-job
 
@@ -154,7 +155,7 @@ A prognosis can be requested at a URL looking like this:
 
 .. code-block:: html
 
-    https://company.flexmeasures.io/api/<version>/sensors/data
+    https://company.flexmeasures.io/api/v3_0/sensors/data
 
 This example requests a prognosis for 24 hours, with a rolling horizon of 6 hours before realisation.
 
@@ -180,11 +181,23 @@ We saw above how FlexMeasures can create optimised schedules with control signal
 
 .. code-block:: html
 
-    https://company.flexmeasures.io/api/<version>/sensors/<id>/schedules/<uuid>
+    https://company.flexmeasures.io/api/v3_0/sensors/<id>/schedules/<uuid>
 
-Here, the schedule's Universally Unique Identifier (UUID) should be filled in that is returned in the `[POST] /schedules/trigger <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_ response.
+Here, the schedule's Universally Unique Identifier (UUID) should be filled in that is returned in the `[POST] /schedules/trigger <../api/v3_0.html#post--api-v3_0-assets-(id)-schedules-trigger>`_ response.
 Schedules can be queried by their UUID for up to 1 week after they were triggered (ask your host if you need to keep them around longer).
 Afterwards, the exact schedule can still be retrieved through the `[GET] /sensors/data <../api/v3_0.html#get--api-v3_0-sensors-data>`_, using precise filter values for ``start``, ``prior`` and ``source``.
+Besides the UUID, the endpoint for retrieving schedules takes a sensor ID, which is the sensor ID of one of the power sensors that was referenced in the flex model.
+
+.. note:: If a ``state-of-charge`` sensor was referenced in the flex model (like in the example below), the scheduled state of charge can be retrieved using the same endpoint and UUID, but then using the state-of-charge sensor ID.
+
+          .. code-block:: json
+
+              "flex-model": {
+                  "sensor": 15,
+                  "state-of-charge": {"sensor": 16}
+              }
+
+          For instance, if the above snippet represents the flex model used by FlexMeasures to compute the schedule, then to fetch the scheduled state of charge you simply replace the power sensor ID in the URL of the `[GET] /sensors/data <../api/v3_0.html#get--api-v3_0-sensors-data>`_ endpoint with the state-of-charge sensor ID.
 
 The following example response indicates that FlexMeasures planned ahead 45 minutes for the requested battery power sensor.
 The list of consecutive power values represents the target consumption of the battery (negative values for production).
@@ -212,3 +225,8 @@ However, because the targets values represent averages over 15-minute time inter
 For example, the battery might start to consume with 2.1 MW at 10.00am and increase its consumption to 2.25 at 10.10am,
 increase its consumption to 5 MW at 10.15am and decrease its consumption to 2 MW at 10.20am.
 That should result in the same average values for each quarter-hour.
+
+Likewise, the control signals can be used to schedule devices that only run at specific power levels.
+For example, let's assume the battery only supports running at an integer number of MW.
+In that case, the battery could start to consume with 2 MW at 10.00am, increase its consumption to 3 MW at (15 seconds before) 10.12am, and decrease its consumption to 2 MW at 10.30am.
+Again, this results in the same average values for each quarter-hour.

documentation/tut/posting_data.rst

@@ -46,7 +46,7 @@ The exact URL will depend on your domain name, and will look approximately like
 
 .. code-block:: html
 
-    [POST] https://company.flexmeasures.io/api/<version>/sensors/data
+    [POST] https://company.flexmeasures.io/api/v3_0/sensors/data
 
 This example "PostSensorDataRequest" message posts prices for hourly intervals between midnight and midnight the next day
 for the Korean Power Exchange (KPX) day-ahead auction, registered under sensor 16.
@@ -271,28 +271,46 @@ There is one more crucial kind of data that FlexMeasures needs to know about: Wh
 For example, a battery has a certain state of charge, which is relevant to describe the flexibility that the battery currently has.
 In our terminology, this is called the "flex model" and you can read more at :ref:`describing_flexibility`.
 
-Owners of such devices can post the flex model along with triggering the creation of a new schedule, to `[POST] /schedules/trigger <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_.
+Owners of such devices can post the flex model along with triggering the creation of a new schedule, to one of two endpoints:
+
+1. `[POST] /assets/<id>/schedules/trigger <../api/v3_0.html#post--api-v3_0-assets-(id)-schedules-trigger>`_ - for scheduling multiple devices
+2. `[POST] /sensors/<id>/schedules/trigger <../api/v3_0.html#post--api-v3_0-sensors-(id)-schedules-trigger>`_ - for scheduling a single device (which can also be done with the first endpoint)
+
 The URL might look like this:
 
 .. code-block:: html
 
-    https://company.flexmeasures.io/api/<version>/sensors/10/schedules/trigger
+    https://company.flexmeasures.io/api/v3_0/assets/10/schedules/trigger
 
-The following example triggers a schedule for a power sensor (with ID 10) of a battery asset, asking to take into account the battery's current state of charge.
+The following example triggers a schedule for a power sensor (with ID 15) of a battery asset (with ID 10), asking to take into account the battery's current state of charge.
 From this, FlexMeasures derives the energy flexibility this battery has in the next 48 hours and computes an optimal charging schedule.
 The endpoint also allows to limit the flexibility range and also to set target values.
 
 .. code-block:: json
 
         {
             "start": "2015-06-02T10:00:00+00:00",
-            "flex-model": {
-                "soc-at-start": "12.1 kWh"
-            }
+            "flex-model": [
+                {
+                    "sensor": 15,
+                    "soc-at-start": "12.1 kWh"
+                }
+            ]
         }
 
 .. note:: More details on supported flex models can be found in :ref:`flex_models_and_schedulers`.
 
-.. note:: Flexibility states are persisted on sensor attributes. To record a more complete history of the state of charge, set up a separate sensor and post data to it using `[POST] /sensors/data <../api/v3_0.html#post--api-v3_0-sensors-data>`_ (see :ref:`posting_sensor_data`).
+.. note::
+    Flexibility states posted in trigger messages are only stored temporarily to describe the scheduling job.
+    To record a more complete history of the flexibility state, set up separate sensors and post data to them using `[POST] /sensors/data <../api/v3_0.html#post--api-v3_0-sensors-data>`_ (see :ref:`posting_sensor_data`).
+    Then reference those sensors in your flex model.
+    For example, say you use sensor 82 to record the power-to-heat efficiency of a heating system, then use this sensor reference in your flex model:
+
+    .. code-block:: json
+
+        {
+            "charging-efficiency": {"sensor": 82}
+        }
+
 
 In :ref:`how_queue_scheduling`, we'll cover what happens when FlexMeasures is triggered to create a new schedule, and how those schedules can be retrieved via the API, so they can be used to steer assets.

documentation/tut/toy-example-expanded.rst

@@ -63,7 +63,7 @@ Setting the data source type to "forecaster" helps FlexMeasures to visually dist
     $ flexmeasures add beliefs --sensor 3 --source 4 solar-tomorrow.csv --timezone Europe/Amsterdam
     Successfully created beliefs
 
-The one-hour CSV data is automatically resampled to the 15-minute resolution of the sensor that is recording solar production. We can see solar production in the `FlexMeasures UI <http://localhost:5000/sensors/3>`_ :
+The one-hour CSV data is automatically resampled to the 15-minute resolution of the sensor that is recording solar production. We can see solar production in the `FlexMeasures UI <http://localhost:5000/sensors/3>`_:
 
 .. image:: https://github.com/FlexMeasures/screenshots/raw/main/tut/toy-schedule/sensor-data-production.png
     :align: center
@@ -75,17 +75,139 @@ The one-hour CSV data is automatically resampled to the 15-minute resolution of
 Trigger an updated schedule
 ----------------------------
 
-Now, we'll reschedule the battery while taking into account the solar production. This will have an effect on the available headroom for the battery, given the ``site-power-capacity`` limit discussed earlier.
-
-.. code-block:: bash
-
-    $ flexmeasures add schedule for-storage --sensor 2 --consumption-price-sensor 1 \
-        --inflexible-device-sensor 3 \
-        --start ${TOMORROW}T07:00+02:00 --duration PT12H \
-        --soc-at-start 50% --roundtrip-efficiency 90%
-    New schedule is stored.
-
-We can see the updated scheduling in the `FlexMeasures UI <http://localhost:5000/sensors/2>`_ :
+Now, we'll reschedule the battery while taking into account the solar production (forecast) as an inflexible device.
+This will have an effect on the available headroom for the battery, given the ``site-power-capacity`` limit discussed earlier.
+
+.. tabs::
+
+    .. tab:: CLI
+
+        .. code-block:: bash
+            :emphasize-lines: 3
+
+            $ flexmeasures add schedule for-storage \
+                --sensor 2 \
+                --inflexible-device-sensor 3 \
+                --start ${TOMORROW}T07:00+01:00 \
+                --duration PT12H \
+                --soc-at-start 50% \
+                --roundtrip-efficiency 90%
+            New schedule is stored.
+
+    .. tab:: API
+
+        Example call: `[POST] http://localhost:5000/api/v3_0/assets/2/schedules/trigger <../api/v3_0.html#post--api-v3_0-assets-(id)-schedules-trigger>`_ (update the start date to tomorrow):
+
+        .. code-block:: json
+            :emphasize-lines: 11-13
+
+            {
+                "start": "2025-06-11T07:00+01:00",
+                "duration": "PT12H",
+                "flex-model": [
+                    {
+                        "sensor": 2,
+                        "soc-at-start": "50%",
+                        "roundtrip-efficiency": "90%"
+                    }
+                ],
+                "flex-context": {
+                    "inflexible-device-sensors": [3]
+                }
+            }
+
+        Alternatively, if the solar production is curtailable, move the solar production to the flex-model.
+        There, we tell the scheduler to pick any production value between 0 and the production forecast recorded on sensor 3, and to store the resulting schedule on sensor 3 as well (the FlexMeasures UI will still be able to distinguish forecasts from schedules):
+
+        .. code-block:: json
+            :emphasize-lines: 10-14,16
+
+            {
+                "start": "2025-06-11T07:00+01:00",
+                "duration": "PT12H",
+                "flex-model": [
+                    {
+                        "sensor": 2,
+                        "soc-at-start": "50%",
+                        "roundtrip-efficiency": "90%"
+                    },
+                    {
+                        "sensor": 3,
+                        "consumption-capacity": "0 kW",
+                        "production-capacity": {"sensor": 3},
+                    }
+                ],
+                "flex-context": {}
+            }
+
+    .. tab:: FlexMeasures Client
+
+        Using the `FlexMeasures Client <https://pypi.org/project/flexmeasures-client/>`_:
+
+        .. code-block:: bash
+
+            pip install flexmeasures-client
+
+        .. code-block:: python
+            :emphasize-lines: 22-24
+
+            import asyncio
+            from datetime import date
+            from flexmeasures_client import FlexMeasuresClient as Client
+
+            async def client_script():
+                client = Client(
+                    email="[email protected]",
+                    password="toy-password",
+                    host="localhost:5000",
+                )
+                schedule = await client.trigger_and_get_schedule(
+                    asset_id=2,  # Toy building (asset ID)
+                    start=f"{date.today().isoformat()}T07:00+01:00",
+                    duration="PT12H",
+                    flex_model=[
+                        {
+                            "sensor": 2,  # battery power (sensor ID)
+                            "soc-at-start": "50%",
+                            "roundtrip-efficiency": "90%",
+                        },
+                    ],
+                    flex_context={
+                        "inflexible-device-sensors": [3],  # solar production (sensor ID)
+                    },
+                )
+                print(schedule)
+                await client.close()
+
+            asyncio.run(client_script())
+
+        Alternatively, if the solar production is curtailable, move the solar production to the flex-model:
+
+        .. code-block:: python
+            :emphasize-lines: 11-15,17
+
+            schedule = await client.trigger_and_get_schedule(
+                asset_id=2,  # Toy building (asset ID)
+                start=f"{date.today().isoformat()}T07:00+01:00",
+                duration="PT12H",
+                flex_model=[
+                    {
+                        "sensor": 2,  # battery power (sensor ID)
+                        "soc-at-start": "50%",
+                        "roundtrip-efficiency": "90%",
+                    },
+                    {
+                        "sensor": 3,  # solar production (sensor ID)
+                        "consumption-capacity": "0 kW",
+                        "production-capacity": {"sensor": 3},
+                    },
+                ],
+                flex_context={},
+            )
+
+
+
+We can see the updated scheduling in the `FlexMeasures UI <http://localhost:5000/sensors/2>`_:
 
 .. image:: https://github.com/FlexMeasures/screenshots/raw/main/tut/toy-schedule/sensor-data-charging-with-solar.png
     :align: center
@@ -117,7 +239,7 @@ In the case of the scheduler that we ran in the previous tutorial, which did not
 
 .. note:: You can add arbitrary sensors to a chart using the asset UI or the attribute ``sensors_to_show``. See :ref:`view_asset-data` for more.
 
-A nice feature is that you can check the data connectivity status of your building asset. Now that we have made the schedule, both lamps are green. You can also view it in `FlexMeasures UI <http://localhost:5000/assets/2/status>`_ :
+A nice feature is that you can check the data connectivity status of your building asset. Now that we have made the schedule, both lamps are green. You can also view it in `FlexMeasures UI <http://localhost:5000/assets/2/status>`_:
 
 .. image:: https://github.com/FlexMeasures/screenshots/raw/main/tut/toy-schedule/screenshot_building_status.png
     :align: center