diff --git a/docs/api/includes/welcome b/docs/api/includes/welcome
index b91002e024..3a299d097a 100644
--- a/docs/api/includes/welcome
+++ b/docs/api/includes/welcome
@@ -11,6 +11,10 @@ If anything is missing or seems incorrect, please check the <a href="https://www
 Also, if you are new to ZAP, then check out the <a href="https://www.zaproxy.org/getting-started/">getting started guide</a> 
 to learn the basic concepts behind ZAP. </p>
 
+<p>An <a href="https://swagger.io/">OpenAPI definition</a> for the ZAP API is <a href="https://raw.githubusercontent.com/zaproxy/zap-api-docs/main/openapi.yaml">available in the main repository</a>, which can be used to generate custom API clients.
+This definition is planned to be kept up to date for the latest core and add-on releases.
+Note that currently the definition does not declare the most appropriate types for the parameters and does not contain the responses.</p>
+
 <p>The following are some of the features provided by ZAP:</p>
 
 <ul>
diff --git a/docs/api/index.html b/docs/api/index.html
index 181c3f08f6..d6a03cfd1b 100644
--- a/docs/api/index.html
+++ b/docs/api/index.html
@@ -2568,6 +2568,10 @@ <h1 id='introduction'>Introduction</h1><h2 id='overview'>Overview</h2>
 Also, if you are new to ZAP, then check out the <a href="https://www.zaproxy.org/getting-started/">getting started guide</a> 
 to learn the basic concepts behind ZAP. </p>
 
+<p>An <a href="https://swagger.io/">OpenAPI definition</a> for the ZAP API is <a href="https://raw.githubusercontent.com/zaproxy/zap-api-docs/main/openapi.yaml">available in the main repository</a>, which can be used to generate custom API clients.
+This definition is planned to be kept up to date for the latest core and add-on releases.
+Note that currently the definition does not declare the most appropriate types for the parameters and does not contain the responses.</p>
+
 <p>The following are some of the features provided by ZAP:</p>
 
 <ul>