update playground doc & add real data warning to ref page (#3506)

_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 %}

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>
 

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.

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