From 6797130e2ba340c989e499bd9280e24501cc4aa3 Mon Sep 17 00:00:00 2001
From: Deborah Barnard <deborah@deborahwrites.com>
Date: Fri, 22 Aug 2025 11:47:51 +0100
Subject: [PATCH] update playground doc & add real data warning to ref page
 (#3506)

---
 _overrides/api.html              | 65 +++++++++++---------------------
 docs/api/api-reference.md        |  1 +
 docs/api/using-api-playground.md | 23 ++++++++++-
 nav.yml                          |  2 +-
 4 files changed, 44 insertions(+), 47 deletions(-)

diff --git a/_overrides/api.html b/_overrides/api.html
index 1eea093bc..d9ccaa8fc 100644
--- a/_overrides/api.html
+++ b/_overrides/api.html
@@ -87,56 +87,33 @@
 		padding: 10px !important;
 	}
   }
+
+  .n8n-api-warning {
+    background-color: #FDF6EC;
+    font-size: 1.5em;
+    padding: 0.25em;
+    text-align: center;
+  }
+
+  .n8n-api-warning > a {
+    color: var(--color-primary);
+  }
 </style>
 
 {% endblock %}
+
+{% block tabs %}
+
+{{ super() }}
+
+<div class="n8n-api-warning">Using the playground to test API calls uses real data. Use with caution. Refer to <a href="https://docs.n8n.io/api/using-api-playground/">Using an API playground</a> for more information.</div>
+
+{% endblock %}
+
 {% block content %}
-<!--
-  Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
-
-  Permission is hereby granted, free of charge, to any person obtaining a copy
-  of this software and associated documentation files (the "Software"), to
-  deal in the Software without restriction, including without limitation the
-  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
-  sell copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
-
-  The above copyright notice and this permission notice shall be included in
-  all copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-  IN THE SOFTWARE.
--->
-
-<!-- Edit button -->
-{% if page.edit_url %}
-  <a
-    href="{{ page.edit_url }}"
-    title="{{ lang.t('edit.link.title') }}"
-    class="md-content__button md-icon"
-  >
-    {% include ".icons/material/pencil.svg" %}
-  </a>
-{% endif %}
-
-<!-- Tags -->
-{% if "tags" in config.plugins %}
-  {% include "partials/tags.html" %}
-{% endif %}
 
 <!-- Markdown content -->
 {{ page.content }}
 
-<!-- Source file information -->
-{% if page and page.meta and (
-  page.meta.git_revision_date_localized or
-  page.meta.revision_date
-) %}
-  {% include "partials/source-file.html" %}
-{% endif %}
+
 {% endblock %}
diff --git a/docs/api/api-reference.md b/docs/api/api-reference.md
index 76d559e57..abf4d62b9 100644
--- a/docs/api/api-reference.md
+++ b/docs/api/api-reference.md
@@ -10,6 +10,7 @@ description: API reference for n8n's public REST API.
 contentType: reference
 ---
 
+
 <!-- Mount point -->
 <div id="app"></div>
 
diff --git a/docs/api/using-api-playground.md b/docs/api/using-api-playground.md
index afb9ccdaf..bdedd4a4b 100644
--- a/docs/api/using-api-playground.md
+++ b/docs/api/using-api-playground.md
@@ -1,10 +1,29 @@
 ---
 #https://www.notion.so/n8n/Frontmatter-432c2b8dff1f43d4b1c8d20075510fe4
-description: How to use the API playground to try out n8n's public REST API.
+description: How to use an API playground to try out n8n's public REST API.
 contentType: howto
 ---
 
-# Using the API playground
+# Using an API playground
+
+This documentation site provides a playground to test out calls. Self-hosted users also have access to a built-in playground hosted as part of their instance.
+
+## Documentation playground
+
+You can test API calls from this site's [API reference](api-reference.md). You need to set your server's base URL and instance name, and add an API key.
+
+n8n uses [Scalar's](https://github.com/scalar/scalar) open source API platform to power this functionality.
+
+/// warning | Exposed API key and data
+Use a test API key with limited scopes and test data when using a playground. All calls from the playground are routed through Scalar's proxy servers.
+///
+
+/// warning | Real data
+You have access to your live data. This is useful for trying out requests. Be aware you can change or delete real data.
+///
+
+
+## Built-in playground
 
 /// info | Feature availability
 The API playground isn't available on Cloud. It's available for all self-hosted pricing tiers.
diff --git a/nav.yml b/nav.yml
index b47e6fd7b..09630c9f3 100644
--- a/nav.yml
+++ b/nav.yml
@@ -1324,7 +1324,7 @@ nav:
       - api/index.md
       - Authentication: api/authentication.md
       - Pagination: api/pagination.md
-      - Using the API playground: api/using-api-playground.md
+      - Using an API playground: api/using-api-playground.md
       - API reference: api/api-reference.md
   - Embed:
       - embed/index.md