diff --git a/compiler/src/model/utils.ts b/compiler/src/model/utils.ts
index c0bf108e15..06ddabe650 100644
--- a/compiler/src/model/utils.ts
+++ b/compiler/src/model/utils.ts
@@ -668,7 +668,7 @@ export function hoistRequestAnnotations (
       const privileges = [
         'all', 'cancel_task', 'create_snapshot', 'grant_api_key', 'manage', 'manage_api_key', 'manage_ccr',
         'manage_enrich', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines',
-        'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules',
+        'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules', 'manage_search_synonyms',
         'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile',
         'manage_watcher', 'monitor', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_text_structure',
         'monitor_transform', 'monitor_watcher', 'read_ccr', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client'
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index cf7870f39b..89c6d7acd0 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -34741,7 +34741,7 @@
           {
             "in": "path",
             "name": "id",
-            "description": "\"The id of the synonyms set to be retrieved",
+            "description": "The synonyms set identifier to retrieve.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -34752,7 +34752,7 @@
           {
             "in": "query",
             "name": "from",
-            "description": "Starting offset for query rules to be retrieved",
+            "description": "The starting offset for query rules to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -34762,7 +34762,7 @@
           {
             "in": "query",
             "name": "size",
-            "description": "specifies a max number of query rules to retrieve",
+            "description": "The max number of query rules to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -34779,9 +34779,11 @@
                   "type": "object",
                   "properties": {
                     "count": {
+                      "description": "The total number of synonyms rules that the synonyms set contains.",
                       "type": "number"
                     },
                     "synonyms_set": {
+                      "description": "Synonym rule details.",
                       "type": "array",
                       "items": {
                         "$ref": "#/components/schemas/synonyms._types:SynonymRuleRead"
@@ -34804,13 +34806,13 @@
           "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.",
+        "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.",
         "operationId": "synonyms-put-synonym",
         "parameters": [
           {
             "in": "path",
             "name": "id",
-            "description": "The id of the synonyms set to be created or updated",
+            "description": "The ID of the synonyms set to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -34826,7 +34828,7 @@
                 "type": "object",
                 "properties": {
                   "synonyms_set": {
-                    "description": "The synonym set information to update",
+                    "description": "The synonym rules definitions for the synonyms set.",
                     "oneOf": [
                       {
                         "$ref": "#/components/schemas/synonyms._types:SynonymRule"
@@ -34879,12 +34881,13 @@
           "synonyms"
         ],
         "summary": "Delete a synonym set",
+        "description": "You can only delete a synonyms set that is not in use by any index analyzer.\n\nSynonyms sets can be used in synonym graph token filters and synonym token filters.\nThese synonym filters can be used as part of search analyzers.\n\nAnalyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open).\nEven if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.\n\nIf any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes red or yellow as index shards are not available.\nTo prevent that, synonyms sets that are used in analyzers can't be deleted.\nA delete request in this case will return a 400 response code.\n\nTo remove a synonyms set, you must first remove all indices that contain analyzers using it.\nYou can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the reindex API in order to copy over the index data.\nOnce finished, you can delete the index.\nWhen the synonyms set is not used in analyzers, you will be able to delete it.",
         "operationId": "synonyms-delete-synonym",
         "parameters": [
           {
             "in": "path",
             "name": "id",
-            "description": "The id of the synonyms set to be deleted",
+            "description": "The synonyms set identifier to delete.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -34920,7 +34923,7 @@
           {
             "in": "path",
             "name": "set_id",
-            "description": "The id of the synonym set to retrieve the synonym rule from",
+            "description": "The ID of the synonym set to retrieve the synonym rule from.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -34931,7 +34934,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The id of the synonym rule to retrieve",
+            "description": "The ID of the synonym rule to retrieve.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -34959,13 +34962,13 @@
           "synonyms"
         ],
         "summary": "Create or update a synonym rule",
-        "description": "Create or update a synonym rule in a synonym set.",
+        "description": "Create or update a synonym rule in a synonym set.\n\nIf any of the synonym rules included is invalid, the API returns an error.\n\nWhen you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.",
         "operationId": "synonyms-put-synonym-rule",
         "parameters": [
           {
             "in": "path",
             "name": "set_id",
-            "description": "The id of the synonym set to be updated with the synonym rule",
+            "description": "The ID of the synonym set.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -34976,7 +34979,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The id of the synonym rule to be updated or created",
+            "description": "The ID of the synonym rule to be updated or created.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -35028,7 +35031,7 @@
           {
             "in": "path",
             "name": "set_id",
-            "description": "The id of the synonym set to be updated",
+            "description": "The ID of the synonym set to update.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -35039,7 +35042,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The id of the synonym rule to be deleted",
+            "description": "The ID of the synonym rule to delete.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -35075,7 +35078,7 @@
           {
             "in": "query",
             "name": "from",
-            "description": "Starting offset",
+            "description": "The starting offset for synonyms sets to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -35085,7 +35088,7 @@
           {
             "in": "query",
             "name": "size",
-            "description": "specifies a max number of results to get",
+            "description": "The maximum number of synonyms sets to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -35102,9 +35105,11 @@
                   "type": "object",
                   "properties": {
                     "count": {
+                      "description": "The total number of synonyms sets defined.",
                       "type": "number"
                     },
                     "results": {
+                      "description": "The identifier and total number of defined synonym rules for each synonyms set.",
                       "type": "array",
                       "items": {
                         "$ref": "#/components/schemas/synonyms.get_synonyms_sets:SynonymsSetItem"
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
index 71f442af3e..76194a6b3d 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -18023,7 +18023,7 @@
           {
             "in": "path",
             "name": "id",
-            "description": "\"The id of the synonyms set to be retrieved",
+            "description": "The synonyms set identifier to retrieve.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18034,7 +18034,7 @@
           {
             "in": "query",
             "name": "from",
-            "description": "Starting offset for query rules to be retrieved",
+            "description": "The starting offset for query rules to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -18044,7 +18044,7 @@
           {
             "in": "query",
             "name": "size",
-            "description": "specifies a max number of query rules to retrieve",
+            "description": "The max number of query rules to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -18061,9 +18061,11 @@
                   "type": "object",
                   "properties": {
                     "count": {
+                      "description": "The total number of synonyms rules that the synonyms set contains.",
                       "type": "number"
                     },
                     "synonyms_set": {
+                      "description": "Synonym rule details.",
                       "type": "array",
                       "items": {
                         "$ref": "#/components/schemas/synonyms._types:SynonymRuleRead"
@@ -18086,13 +18088,13 @@
           "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.",
+        "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.",
         "operationId": "synonyms-put-synonym",
         "parameters": [
           {
             "in": "path",
             "name": "id",
-            "description": "The id of the synonyms set to be created or updated",
+            "description": "The ID of the synonyms set to be created or updated.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18108,7 +18110,7 @@
                 "type": "object",
                 "properties": {
                   "synonyms_set": {
-                    "description": "The synonym set information to update",
+                    "description": "The synonym rules definitions for the synonyms set.",
                     "oneOf": [
                       {
                         "$ref": "#/components/schemas/synonyms._types:SynonymRule"
@@ -18161,12 +18163,13 @@
           "synonyms"
         ],
         "summary": "Delete a synonym set",
+        "description": "You can only delete a synonyms set that is not in use by any index analyzer.\n\nSynonyms sets can be used in synonym graph token filters and synonym token filters.\nThese synonym filters can be used as part of search analyzers.\n\nAnalyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open).\nEven if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.\n\nIf any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes red or yellow as index shards are not available.\nTo prevent that, synonyms sets that are used in analyzers can't be deleted.\nA delete request in this case will return a 400 response code.\n\nTo remove a synonyms set, you must first remove all indices that contain analyzers using it.\nYou can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the reindex API in order to copy over the index data.\nOnce finished, you can delete the index.\nWhen the synonyms set is not used in analyzers, you will be able to delete it.",
         "operationId": "synonyms-delete-synonym",
         "parameters": [
           {
             "in": "path",
             "name": "id",
-            "description": "The id of the synonyms set to be deleted",
+            "description": "The synonyms set identifier to delete.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18202,7 +18205,7 @@
           {
             "in": "path",
             "name": "set_id",
-            "description": "The id of the synonym set to retrieve the synonym rule from",
+            "description": "The ID of the synonym set to retrieve the synonym rule from.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18213,7 +18216,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The id of the synonym rule to retrieve",
+            "description": "The ID of the synonym rule to retrieve.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18241,13 +18244,13 @@
           "synonyms"
         ],
         "summary": "Create or update a synonym rule",
-        "description": "Create or update a synonym rule in a synonym set.",
+        "description": "Create or update a synonym rule in a synonym set.\n\nIf any of the synonym rules included is invalid, the API returns an error.\n\nWhen you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.",
         "operationId": "synonyms-put-synonym-rule",
         "parameters": [
           {
             "in": "path",
             "name": "set_id",
-            "description": "The id of the synonym set to be updated with the synonym rule",
+            "description": "The ID of the synonym set.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18258,7 +18261,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The id of the synonym rule to be updated or created",
+            "description": "The ID of the synonym rule to be updated or created.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18310,7 +18313,7 @@
           {
             "in": "path",
             "name": "set_id",
-            "description": "The id of the synonym set to be updated",
+            "description": "The ID of the synonym set to update.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18321,7 +18324,7 @@
           {
             "in": "path",
             "name": "rule_id",
-            "description": "The id of the synonym rule to be deleted",
+            "description": "The ID of the synonym rule to delete.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -18357,7 +18360,7 @@
           {
             "in": "query",
             "name": "from",
-            "description": "Starting offset",
+            "description": "The starting offset for synonyms sets to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -18367,7 +18370,7 @@
           {
             "in": "query",
             "name": "size",
-            "description": "specifies a max number of results to get",
+            "description": "The maximum number of synonyms sets to retrieve.",
             "deprecated": false,
             "schema": {
               "type": "number"
@@ -18384,9 +18387,11 @@
                   "type": "object",
                   "properties": {
                     "count": {
+                      "description": "The total number of synonyms sets defined.",
                       "type": "number"
                     },
                     "results": {
+                      "description": "The identifier and total number of defined synonym rules for each synonyms set.",
                       "type": "array",
                       "items": {
                         "$ref": "#/components/schemas/synonyms.get_synonyms_sets:SynonymsSetItem"
diff --git a/output/schema/schema.json b/output/schema/schema.json
index a353999155..150d3ae473 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -8320,7 +8320,7 @@
       },
       "description": "Simulate an index.\nGet the index configuration that would be applied to the specified index from an existing index template.",
       "docId": "indices-simulate",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{master}/indices-simulate-index.html",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-simulate-index.html",
       "name": "indices.simulate_index_template",
       "privileges": {
         "cluster": [
@@ -19637,9 +19637,15 @@
           "stability": "stable"
         }
       },
-      "description": "Delete a synonym set.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-synonyms-set.html",
+      "description": "Delete a synonym set.\n\nYou can only delete a synonyms set that is not in use by any index analyzer.\n\nSynonyms sets can be used in synonym graph token filters and synonym token filters.\nThese synonym filters can be used as part of search analyzers.\n\nAnalyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open).\nEven if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.\n\nIf any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes red or yellow as index shards are not available.\nTo prevent that, synonyms sets that are used in analyzers can't be deleted.\nA delete request in this case will return a 400 response code.\n\nTo remove a synonyms set, you must first remove all indices that contain analyzers using it.\nYou can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the reindex API in order to copy over the index data.\nOnce finished, you can delete the index.\nWhen the synonyms set is not used in analyzers, you will be able to delete it.",
+      "docId": "synonym-set-delete",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-synonyms-set.html",
       "name": "synonyms.delete_synonym",
+      "privileges": {
+        "cluster": [
+          "manage_search_synonyms"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "synonyms.delete_synonym"
@@ -19673,8 +19679,14 @@
         }
       },
       "description": "Delete a synonym rule.\nDelete a synonym rule from a synonym set.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-synonym-rule.html",
+      "docId": "synonym-rule-delete",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-synonym-rule.html",
       "name": "synonyms.delete_synonym_rule",
+      "privileges": {
+        "cluster": [
+          "manage_search_synonyms"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "synonyms.delete_synonym_rule"
@@ -19711,8 +19723,14 @@
         }
       },
       "description": "Get a synonym set.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-synonyms-set.html",
+      "docId": "synonym-set-get",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonyms-set.html",
       "name": "synonyms.get_synonym",
+      "privileges": {
+        "cluster": [
+          "manage_search_synonyms"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "synonyms.get_synonym"
@@ -19746,8 +19764,14 @@
         }
       },
       "description": "Get a synonym rule.\nGet a synonym rule from a synonym set.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-synonym-rule.html",
+      "docId": "synonym-rule-get",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonym-rule.html",
       "name": "synonyms.get_synonym_rule",
+      "privileges": {
+        "cluster": [
+          "manage_search_synonyms"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "synonyms.get_synonym_rule"
@@ -19784,8 +19808,14 @@
         }
       },
       "description": "Get all synonym sets.\nGet a summary of all defined synonym sets.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/list-synonyms-sets.html",
+      "docId": "synonym-set-list",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonyms-set.html",
       "name": "synonyms.get_synonyms_sets",
+      "privileges": {
+        "cluster": [
+          "manage_search_synonyms"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "synonyms.get_synonyms_sets"
@@ -19818,9 +19848,15 @@
           "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.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/put-synonyms-set.html",
+      "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.",
+      "docId": "synonym-set-create",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-synonyms-set.html",
       "name": "synonyms.put_synonym",
+      "privileges": {
+        "cluster": [
+          "manage_search_synonyms"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "synonyms.put_synonym"
@@ -19856,9 +19892,15 @@
           "stability": "stable"
         }
       },
-      "description": "Create or update a synonym rule.\nCreate or update a synonym rule in a synonym set.",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/put-synonym-rule.html",
+      "description": "Create or update a synonym rule.\nCreate or update a synonym rule in a synonym set.\n\nIf any of the synonym rules included is invalid, the API returns an error.\n\nWhen you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.",
+      "docId": "synonym-rule-create",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-synonym-rule.html",
       "name": "synonyms.put_synonym_rule",
+      "privileges": {
+        "cluster": [
+          "manage_search_synonyms"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "synonyms.put_synonym_rule"
@@ -210884,7 +210926,7 @@
       },
       "properties": [
         {
-          "description": "Synonym Rule identifier",
+          "description": "The identifier for the synonym rule.\nIf you do not specify a synonym rule ID when you create a rule, an identifier is created automatically by Elasticsearch.",
           "name": "id",
           "required": false,
           "type": {
@@ -210896,7 +210938,9 @@
           }
         },
         {
-          "description": "Synonyms, in Solr format, that conform the synonym rule. See https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-graph-tokenfilter.html#_solr_synonyms_2",
+          "description": "The synonyms that conform the synonym rule in Solr format.",
+          "extDocId": "synonym-set-define",
+          "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-synonym-graph-tokenfilter.html#analysis-synonym-graph-define-synonyms",
           "name": "synonyms",
           "required": true,
           "type": {
@@ -210908,7 +210952,7 @@
           }
         }
       ],
-      "specLocation": "synonyms/_types/SynonymRule.ts#L26-L35"
+      "specLocation": "synonyms/_types/SynonymRule.ts#L26-L37"
     },
     {
       "kind": "interface",
@@ -210951,6 +210995,8 @@
         },
         {
           "description": "Synonyms, in Solr format, that conform the synonym rule. See https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-graph-tokenfilter.html#_solr_synonyms_2",
+          "extDocId": "synonym-set-define",
+          "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-synonym-graph-tokenfilter.html#analysis-synonym-graph-define-synonyms",
           "name": "synonyms",
           "required": true,
           "type": {
@@ -210962,7 +211008,7 @@
           }
         }
       ],
-      "specLocation": "synonyms/_types/SynonymRule.ts#L38-L47"
+      "specLocation": "synonyms/_types/SynonymRule.ts#L40-L49"
     },
     {
       "kind": "type_alias",
@@ -210987,7 +211033,7 @@
       },
       "properties": [
         {
-          "description": "Update operation result",
+          "description": "The update operation result.",
           "name": "result",
           "required": true,
           "type": {
@@ -210999,7 +211045,7 @@
           }
         },
         {
-          "description": "Updating synonyms in a synonym set reloads the associated analyzers.\nThis is the analyzers reloading result",
+          "description": "Updating synonyms in a synonym set reloads the associated analyzers.\nThis information is the analyzers reloading result.",
           "name": "reload_analyzers_details",
           "required": true,
           "type": {
@@ -211021,7 +211067,7 @@
       "body": {
         "kind": "no_body"
       },
-      "description": "Delete a synonym set.",
+      "description": "Delete a synonym set.\n\nYou can only delete a synonyms set that is not in use by any index analyzer.\n\nSynonyms sets can be used in synonym graph token filters and synonym token filters.\nThese synonym filters can be used as part of search analyzers.\n\nAnalyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open).\nEven if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.\n\nIf any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes red or yellow as index shards are not available.\nTo prevent that, synonyms sets that are used in analyzers can't be deleted.\nA delete request in this case will return a 400 response code.\n\nTo remove a synonyms set, you must first remove all indices that contain analyzers using it.\nYou can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the reindex API in order to copy over the index data.\nOnce finished, you can delete the index.\nWhen the synonyms set is not used in analyzers, you will be able to delete it.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -211034,7 +211080,7 @@
       },
       "path": [
         {
-          "description": "The id of the synonyms set to be deleted",
+          "description": "The synonyms set identifier to delete.",
           "name": "id",
           "required": true,
           "type": {
@@ -211047,7 +211093,7 @@
         }
       ],
       "query": [],
-      "specLocation": "synonyms/delete_synonym/SynonymsDeleteRequest.ts#L22-L35"
+      "specLocation": "synonyms/delete_synonym/SynonymsDeleteRequest.ts#L22-L54"
     },
     {
       "kind": "response",
@@ -211088,7 +211134,7 @@
       },
       "path": [
         {
-          "description": "The id of the synonym set to be updated",
+          "description": "The ID of the synonym set to update.",
           "name": "set_id",
           "required": true,
           "type": {
@@ -211100,7 +211146,7 @@
           }
         },
         {
-          "description": "The id of the synonym rule to be deleted",
+          "description": "The ID of the synonym rule to delete.",
           "name": "rule_id",
           "required": true,
           "type": {
@@ -211113,7 +211159,7 @@
         }
       ],
       "query": [],
-      "specLocation": "synonyms/delete_synonym_rule/SynonymRuleDeleteRequest.ts#L22-L41"
+      "specLocation": "synonyms/delete_synonym_rule/SynonymRuleDeleteRequest.ts#L22-L42"
     },
     {
       "kind": "response",
@@ -211154,7 +211200,7 @@
       },
       "path": [
         {
-          "description": "\"The id of the synonyms set to be retrieved",
+          "description": "The synonyms set identifier to retrieve.",
           "name": "id",
           "required": true,
           "type": {
@@ -211168,7 +211214,7 @@
       ],
       "query": [
         {
-          "description": "Starting offset for query rules to be retrieved",
+          "description": "The starting offset for query rules to retrieve.",
           "name": "from",
           "required": false,
           "serverDefault": 0,
@@ -211181,7 +211227,7 @@
           }
         },
         {
-          "description": "specifies a max number of query rules to retrieve",
+          "description": "The max number of query rules to retrieve.",
           "name": "size",
           "required": false,
           "serverDefault": 10,
@@ -211194,7 +211240,7 @@
           }
         }
       ],
-      "specLocation": "synonyms/get_synonym/SynonymsGetRequest.ts#L23-L48"
+      "specLocation": "synonyms/get_synonym/SynonymsGetRequest.ts#L23-L50"
     },
     {
       "kind": "response",
@@ -211202,6 +211248,7 @@
         "kind": "properties",
         "properties": [
           {
+            "description": "The total number of synonyms rules that the synonyms set contains.",
             "name": "count",
             "required": true,
             "type": {
@@ -211213,6 +211260,7 @@
             }
           },
           {
+            "description": "Synonym rule details.",
             "name": "synonyms_set",
             "required": true,
             "type": {
@@ -211232,7 +211280,7 @@
         "name": "Response",
         "namespace": "synonyms.get_synonym"
       },
-      "specLocation": "synonyms/get_synonym/SynonymsGetResponse.ts#L23-L28"
+      "specLocation": "synonyms/get_synonym/SynonymsGetResponse.ts#L23-L34"
     },
     {
       "kind": "request",
@@ -211255,7 +211303,7 @@
       },
       "path": [
         {
-          "description": "The id of the synonym set to retrieve the synonym rule from",
+          "description": "The ID of the synonym set to retrieve the synonym rule from.",
           "name": "set_id",
           "required": true,
           "type": {
@@ -211267,7 +211315,7 @@
           }
         },
         {
-          "description": "The id of the synonym rule to retrieve",
+          "description": "The ID of the synonym rule to retrieve.",
           "name": "rule_id",
           "required": true,
           "type": {
@@ -211280,7 +211328,7 @@
         }
       ],
       "query": [],
-      "specLocation": "synonyms/get_synonym_rule/SynonymRuleGetRequest.ts#L22-L41"
+      "specLocation": "synonyms/get_synonym_rule/SynonymRuleGetRequest.ts#L22-L42"
     },
     {
       "kind": "response",
@@ -211322,7 +211370,7 @@
       "path": [],
       "query": [
         {
-          "description": "Starting offset",
+          "description": "The starting offset for synonyms sets to retrieve.",
           "name": "from",
           "required": false,
           "serverDefault": 0,
@@ -211335,7 +211383,7 @@
           }
         },
         {
-          "description": "specifies a max number of results to get",
+          "description": "The maximum number of synonyms sets to retrieve.",
           "name": "size",
           "required": false,
           "serverDefault": 10,
@@ -211348,7 +211396,7 @@
           }
         }
       ],
-      "specLocation": "synonyms/get_synonyms_sets/SynonymsSetsGetRequest.ts#L22-L42"
+      "specLocation": "synonyms/get_synonyms_sets/SynonymsSetsGetRequest.ts#L22-L44"
     },
     {
       "kind": "response",
@@ -211356,6 +211404,7 @@
         "kind": "properties",
         "properties": [
           {
+            "description": "The total number of synonyms sets defined.",
             "name": "count",
             "required": true,
             "type": {
@@ -211367,6 +211416,7 @@
             }
           },
           {
+            "description": "The identifier and total number of defined synonym rules for each synonyms set.",
             "name": "results",
             "required": true,
             "type": {
@@ -211386,7 +211436,7 @@
         "name": "Response",
         "namespace": "synonyms.get_synonyms_sets"
       },
-      "specLocation": "synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts#L23-L28"
+      "specLocation": "synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts#L23-L34"
     },
     {
       "kind": "interface",
@@ -211420,7 +211470,7 @@
           }
         }
       ],
-      "specLocation": "synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts#L30-L39"
+      "specLocation": "synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts#L36-L45"
     },
     {
       "kind": "request",
@@ -211431,7 +211481,7 @@
         "kind": "properties",
         "properties": [
           {
-            "description": "The synonym set information to update",
+            "description": "The synonym rules definitions for the synonyms set.",
             "name": "synonyms_set",
             "required": true,
             "type": {
@@ -211459,7 +211509,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.",
+      "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.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -211472,7 +211522,7 @@
       },
       "path": [
         {
-          "description": "The id of the synonyms set to be created or updated",
+          "description": "The ID of the synonyms set to be created or updated.",
           "name": "id",
           "required": true,
           "type": {
@@ -211485,7 +211535,7 @@
         }
       ],
       "query": [],
-      "specLocation": "synonyms/put_synonym/SynonymsPutRequest.ts#L23-L44"
+      "specLocation": "synonyms/put_synonym/SynonymsPutRequest.ts#L23-L49"
     },
     {
       "kind": "response",
@@ -211531,6 +211581,9 @@
         "kind": "properties",
         "properties": [
           {
+            "description": "The synonym rule information definition, which must be in Solr format.",
+            "extDocId": "synonym-set-define",
+            "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-synonym-graph-tokenfilter.html#analysis-synonym-graph-define-synonyms",
             "name": "synonyms",
             "required": true,
             "type": {
@@ -211543,7 +211596,7 @@
           }
         ]
       },
-      "description": "Create or update a synonym rule.\nCreate or update a synonym rule in a synonym set.",
+      "description": "Create or update a synonym rule.\nCreate or update a synonym rule in a synonym set.\n\nIf any of the synonym rules included is invalid, the API returns an error.\n\nWhen you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.",
       "inherits": {
         "type": {
           "name": "RequestBase",
@@ -211556,7 +211609,7 @@
       },
       "path": [
         {
-          "description": "The id of the synonym set to be updated with the synonym rule",
+          "description": "The ID of the synonym set.",
           "name": "set_id",
           "required": true,
           "type": {
@@ -211568,7 +211621,7 @@
           }
         },
         {
-          "description": "The id of the synonym rule to be updated or created",
+          "description": "The ID of the synonym rule to be updated or created.",
           "name": "rule_id",
           "required": true,
           "type": {
@@ -211581,7 +211634,7 @@
         }
       ],
       "query": [],
-      "specLocation": "synonyms/put_synonym_rule/SynonymRulePutRequest.ts#L23-L48"
+      "specLocation": "synonyms/put_synonym_rule/SynonymRulePutRequest.ts#L23-L54"
     },
     {
       "kind": "response",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index 67196e7686..40a423f143 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -268,7 +268,7 @@ indices-rollover-index,https://www.elastic.co/guide/en/elasticsearch/reference/{
 indices-segments,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-segments.html
 indices-shards-stores,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-shards-stores.html
 indices-shrink-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-shrink-index.html
-indices-simulate,https://www.elastic.co/guide/en/elasticsearch/reference/{master}/indices-simulate-index.html
+indices-simulate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-simulate-index.html
 indices-simulate-template,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-simulate-template.html
 indices-split-index,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-split-index.html
 indices-stats,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-stats.html
@@ -705,6 +705,14 @@ start-trial,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sta
 stop-dfanalytics,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-dfanalytics.html
 stop-trained-model-deployment,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-trained-model-deployment.html
 stop-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/stop-transform.html
+synonym-rule-create,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-synonym-rule.html
+synonym-rule-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-synonym-rule.html
+synonym-rule-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonym-rule.html
+synonym-set-create,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-synonyms-set.html
+synonym-set-define,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-synonym-graph-tokenfilter.html#analysis-synonym-graph-define-synonyms
+synonym-set-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-synonyms-set.html
+synonym-set-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonyms-set.html
+synonym-set-list,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-synonyms-set.html
 supported-flags,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-simple-query-string-query.html#supported-flags
 tasks,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/tasks.html
 templating-role-query,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html#templating-role-query
diff --git a/specification/synonyms/_types/SynonymRule.ts b/specification/synonyms/_types/SynonymRule.ts
index 9fa469233b..99a1c31dcf 100644
--- a/specification/synonyms/_types/SynonymRule.ts
+++ b/specification/synonyms/_types/SynonymRule.ts
@@ -25,11 +25,13 @@ export type SynonymString = string
 // Synonym Rule with optional ID, used for PUT method
 export class SynonymRule {
   /**
-   * Synonym Rule identifier
+   * The identifier for the synonym rule.
+   * If you do not specify a synonym rule ID when you create a rule, an identifier is created automatically by Elasticsearch.
    */
   id?: Id
   /**
-   * Synonyms, in Solr format, that conform the synonym rule. See https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-graph-tokenfilter.html#_solr_synonyms_2
+   * The synonyms that conform the synonym rule in Solr format.
+   * @ext_doc_id synonym-set-define
    */
   synonyms: SynonymString
 }
diff --git a/specification/synonyms/_types/SynonymsUpdateResult.ts b/specification/synonyms/_types/SynonymsUpdateResult.ts
index ef65372897..85ac5232fb 100644
--- a/specification/synonyms/_types/SynonymsUpdateResult.ts
+++ b/specification/synonyms/_types/SynonymsUpdateResult.ts
@@ -22,13 +22,13 @@ import { Result } from '@_types/Result'
 
 export class SynonymsUpdateResult {
   /**
-   * Update operation result
+   * The update operation result.
    */
   result: Result
 
   /**
    * Updating synonyms in a synonym set reloads the associated analyzers.
-   * This is the analyzers reloading result
+   * This information is the analyzers reloading result.
    */
   reload_analyzers_details: ReloadResult
 }
diff --git a/specification/synonyms/delete_synonym/SynonymsDeleteRequest.ts b/specification/synonyms/delete_synonym/SynonymsDeleteRequest.ts
index ad6e0b7595..fe75d664c8 100644
--- a/specification/synonyms/delete_synonym/SynonymsDeleteRequest.ts
+++ b/specification/synonyms/delete_synonym/SynonymsDeleteRequest.ts
@@ -21,14 +21,33 @@ import { Id } from '@_types/common'
 
 /**
  * Delete a synonym set.
+ *
+ * You can only delete a synonyms set that is not in use by any index analyzer.
+ *
+ * Synonyms sets can be used in synonym graph token filters and synonym token filters.
+ * These synonym filters can be used as part of search analyzers.
+ *
+ * Analyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open).
+ * Even if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.
+ *
+ * If any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes red or yellow as index shards are not available.
+ * To prevent that, synonyms sets that are used in analyzers can't be deleted.
+ * A delete request in this case will return a 400 response code.
+ *
+ * To remove a synonyms set, you must first remove all indices that contain analyzers using it.
+ * You can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the reindex API in order to copy over the index data.
+ * Once finished, you can delete the index.
+ * When the synonyms set is not used in analyzers, you will be able to delete it.
  * @rest_spec_name synonyms.delete_synonym
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_synonyms
+ * @doc_id synonym-set-delete
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * The id of the synonyms set to be deleted
+     * The synonyms set identifier to delete.
      */
     id: Id
   }
diff --git a/specification/synonyms/delete_synonym_rule/SynonymRuleDeleteRequest.ts b/specification/synonyms/delete_synonym_rule/SynonymRuleDeleteRequest.ts
index 4c095ad1f0..d9f4f7b75b 100644
--- a/specification/synonyms/delete_synonym_rule/SynonymRuleDeleteRequest.ts
+++ b/specification/synonyms/delete_synonym_rule/SynonymRuleDeleteRequest.ts
@@ -25,16 +25,17 @@ import { Id } from '@_types/common'
  * @rest_spec_name synonyms.delete_synonym_rule
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_synonyms
+ * @doc_id synonym-rule-delete
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * The id of the synonym set to be updated
+     * The ID of the synonym set to update.
      */
     set_id: Id
-
     /**
-     * The id of the synonym rule to be deleted
+     * The ID of the synonym rule to delete.
      */
     rule_id: Id
   }
diff --git a/specification/synonyms/delete_synonym_rule/examples/response/SynonymRuleDeleteResponseExample1.yaml b/specification/synonyms/delete_synonym_rule/examples/response/SynonymRuleDeleteResponseExample1.yaml
new file mode 100644
index 0000000000..9a0b3b7ec4
--- /dev/null
+++ b/specification/synonyms/delete_synonym_rule/examples/response/SynonymRuleDeleteResponseExample1.yaml
@@ -0,0 +1,28 @@
+# summary:
+description: >
+  A successful response from `DELETE _synonyms/my-synonyms-set/test-1`.
+  All analyzers using this synonyms set will be reloaded automatically to reflect the rule being deleted.
+# type: response
+# response_code: ''
+value: |-
+  {
+    "result": "deleted",
+    "reload_analyzers_details": {
+      "_shards": {
+        "total": 2,
+        "successful": 1,
+        "failed": 0
+      },
+      "reload_details": [
+        {
+          "index": "test-index",
+          "reloaded_analyzers": [
+            "my_search_analyzer"
+          ],
+          "reloaded_node_ids": [
+            "1wYFZzq8Sxeu_Jvt9mlbkg"
+          ]
+        }
+      ]
+    }
+  }
diff --git a/specification/synonyms/get_synonym/SynonymsGetRequest.ts b/specification/synonyms/get_synonym/SynonymsGetRequest.ts
index 277ca732b9..bfcebef584 100644
--- a/specification/synonyms/get_synonym/SynonymsGetRequest.ts
+++ b/specification/synonyms/get_synonym/SynonymsGetRequest.ts
@@ -25,22 +25,24 @@ import { integer } from '@_types/Numeric'
  * @rest_spec_name synonyms.get_synonym
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_synonyms
+ * @doc_id synonym-set-get
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * "The id of the synonyms set to be retrieved
+     * The synonyms set identifier to retrieve.
      */
     id: Id
   }
   query_parameters: {
     /**
-     * Starting offset for query rules to be retrieved
+     * The starting offset for query rules to retrieve.
      * @server_default 0
      */
     from?: integer
     /**
-     * specifies a max number of query rules to retrieve
+     * The max number of query rules to retrieve.
      * @server_default 10
      */
     size?: integer
diff --git a/specification/synonyms/get_synonym/SynonymsGetResponse.ts b/specification/synonyms/get_synonym/SynonymsGetResponse.ts
index d160bef8d3..56be74d698 100644
--- a/specification/synonyms/get_synonym/SynonymsGetResponse.ts
+++ b/specification/synonyms/get_synonym/SynonymsGetResponse.ts
@@ -22,7 +22,13 @@ import { SynonymRuleRead } from '../_types/SynonymRule'
 
 export class Response {
   body: {
+    /**
+     * The total number of synonyms rules that the synonyms set contains.
+     */
     count: integer
+    /**
+     * Synonym rule details.
+     */
     synonyms_set: SynonymRuleRead[]
   }
 }
diff --git a/specification/synonyms/get_synonym/examples/response/SynonymsGetResponseExample1.yaml b/specification/synonyms/get_synonym/examples/response/SynonymsGetResponseExample1.yaml
new file mode 100644
index 0000000000..ba8b37b77b
--- /dev/null
+++ b/specification/synonyms/get_synonym/examples/response/SynonymsGetResponseExample1.yaml
@@ -0,0 +1,9 @@
+# summary:
+description: A successful response from `GET _synonyms/my-synonyms-set`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"count\": 3,\n  \"synonyms_set\": [\n    {\n      \"id\": \"test-1\"\
+  ,\n      \"synonyms\": \"hello, hi\"\n    },\n    {\n      \"id\": \"test-2\",\n\
+  \      \"synonyms\": \"bye, goodbye\"\n    },\n    {\n      \"id\": \"test-3\",\n\
+  \      \"synonyms\": \"test => check\"\n    }\n  ]\n}"
diff --git a/specification/synonyms/get_synonym_rule/SynonymRuleGetRequest.ts b/specification/synonyms/get_synonym_rule/SynonymRuleGetRequest.ts
index aaabd51d60..1b3ed9a30d 100644
--- a/specification/synonyms/get_synonym_rule/SynonymRuleGetRequest.ts
+++ b/specification/synonyms/get_synonym_rule/SynonymRuleGetRequest.ts
@@ -25,16 +25,17 @@ import { Id } from '@_types/common'
  * @rest_spec_name synonyms.get_synonym_rule
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_synonyms
+ * @doc_id synonym-rule-get
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * The id of the synonym set to retrieve the synonym rule from
+     * The ID of the synonym set to retrieve the synonym rule from.
      */
     set_id: Id
-
     /**
-     * The id of the synonym rule to retrieve
+     * The ID of the synonym rule to retrieve.
      */
     rule_id: Id
   }
diff --git a/specification/synonyms/get_synonym_rule/examples/response/SynonymRuleGetResponseExample1.yaml b/specification/synonyms/get_synonym_rule/examples/response/SynonymRuleGetResponseExample1.yaml
new file mode 100644
index 0000000000..af8b93bec6
--- /dev/null
+++ b/specification/synonyms/get_synonym_rule/examples/response/SynonymRuleGetResponseExample1.yaml
@@ -0,0 +1,5 @@
+# summary:
+description: A successful response from `GET _synonyms/my-synonyms-set/test-1`.
+# type: response
+# response_code: ''
+value: "{\n  \"id\": \"test-1\",\n  \"synonyms\": \"hello, hi\"\n}"
diff --git a/specification/synonyms/get_synonyms_sets/SynonymsSetsGetRequest.ts b/specification/synonyms/get_synonyms_sets/SynonymsSetsGetRequest.ts
index 68dccb4ff5..6f78663552 100644
--- a/specification/synonyms/get_synonyms_sets/SynonymsSetsGetRequest.ts
+++ b/specification/synonyms/get_synonyms_sets/SynonymsSetsGetRequest.ts
@@ -25,16 +25,18 @@ import { integer } from '@_types/Numeric'
  * @rest_spec_name synonyms.get_synonyms_sets
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_synonyms
+ * @doc_id synonym-set-list
  */
 export interface Request extends RequestBase {
   query_parameters: {
     /**
-     * Starting offset
+     * The starting offset for synonyms sets to retrieve.
      * @server_default 0
      */
     from?: integer
     /**
-     * specifies a max number of results to get
+     * The maximum number of synonyms sets to retrieve.
      * @server_default 10
      */
     size?: integer
diff --git a/specification/synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts b/specification/synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts
index 13fc27fa8a..06eefb9313 100644
--- a/specification/synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts
+++ b/specification/synonyms/get_synonyms_sets/SynonymsSetsGetResponse.ts
@@ -22,7 +22,13 @@ import { integer } from '@_types/Numeric'
 
 export class Response {
   body: {
+    /**
+     * The total number of synonyms sets defined.
+     */
     count: integer
+    /**
+     * The identifier and total number of defined synonym rules for each synonyms set.
+     */
     results: SynonymsSetItem[]
   }
 }
diff --git a/specification/synonyms/get_synonyms_sets/examples/response/SynonymsSetsGetResponseExample1.yaml b/specification/synonyms/get_synonyms_sets/examples/response/SynonymsSetsGetResponseExample1.yaml
new file mode 100644
index 0000000000..edb95e9433
--- /dev/null
+++ b/specification/synonyms/get_synonyms_sets/examples/response/SynonymsSetsGetResponseExample1.yaml
@@ -0,0 +1,9 @@
+# summary:
+description: A successful response from `GET _synonyms`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"count\": 3,\n  \"results\": [\n    {\n      \"synonyms_set\": \"ecommerce-synonyms\"\
+  ,\n      \"count\": 2\n    },\n    {\n      \"synonyms_set\": \"my-synonyms-set\"\
+  ,\n      \"count\": 3\n    },\n    {\n      \"synonyms_set\": \"new-ecommerce-synonyms\"\
+  ,\n      \"count\": 1\n    }\n  ]\n}"
diff --git a/specification/synonyms/put_synonym/SynonymsPutRequest.ts b/specification/synonyms/put_synonym/SynonymsPutRequest.ts
index 73c8b2eaea..3ec7de804a 100644
--- a/specification/synonyms/put_synonym/SynonymsPutRequest.ts
+++ b/specification/synonyms/put_synonym/SynonymsPutRequest.ts
@@ -24,20 +24,25 @@ import { SynonymRule } from '../_types/SynonymRule'
  * Create or update a synonym set.
  * Synonyms sets are limited to a maximum of 10,000 synonym rules per set.
  * If you need to manage more synonym rules, you can create multiple synonym sets.
+ *
+ * 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.
  * @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
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * The id of the synonyms set to be created or updated
+     * The ID of the synonyms set to be created or updated.
      */
     id: Id
   }
   body: {
     /**
-     * The synonym set information to update
+     * The synonym rules definitions for the synonyms set.
      */
     synonyms_set: SynonymRule | SynonymRule[]
   }
diff --git a/specification/synonyms/put_synonym/examples/400_response/SynonymsPutRequestExample1.yaml b/specification/synonyms/put_synonym/examples/400_response/SynonymsPutRequestExample1.yaml
new file mode 100644
index 0000000000..49f4db3f80
--- /dev/null
+++ b/specification/synonyms/put_synonym/examples/400_response/SynonymsPutRequestExample1.yaml
@@ -0,0 +1,11 @@
+# summary:
+# method_request: PUT _synonyms/my-synonyms-set
+description: >
+  Run `PUT _synonyms/my-synonyms-set` to create a new synonyms set.
+  If any of the synonym rules included is not valid, the API will return an error.
+# type: request
+value:
+  "{\n  \"synonyms_set\": [\n    {\n      \"id\": \"test-1\",\n      \"synonyms\"\
+  : \"hello, hi\"\n    },\n    {\n      \"synonyms\": \"bye, goodbye\"\n    },\n \
+  \   {\n      \"id\": \"test-2\",\n      \"synonyms\": \"test => check\"\n    }\n\
+  \  ]\n}"
diff --git a/specification/synonyms/put_synonym/examples/400_response/SynonymsPutResponseExample1.yaml b/specification/synonyms/put_synonym/examples/400_response/SynonymsPutResponseExample1.yaml
new file mode 100644
index 0000000000..08b38239cc
--- /dev/null
+++ b/specification/synonyms/put_synonym/examples/400_response/SynonymsPutResponseExample1.yaml
@@ -0,0 +1,14 @@
+# summary:
+description: >
+  An abbreviated response from `PUT _synonyms/my-synonyms-set`.
+  If any of the synonym rules included is not valid, the API returns an error.
+# type: response
+# response_code: 400
+value:
+  "{\n  \"error\": {\n    \"root_cause\": [\n      {\n        \"type\": \"action_request_validation_exception\"\
+  ,\n        \"reason\": \"Validation Failed: 1: More than one explicit mapping specified\
+  \ in the same synonyms rule: [hello => hi => howdy];\",\n        \"stack_trace\"\
+  : ...\n      }\n    ],\n    \"type\": \"action_request_validation_exception\",\n\
+  \    \"reason\": \"Validation Failed: 1: More than one explicit mapping specified\
+  \ in the same synonyms rule: [hello => hi => howdy];\",\n    \"stack_trace\": ...\n\
+  \  },\n  \"status\": 400\n}"
diff --git a/specification/synonyms/put_synonym_rule/SynonymRulePutRequest.ts b/specification/synonyms/put_synonym_rule/SynonymRulePutRequest.ts
index a661580cf0..29b47ef299 100644
--- a/specification/synonyms/put_synonym_rule/SynonymRulePutRequest.ts
+++ b/specification/synonyms/put_synonym_rule/SynonymRulePutRequest.ts
@@ -23,26 +23,32 @@ import { SynonymString } from '../_types/SynonymRule'
 /**
  * Create or update a synonym rule.
  * Create or update a synonym rule in a synonym set.
+ *
+ * If any of the synonym rules included is invalid, the API returns an error.
+ *
+ * When you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.
  * @rest_spec_name synonyms.put_synonym_rule
  * @availability stack since=8.10.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage_search_synonyms
+ * @doc_id synonym-rule-create
  */
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * The id of the synonym set to be updated with the synonym rule
+     * The ID of the synonym set.
      */
     set_id: Id
-
     /**
-     * The id of the synonym rule to be updated or created
+     * The ID of the synonym rule to be updated or created.
      */
     rule_id: Id
   }
-  /**
-   * The synonym rule information to update
-   */
   body: {
+    /**
+     * The synonym rule information definition, which must be in Solr format.
+     * @ext_doc_id synonym-set-define
+     */
     synonyms: SynonymString
   }
 }
diff --git a/specification/synonyms/put_synonym_rule/examples/request/SynonymRulePutRequestExample1.yaml b/specification/synonyms/put_synonym_rule/examples/request/SynonymRulePutRequestExample1.yaml
new file mode 100644
index 0000000000..ca6523d195
--- /dev/null
+++ b/specification/synonyms/put_synonym_rule/examples/request/SynonymRulePutRequestExample1.yaml
@@ -0,0 +1,5 @@
+summary: synonyms/apis/put-synonym-rule.asciidoc:107
+method_request: PUT _synonyms/my-synonyms-set/test-1
+description: ''
+type: request
+value: "{\n  \"synonyms\": \"hello, hi, howdy\"\n}"
diff --git a/specification/synonyms/put_synonym_rule/examples/response/SynonymRuleResponseExample1.yaml b/specification/synonyms/put_synonym_rule/examples/response/SynonymRuleResponseExample1.yaml
new file mode 100644
index 0000000000..e16fd7c7e7
--- /dev/null
+++ b/specification/synonyms/put_synonym_rule/examples/response/SynonymRuleResponseExample1.yaml
@@ -0,0 +1,13 @@
+# summary:
+description: >
+  A successful response from `PUT _synonyms/my-synonyms-set/test-1`.
+
+# type: response
+# response_code: ''
+value:
+  "{\n  \"result\": \"updated\",\n  \"reload_analyzers_details\": {\n    \"_shards\"\
+  : {\n      \"total\": 2,\n      \"successful\": 1,\n      \"failed\": 0\n    },\n\
+  \    \"reload_details\": [\n      {\n        \"index\": \"test-index\",\n      \
+  \  \"reloaded_analyzers\": [\n          \"my_search_analyzer\"\n        ],\n   \
+  \     \"reloaded_node_ids\": [\n          \"1wYFZzq8Sxeu_Jvt9mlbkg\"\n        ]\n\
+  \      }\n    ]\n  }\n}"