diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index 72a0de0a27..6f8f5a2148 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -40666,7 +40666,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 72d6284045..7a5c026624 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -21689,7 +21689,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 8137c64197..c35818cae9 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -22159,9 +22159,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/v9/operation/operation-synonyms-put-synonym",
+      "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": {
@@ -249934,7 +249936,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": [
@@ -249986,8 +249988,27 @@
           }
         }
       ],
-      "query": [],
-      "specLocation": "synonyms/put_synonym/SynonymsPutRequest.ts#L23-L55"
+      "query": [
+        {
+          "availability": {
+            "stack": {
+              "since": "9.1.0"
+            }
+          },
+          "description": "If `true`, the request will refresh the analyzers with the new synonyms set and wait for the new synonyms to be available before returning.\nIf `false`, analyzers will not be reloaded with the new synonym set",
+          "name": "refresh",
+          "required": false,
+          "serverDefault": true,
+          "type": {
+            "kind": "instance_of",
+            "type": {
+              "name": "boolean",
+              "namespace": "_builtins"
+            }
+          }
+        }
+      ],
+      "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 3950953276..b45ae3e613 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -870,6 +870,7 @@ start-trial,https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/opera
 stop-dfanalytics,https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-ml-stop-data-frame-analytics,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-dfanalytics.html
 stop-trained-model-deployment,https://www.elastic.co/docs/api/doc/elasticsearch/v9/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/v9/operation/operation-transform-stop-transform,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-transform.html
+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
 stored-fields,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields#stored-fields,
 synonym-rule-create,https://www.elastic.co/docs/api/doc/elasticsearch/v9/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/v9/operation/operation-synonyms-delete-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-synonym-rule.html
@@ -921,4 +922,4 @@ watcher-api-update-settings,https://www.elastic.co/docs/api/doc/elasticsearch/v9
 watsonx-api-keys,https://cloud.ibm.com/iam/apikeys,
 watsonx-api-models,https://www.ibm.com/products/watsonx-ai/foundation-models,
 watsonx-api-version,https://cloud.ibm.com/apidocs/watsonx-ai#active-version-dates,
-xpack-rollup,https://www.elastic.co/docs/manage-data/lifecycle/rollup,
\ No newline at end of file
+xpack-rollup,https://www.elastic.co/docs/manage-data/lifecycle/rollup,
diff --git a/specification/synonyms/put_synonym/SynonymsPutRequest.ts b/specification/synonyms/put_synonym/SynonymsPutRequest.ts
index b6ed5ca6da..289d39e67d 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: [