Skip to main content

API change log

While we endeavour not to change the API in a backwards-incompatible way, this is not always possible. This page contains a history of changes to the API.

Production
These changes are live in both production and staging environments.
Staging
Changes marked with this badge are already live in the staging environment, but have not yet been released in the production environment. The date represents when the change will become available in production.
Not yet released
These changes are not yet available in either environment, but are included to warn of an upcoming change to the API.

To learn more about our environments, see the introduction to the API.

24th Feb 2025 ​

  • Stable versions introduced. It is now possible to access stable environments for stable results. More on accessing these stable API endpoints can be found here.
  • The introduction of stable versions also means that saved scenarios and collections have version tags associated with them now. These are included in the API responses.
  • The saved scenario API response now includes a saved_scenario_users field. Learn more here.

3rd September 2024 ​

  • Uncoupling scenarios has changed. It's now possible to recouple your scenario after deactivating a coupling.

5th December 2023 ​

  • The ETM now supports three heat networks instead of one, differentiating in temperature levels. Updating your heat network order via the API has changed.

6th June 2023 ​

7th February 2023 ​

10th January 2023 ​

  • Authentication has come to the API! You can now create personal access tokens for your account. Scenarios will be linked to your account which prevents others from making changes to your data.
  • Scenarios:
    • API endpoints have been added for listing and deleting your scenarios.
    • Scenarios have a new private attribute available to authenticated users. This allows you to prevent other API users from viewing your scenario.
    • The scenario protected attribute has been removed.
    • The scenario read_only attribute has been removed. To prevent others from changing your scenario, please sign up for an account and see the page on authentication and personal access tokens.
    • The scenario title and description attributes have been removed. Please use the scenario metadata attribute instead. See the change log entry from 5th April 2022 for more information.
    • An undocumented and unsupported include_inputs parameter has been removed from the scenario endpoint. The scenario slider settings are still available through the scenarios endpoint using the the user_values attribute, or you can fetch the full list of inputs through the inputs endpoint.
    • The detailed parameter has been removed from the scenario endpoint. Scenario data will now include all information about the scenario without the need for this parameter.
  • An API for saved scenarios has been added. Saved scenarios allow you show scenarios in your list scenarios in the ETM web application, and more easily share your scenarios with others.
  • An API for transition paths has been added. Transition paths allow you to work with scenarios across multiple end years and plot their results in a chart.

3rd May 2022 ​

  • The scenario protected attribute is deprecated and has been split into two separate attributes: read_only and keep_compatible. The protected attribute continues to be supported as an alias of read_only, and scenarios marked as protected will behave as they did before.

5th April 2022 ​

  • Scenarios should no longer be given a title or description attribute. If you wish to store such data with your scenarios, please use the scenario metadata.

    {
      "scenario": {
        "metadata": {
          "title": "My scenario"
        }
      }
    }

    For the moment, title and description continue to be supported, and will result in the corresponding metadata keys being set. This feature will be removed later in May 2022.

    Example request
    PUT /api/v3/scenarios/12345 HTTP/2
    Host: engine.energytransitionmodel.com
    Accept: application/json

    {
      "scenario": {
        "title": "My scenario",
        "description": "A description"
      },
      "detailed": true
    }
    Example response
    {
      "id": 12345,
      // ...
      "title": "My scenario",
      "description": "A description"
      "metadata": {
        "title": "My scenario",
        "description": "A description"
      }
    }

1st February 2022 ​

  • Scenarios marked as protected are now read-only. Changes to a protected scenario are not permitted and will be rejected with a 403 Forbidden response. Read more →
  • Inputs may now contain a disabled_by attribute which lists other input keys in an array. The input will be disabled if any of the specified inputs have a value provided by the user. Read more →
  • Old node endpoints /api/v3/converters and /api/v3/converters/{node_id} have been removed. You can still access this data by first creating a scenario.