diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index 81ecfe9d19..d2e3db5ed0 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -41428,7 +41428,11 @@
           "synonyms"
         ],
         "summary": "Create or update a synonym set",
-        "description": "Synonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.\n\n## Required authorization\n\n* Cluster privileges: `manage_search_synonyms`\n",
+        "description": "Synonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.\n\nFor practical examples of how to create or update a synonyms set, refer to the External documentation.\n\n## Required authorization\n\n* Cluster privileges: `manage_search_synonyms`\n",
+        "externalDocs": {
+          "url": "https://www.elastic.co/docs/solutions/search/full-text/create-update-synonyms-api-example",
+          "x-previousVersionUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html"
+        },
         "operationId": "synonyms-put-synonym",
         "parameters": [
           {
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
index 1d6fba4fc8..044e423005 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -22229,7 +22229,11 @@
           "synonyms"
         ],
         "summary": "Create or update a synonym set",
-        "description": "Synonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.\n\n## Required authorization\n\n* Cluster privileges: `manage_search_synonyms`\n",
+        "description": "Synonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.\n\nFor practical examples of how to create or update a synonyms set, refer to the External documentation.\n\n## Required authorization\n\n* Cluster privileges: `manage_search_synonyms`\n",
+        "externalDocs": {
+          "url": "https://www.elastic.co/docs/solutions/search/full-text/create-update-synonyms-api-example",
+          "x-previousVersionUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html"
+        },
         "operationId": "synonyms-put-synonym",
         "parameters": [
           {
diff --git a/output/schema/schema.json b/output/schema/schema.json
index ab2007136f..a06a849922 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -22678,9 +22678,11 @@
           "stability": "stable"
         }
       },
-      "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.",
+      "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.\n\nFor practical examples of how to create or update a synonyms set, refer to the External documentation.",
       "docId": "synonym-set-create",
       "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-put-synonym",
+      "extDocId": "synonym-api-examples",
+      "extDocUrl": "https://www.elastic.co/docs/solutions/search/full-text/create-update-synonyms-api-example",
       "extPreviousVersionDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html",
       "name": "synonyms.put_synonym",
       "privileges": {
@@ -252747,7 +252749,7 @@
           }
         ]
       },
-      "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.",
+      "description": "Create or update a synonym set.\nSynonyms sets are limited to a maximum of 10,000 synonym rules per set.\nIf you need to manage more synonym rules, you can create multiple synonym sets.\n\nWhen an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.\nThis is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.\n\nFor practical examples of how to create or update a synonyms set, refer to the External documentation.",
       "examples": {
         "SynonymsPutRequestExample1": {
           "alternatives": [
@@ -252819,7 +252821,7 @@
           }
         }
       ],
-      "specLocation": "synonyms/put_synonym/SynonymsPutRequest.ts#L23-L64"
+      "specLocation": "synonyms/put_synonym/SynonymsPutRequest.ts#L23-L67"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index c7c54e6998..daf88b2c80 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -877,6 +877,7 @@ stop-dfanalytics,https://www.elastic.co/docs/api/doc/elasticsearch/operation/ope
 stop-trained-model-deployment,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-stop-trained-model-deployment,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-trained-model-deployment.html
 stop-transform,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-transform-stop-transform,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-transform.html
 stored-fields,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields#stored-fields,
+synonym-api-examples,https://www.elastic.co/docs/solutions/search/full-text/create-update-synonyms-api-example,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html
 synonym-rule-create,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-put-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonym-rule.html
 synonym-rule-delete,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-delete-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-synonym-rule.html
 synonym-rule-get,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-get-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-synonym-rule.html
diff --git a/specification/synonyms/put_synonym/SynonymsPutRequest.ts b/specification/synonyms/put_synonym/SynonymsPutRequest.ts
index 809c5d0a11..5408b22e6b 100644
--- a/specification/synonyms/put_synonym/SynonymsPutRequest.ts
+++ b/specification/synonyms/put_synonym/SynonymsPutRequest.ts
@@ -27,11 +27,14 @@ import { SynonymRule } from '../_types/SynonymRule'
  *
  * When an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices.
  * This is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.
+ *
+ * For practical examples of how to create or update a synonyms set, refer to the External documentation.
  * @rest_spec_name synonyms.put_synonym
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @cluster_privileges manage_search_synonyms
  * @doc_id synonym-set-create
+ * @ext_doc_id synonym-api-examples
  */
 export interface Request extends RequestBase {
   urls: [