From 4a711f71a4867b14b4900d5e10f28d26683c0f6a Mon Sep 17 00:00:00 2001
From: aaccensi <andreu.accensi@gmail.com>
Date: Wed, 17 Dec 2025 11:26:46 +0100
Subject: [PATCH 1/2] Add documentation pertinent to the scenario interpolate
 API endpoint

References quintel/etengine#1684
---
 data/api/scenario.js  | 26 ++++++++++++++++++++++++++
 docs/api/scenarios.md | 38 +++++++++++++++++++++++++++++++++++---
 2 files changed, 61 insertions(+), 3 deletions(-)

diff --git a/data/api/scenario.js b/data/api/scenario.js
index a54b73f5..f5d2f2e8 100644
--- a/data/api/scenario.js
+++ b/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",
diff --git a/docs/api/scenarios.md b/docs/api/scenarios.md
index 74d45fac..ba10756b 100644
--- a/docs/api/scenarios.md
+++ b/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

From a61f3396c68e17bdf8b25e065ede84dfc2bd8961 Mon Sep 17 00:00:00 2001
From: aaccensi <andreu.accensi@gmail.com>
Date: Wed, 17 Dec 2025 11:54:51 +0100
Subject: [PATCH 2/2] Add changelog entry for 2026-01

References quintel/etengine#1684
---
 data/releases.js                | 6 ++++++
 static/api-changelog/2026-01.md | 1 +
 2 files changed, 7 insertions(+)
 create mode 100644 static/api-changelog/2026-01.md

diff --git a/data/releases.js b/data/releases.js
index 84688d5d..4bb9e478 100644
--- a/data/releases.js
+++ b/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",
diff --git a/static/api-changelog/2026-01.md b/static/api-changelog/2026-01.md
new file mode 100644
index 00000000..559342ff
--- /dev/null
+++ b/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)