From 65c1ecaf17e1e6bc9e31caabf38959207c332678 Mon Sep 17 00:00:00 2001
From: Hans Pagel <hanspagel@users.noreply.github.com>
Date: Fri, 22 Aug 2025 11:49:49 +0200
Subject: [PATCH] feat: Scalar API Reference (#3485)

Co-authored-by: anthony lio <lionnet.ant@gmail.com>
Co-authored-by: Deborah Barnard <deborah@deborahwrites.com>
---
 _overrides/api.html       | 68 +++++++++++++++++++++++++++++++--------
 docs/api/api-reference.md | 55 ++++++++++++++++++++-----------
 2 files changed, 90 insertions(+), 33 deletions(-)

diff --git a/_overrides/api.html b/_overrides/api.html
index 71641a037..1eea093bc 100644
--- a/_overrides/api.html
+++ b/_overrides/api.html
@@ -1,30 +1,39 @@
 {% extends "main.html" %}
 
-{% block extrahead %}    
+{% block extrahead %}
 <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
 
-<!--
-Redoc doesn't change outer page styles
--->
 <style>
-
   body {
     margin: 0;
     padding: 0;
   }
 
+  .md-content__button {
+    position: absolute;
+    right: 4px;
+    top: 50px;
+    z-index: 1;
+  }
+
+  .md-typeset svg {
+    border: none;
+  }
+
   .md-main__inner  {
       width: 100%;
       margin-top: 0;
   }
 
-  .md-grid {
-      max-width: 100%;
+  .md-typeset .grid {
+    grid-gap: 0;
+    margin: 0;
   }
 
   .md-content__inner {
-    padding: 0;
     margin: 0;
+    padding: 0;
+    position: relative;
   }
 
   .md-content__inner > p {
@@ -39,14 +48,45 @@ Redoc doesn't change outer page styles
     margin-bottom: invalid;
   }
 
-  [dir=ltr] .md-typeset ol li, [dir=ltr] .md-typeset ul li {
-    margin-left: 0;
+  [dir=ltr] .md-typeset ol li, [dir=ltr] .md-typeset ul li,
+  [dir=ltr] .md-typeset ol, [dir=ltr] .md-typeset ul,
+  [dir=ltr] .md-typeset ul li ul {
+    margin: 0;
   }
 
-  [dir=ltr] .md-typeset ol, [dir=ltr] .md-typeset ul {
-    margin-left: 0;
-  }
+  /* API Reference styles */
+  .scalar-api-reference {
+    --scalar-custom-header-height: 48px;
 
+    h1,
+    h2,
+    h3,
+    table,
+    li,
+    kbd {
+      all: unset;
+    }
+
+    .sidebar-search {
+      border-style: solid;
+    }
+
+    .section-container {
+      padding-right: 4px !important;
+    }
+
+    .section-container:has(.show-more) {
+      background-color: transparent !important;
+    }
+
+	pre {
+		margin: 0;
+	}
+
+	.scalar-code-block {
+		padding: 10px !important;
+	}
+  }
 </style>
 
 {% endblock %}
@@ -99,4 +139,4 @@ Redoc doesn't change outer page styles
 ) %}
   {% include "partials/source-file.html" %}
 {% endif %}
-{% endblock %}
\ No newline at end of file
+{% endblock %}
diff --git a/docs/api/api-reference.md b/docs/api/api-reference.md
index 97d8eef64..76d559e57 100644
--- a/docs/api/api-reference.md
+++ b/docs/api/api-reference.md
@@ -10,23 +10,40 @@ description: API reference for n8n's public REST API.
 contentType: reference
 ---
 
+<!-- Mount point -->
+<div id="app"></div>
 
-<redoc
-  spec-url="/api/v1/openapi.yml"
-  disable-search
-  hide-hostname
-  theme='{
-    "typography": {
-      "fontSize": "14px",
-      "lineHeight": "1.2em",
-      "fontFamily": "\"Open sans\", Helvetica, sans-serif",
-      "headings": {
-        "fontFamily": "\"Open sans\", Helvetica, sans-serif"
-      }
-    },
-    "sidebar": {
-      "backgroundColor": "#eaeaea",
-      "width": "280px"
-    }
-  }' />
-<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
+<!-- Load the Script -->
+<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+
+<!-- Initialize the Scalar API Reference -->
+<script>
+	Scalar.createApiReference('#app', {
+		url: '/api/v1/openapi.yml',
+		// Avoid CORS issues
+        proxyUrl: 'https://proxy.scalar.com',
+		servers: [
+			{
+				url: 'https://{instance}.app.n8n.cloud/api/v1',
+				description: 'n8n cloud instance',
+				variables: {
+					instance: {
+						default: 'your-instance-name',
+					}
+				}
+			},
+			{
+				url: '{url}/api/v1',
+				description: 'self-hosted n8n instance',
+				variables: {
+					url: {
+						default: 'https://example.com',
+					}
+				}
+			},
+		],
+		forceDarkModeState: 'light',
+		hideDarkModeToggle: true,
+		hideClientButton: true,
+	})
+</script>