Scenario interpolation

data/api/scenario.js

@@ -33,6 +33,32 @@ export default {
     method: "POST",
     token: { scopes: ["scenarios:read"], type: "optional" },
   },
+  interpolate: {
+    endpoint: "/api/v3/scenarios/{id}/interpolate",
+    method: "POST",
+    path_parameters: [scenarioIdParam],
+    parameters: [
+      {
+        name: "start_scenario_id",
+        type: "number",
+        description:
+          "the ID of the scenario whose input values are used as the interpolation starting point, if provided. Must match the endpoint scenario’s start year and area code",
+        required: false,
+      },
+      {
+        name: "end_year",
+        type: "number",
+        description:
+          `end year of the scenario (interpolation target year)<br>
+          <ul>
+            <li>Must fall between the endpoint scenario’s start and end years when <code>start_scenario_id</code> is <strong>not</strong> provided</li>
+            <li>Must fall between the start scenario and the endpoint scenario end years when <code>start_scenario_id</code> is provided</li>
+          </ul>`,
+        required: true,
+      },
+    ],
+    token: { scopes: ["scenarios:read"], type: "optional" },
+  },
   update: {
     endpoint: "/api/v3/scenarios/{id}",
     method: "PUT",

data/releases.js

@@ -154,6 +154,12 @@ export const mainReleases = [
 
 // API changelog timeline data
 export const apiChangelog = [
+  {
+    date: "Jan 8, 2025",
+    title: "Scenario interpolation",
+    file: "2026-01.md",
+    tag: "2026.01",
+  },
   {
     date: "Dec 11, 2025",
     title: "Managing collections",

docs/api/scenarios.md

@@ -163,9 +163,8 @@ Authorization: Bearer YOUR_TOKEN
 
 ## Create a scenario
 
-A scenario can be created in three ways: as a blank scenario for an area and end year, as a new
-scenario with certain sliders set, or as a scenario based on another scenario (its preset). All
-creation methods use a POST request on the scenario endpoint, but with different data.
+A scenario can be created in four ways: as a blank scenario for an area and end year, as a new
+scenario with certain sliders set, as a scenario based on another scenario (its preset), or as an interpolated scenario. The first three methods use a POST request on the scenario endpoint, but with different data.
 
 ### Create a blank scenario
 
@@ -288,6 +287,39 @@ Authorization: Bearer YOUR_TOKEN
 }
 ```
 
+### Create an interpolated scenario for a transition path
+
+Creates a scenario meant for use in a transition path, which is a specific type of [collection](/api/collections). The key feature of this method is that the scenario’s inputs are calculated by linearly interpolating the endpoint scenario’s input values against its own starting inputs or another scenario’s inputs.
+
+<ApiEndpoint data={endpointData.interpolate} />
+
+```http title="Example request"
+POST /api/v3/scenarios/22222/interpolate HTTP/2
+Host: engine.energytransitionmodel.com
+Accept: application/json
+Authorization: Bearer YOUR_TOKEN
+
+{
+  "start_scenario_id": "11111",
+  "end_year": "2040"
+}
+```
+
+```json title="Example response"
+{
+  "id": 123456,
+  "area_code":"nl",
+  "start_year": 2019,
+  "end_year": 2040,
+  "url": "https://engine.energytransitionmodel.com/api/v3/scenarios/123456",
+  ...
+  "user_values": {
+    "buildings_insulation_level": 40.3,
+    "capacity_of_energy_power_hydro_river": 39.0
+  }
+}
+```
+
 ## Set sliders in a scenario
 
 :::info Available inputs

static/api-changelog/2026-01.md

@@ -0,0 +1 @@
+* Ability to create and interpolated scenario between two scenarios. [Learn more here.](/api/scenarios#create-an-interpolated-scenario-for-a-transition-path)