From f39e614f927f07e541fd85dee679d7cb8f7aaaf2 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Mon, 27 Jan 2025 01:23:18 -0800
Subject: [PATCH] [DOCS] Add examples and descriptions for script APIs (#3613)

---
 .../elasticsearch-shared-overlays.yaml        |  5 +
 output/openapi/elasticsearch-openapi.json     | 54 +++++++++--
 .../elasticsearch-serverless-openapi.json     | 54 +++++++++--
 output/schema/schema.json                     | 92 ++++++++++++++-----
 output/schema/validation-errors.json          |  6 --
 specification/_doc_ids/table.csv              |  4 +
 .../delete_script/DeleteScriptRequest.ts      | 10 +-
 .../_global/get_script/GetScriptRequest.ts    | 10 +-
 .../GetScriptContextRequest.ts                |  2 +
 .../GetScriptLanguagesRequest.ts              |  2 +
 .../_global/put_script/PutScriptRequest.ts    | 23 +++--
 .../request/PutScriptRequestExample1.yaml     | 20 ++++
 .../request/PutScriptRequestExample2.yaml     | 12 +++
 specification/_types/Scripting.ts             |  2 +
 14 files changed, 235 insertions(+), 61 deletions(-)
 create mode 100644 specification/_global/put_script/examples/request/PutScriptRequestExample1.yaml
 create mode 100644 specification/_global/put_script/examples/request/PutScriptRequestExample2.yaml

diff --git a/docs/overlays/elasticsearch-shared-overlays.yaml b/docs/overlays/elasticsearch-shared-overlays.yaml
index d465e4f405..4888aa8695 100644
--- a/docs/overlays/elasticsearch-shared-overlays.yaml
+++ b/docs/overlays/elasticsearch-shared-overlays.yaml
@@ -170,6 +170,11 @@ actions:
       # S
         - name: script
           x-displayName: Script
+          description: >
+            Use the script support APIs to get a list of supported script contexts and languages.
+            Use the stored script APIs to manage stored scripts and search templates.
+          externalDocs:
+            url: https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html
         - name: search
           x-displayName: Search
         - name: search_application
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index 1ffd9b7064..ec04e38854 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -7997,7 +7997,7 @@
           {
             "in": "path",
             "name": "id",
-            "description": "Identifier for the stored script or search template.",
+            "description": "The identifier for the stored script or search template.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -8008,7 +8008,7 @@
           {
             "in": "query",
             "name": "master_timeout",
-            "description": "Specify timeout for connection to master",
+            "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
             "deprecated": false,
             "schema": {
               "$ref": "#/components/schemas/_types:Duration"
@@ -8050,11 +8050,17 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script",
         "parameters": [
           {
             "$ref": "#/components/parameters/put_script#id"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -8077,11 +8083,17 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script-1",
         "parameters": [
           {
             "$ref": "#/components/parameters/put_script#id"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -8109,7 +8121,7 @@
           {
             "in": "path",
             "name": "id",
-            "description": "Identifier for the stored script or search template.",
+            "description": "The identifier for the stored script or search template.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -8120,7 +8132,7 @@
           {
             "in": "query",
             "name": "master_timeout",
-            "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+            "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
             "deprecated": false,
             "schema": {
               "$ref": "#/components/schemas/_types:Duration"
@@ -8130,7 +8142,7 @@
           {
             "in": "query",
             "name": "timeout",
-            "description": "Period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+            "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
             "deprecated": false,
             "schema": {
               "$ref": "#/components/schemas/_types:Duration"
@@ -25838,6 +25850,9 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script-2",
         "parameters": [
           {
@@ -25846,6 +25861,9 @@
           {
             "$ref": "#/components/parameters/put_script#context"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -25868,6 +25886,9 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script-3",
         "parameters": [
           {
@@ -25876,6 +25897,9 @@
           {
             "$ref": "#/components/parameters/put_script#context"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -69650,7 +69674,7 @@
             }
           },
           "source": {
-            "description": "The script source.",
+            "description": "The script source.\nFor search templates, an object containing the search template.",
             "type": "string"
           }
         },
@@ -105234,7 +105258,7 @@
       "put_script#id": {
         "in": "path",
         "name": "id",
-        "description": "Identifier for the stored script or search template.\nMust be unique within the cluster.",
+        "description": "The identifier for the stored script or search template.\nIt must be unique within the cluster.",
         "required": true,
         "deprecated": false,
         "schema": {
@@ -105245,7 +105269,7 @@
       "put_script#context": {
         "in": "path",
         "name": "context",
-        "description": "Context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.",
+        "description": "The context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.",
         "required": true,
         "deprecated": false,
         "schema": {
@@ -105253,10 +105277,20 @@
         },
         "style": "simple"
       },
+      "put_script#context_": {
+        "in": "query",
+        "name": "context",
+        "description": "The context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.\nIf you specify both this and the `<context>` path parameter, the API uses the request path parameter.",
+        "deprecated": false,
+        "schema": {
+          "$ref": "#/components/schemas/_types:Name"
+        },
+        "style": "form"
+      },
       "put_script#master_timeout": {
         "in": "query",
         "name": "master_timeout",
-        "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+        "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
         "deprecated": false,
         "schema": {
           "$ref": "#/components/schemas/_types:Duration"
@@ -105266,7 +105300,7 @@
       "put_script#timeout": {
         "in": "query",
         "name": "timeout",
-        "description": "Period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+        "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
         "deprecated": false,
         "schema": {
           "$ref": "#/components/schemas/_types:Duration"
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
index a546882772..e672db5fa6 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -4509,7 +4509,7 @@
           {
             "in": "path",
             "name": "id",
-            "description": "Identifier for the stored script or search template.",
+            "description": "The identifier for the stored script or search template.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -4520,7 +4520,7 @@
           {
             "in": "query",
             "name": "master_timeout",
-            "description": "Specify timeout for connection to master",
+            "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
             "deprecated": false,
             "schema": {
               "$ref": "#/components/schemas/_types:Duration"
@@ -4562,11 +4562,17 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script",
         "parameters": [
           {
             "$ref": "#/components/parameters/put_script#id"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -4589,11 +4595,17 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script-1",
         "parameters": [
           {
             "$ref": "#/components/parameters/put_script#id"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -4621,7 +4633,7 @@
           {
             "in": "path",
             "name": "id",
-            "description": "Identifier for the stored script or search template.",
+            "description": "The identifier for the stored script or search template.",
             "required": true,
             "deprecated": false,
             "schema": {
@@ -4632,7 +4644,7 @@
           {
             "in": "query",
             "name": "master_timeout",
-            "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+            "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
             "deprecated": false,
             "schema": {
               "$ref": "#/components/schemas/_types:Duration"
@@ -4642,7 +4654,7 @@
           {
             "in": "query",
             "name": "timeout",
-            "description": "Period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+            "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
             "deprecated": false,
             "schema": {
               "$ref": "#/components/schemas/_types:Duration"
@@ -14785,6 +14797,9 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script-2",
         "parameters": [
           {
@@ -14793,6 +14808,9 @@
           {
             "$ref": "#/components/parameters/put_script#context"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -14815,6 +14833,9 @@
         ],
         "summary": "Create or update a script or search template",
         "description": "Creates or updates a stored script or search template.",
+        "externalDocs": {
+          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html"
+        },
         "operationId": "put-script-3",
         "parameters": [
           {
@@ -14823,6 +14844,9 @@
           {
             "$ref": "#/components/parameters/put_script#context"
           },
+          {
+            "$ref": "#/components/parameters/put_script#context_"
+          },
           {
             "$ref": "#/components/parameters/put_script#master_timeout"
           },
@@ -45099,7 +45123,7 @@
             }
           },
           "source": {
-            "description": "The script source.",
+            "description": "The script source.\nFor search templates, an object containing the search template.",
             "type": "string"
           }
         },
@@ -62056,7 +62080,7 @@
       "put_script#id": {
         "in": "path",
         "name": "id",
-        "description": "Identifier for the stored script or search template.\nMust be unique within the cluster.",
+        "description": "The identifier for the stored script or search template.\nIt must be unique within the cluster.",
         "required": true,
         "deprecated": false,
         "schema": {
@@ -62067,7 +62091,7 @@
       "put_script#context": {
         "in": "path",
         "name": "context",
-        "description": "Context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.",
+        "description": "The context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.",
         "required": true,
         "deprecated": false,
         "schema": {
@@ -62075,10 +62099,20 @@
         },
         "style": "simple"
       },
+      "put_script#context_": {
+        "in": "query",
+        "name": "context",
+        "description": "The context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.\nIf you specify both this and the `<context>` path parameter, the API uses the request path parameter.",
+        "deprecated": false,
+        "schema": {
+          "$ref": "#/components/schemas/_types:Name"
+        },
+        "style": "form"
+      },
       "put_script#master_timeout": {
         "in": "query",
         "name": "master_timeout",
-        "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+        "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
         "deprecated": false,
         "schema": {
           "$ref": "#/components/schemas/_types:Duration"
@@ -62088,7 +62122,7 @@
       "put_script#timeout": {
         "in": "query",
         "name": "timeout",
-        "description": "Period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+        "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
         "deprecated": false,
         "schema": {
           "$ref": "#/components/schemas/_types:Duration"
diff --git a/output/schema/schema.json b/output/schema/schema.json
index 5768f8a74b..e328220c86 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -4493,9 +4493,15 @@
         }
       },
       "description": "Delete a script or search template.\nDeletes a stored script or search template.",
+      "docId": "script-delete",
       "docTag": "script",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-stored-script-api.html",
       "name": "delete_script",
+      "privileges": {
+        "cluster": [
+          "manage"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "_global.delete_script"
@@ -5510,6 +5516,11 @@
       "docTag": "script",
       "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
       "name": "get_script",
+      "privileges": {
+        "cluster": [
+          "manage"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "_global.get_script"
@@ -5538,9 +5549,15 @@
         }
       },
       "description": "Get script contexts.\n\nGet a list of supported script contexts and their methods.",
+      "docId": "script-contexts",
       "docTag": "script",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-contexts.html",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-script-contexts-api.html",
       "name": "get_script_context",
+      "privileges": {
+        "cluster": [
+          "manage"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "_global.get_script_context"
@@ -5569,9 +5586,15 @@
         }
       },
       "description": "Get script languages.\n\nGet a list of available script types, languages, and contexts.",
+      "docId": "script-languages",
       "docTag": "script",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-script-languages-api.html",
       "name": "get_script_languages",
+      "privileges": {
+        "cluster": [
+          "manage"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "_global.get_script_languages"
@@ -14378,9 +14401,17 @@
         }
       },
       "description": "Create or update a script or search template.\nCreates or updates a stored script or search template.",
+      "docId": "script-put",
       "docTag": "script",
-      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
+      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/create-stored-script-api.html",
+      "extDocId": "search-template",
+      "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html",
       "name": "put_script",
+      "privileges": {
+        "cluster": [
+          "manage"
+        ]
+      },
       "request": {
         "name": "Request",
         "namespace": "_global.put_script"
@@ -24715,7 +24746,7 @@
       },
       "path": [
         {
-          "description": "Identifier for the stored script or search template.",
+          "description": "The identifier for the stored script or search template.",
           "name": "id",
           "required": true,
           "type": {
@@ -24729,7 +24760,7 @@
       ],
       "query": [
         {
-          "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+          "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
           "name": "master_timeout",
           "required": false,
           "serverDefault": "30s",
@@ -24742,7 +24773,7 @@
           }
         },
         {
-          "description": "Period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+          "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
           "name": "timeout",
           "required": false,
           "serverDefault": "30s",
@@ -24755,7 +24786,7 @@
           }
         }
       ],
-      "specLocation": "_global/delete_script/DeleteScriptRequest.ts#L24-L59"
+      "specLocation": "_global/delete_script/DeleteScriptRequest.ts#L24-L63"
     },
     {
       "kind": "response",
@@ -26418,7 +26449,7 @@
       },
       "path": [
         {
-          "description": "Identifier for the stored script or search template.",
+          "description": "The identifier for the stored script or search template.",
           "name": "id",
           "required": true,
           "type": {
@@ -26432,9 +26463,10 @@
       ],
       "query": [
         {
-          "description": "Specify timeout for connection to master",
+          "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
           "name": "master_timeout",
           "required": false,
+          "serverDefault": "",
           "type": {
             "kind": "instance_of",
             "type": {
@@ -26444,7 +26476,7 @@
           }
         }
       ],
-      "specLocation": "_global/get_script/GetScriptRequest.ts#L24-L49"
+      "specLocation": "_global/get_script/GetScriptRequest.ts#L24-L55"
     },
     {
       "kind": "response",
@@ -26626,7 +26658,7 @@
       },
       "path": [],
       "query": [],
-      "specLocation": "_global/get_script_context/GetScriptContextRequest.ts#L22-L37"
+      "specLocation": "_global/get_script_context/GetScriptContextRequest.ts#L22-L39"
     },
     {
       "kind": "response",
@@ -26711,7 +26743,7 @@
       },
       "path": [],
       "query": [],
-      "specLocation": "_global/get_script_languages/GetScriptLanguagesRequest.ts#L22-L37"
+      "specLocation": "_global/get_script_languages/GetScriptLanguagesRequest.ts#L22-L39"
     },
     {
       "kind": "response",
@@ -31529,7 +31561,7 @@
         "kind": "properties",
         "properties": [
           {
-            "description": "Contains the script or search template, its parameters, and its language.",
+            "description": "The script or search template, its parameters, and its language.",
             "name": "script",
             "required": true,
             "type": {
@@ -31555,7 +31587,7 @@
       },
       "path": [
         {
-          "description": "Identifier for the stored script or search template.\nMust be unique within the cluster.",
+          "description": "The identifier for the stored script or search template.\nIt must be unique within the cluster.",
           "name": "id",
           "required": true,
           "type": {
@@ -31567,7 +31599,7 @@
           }
         },
         {
-          "description": "Context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.",
+          "description": "The context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.",
           "name": "context",
           "required": false,
           "type": {
@@ -31581,7 +31613,19 @@
       ],
       "query": [
         {
-          "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+          "description": "The context in which the script or search template should run.\nTo prevent errors, the API immediately compiles the script or template in this context.\nIf you specify both this and the `<context>` path parameter, the API uses the request path parameter.",
+          "name": "context",
+          "required": false,
+          "type": {
+            "kind": "instance_of",
+            "type": {
+              "name": "Name",
+              "namespace": "_types"
+            }
+          }
+        },
+        {
+          "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
           "name": "master_timeout",
           "required": false,
           "serverDefault": "30s",
@@ -31594,7 +31638,7 @@
           }
         },
         {
-          "description": "Period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.",
+          "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.",
           "name": "timeout",
           "required": false,
           "serverDefault": "30s",
@@ -31607,7 +31651,7 @@
           }
         }
       ],
-      "specLocation": "_global/put_script/PutScriptRequest.ts#L25-L76"
+      "specLocation": "_global/put_script/PutScriptRequest.ts#L25-L87"
     },
     {
       "kind": "response",
@@ -50463,7 +50507,7 @@
         }
       ],
       "shortcutProperty": "source",
-      "specLocation": "_types/Scripting.ts#L73-L97"
+      "specLocation": "_types/Scripting.ts#L75-L99"
     },
     {
       "kind": "interface",
@@ -50495,7 +50539,7 @@
           }
         }
       ],
-      "specLocation": "_types/Scripting.ts#L99-L102"
+      "specLocation": "_types/Scripting.ts#L101-L104"
     },
     {
       "kind": "enum",
@@ -51981,7 +52025,7 @@
       },
       "properties": [
         {
-          "description": "The language the script is written in.",
+          "description": "The language the script is written in.\nFor serach templates, use `mustache`.",
           "name": "lang",
           "required": true,
           "type": {
@@ -52015,7 +52059,7 @@
           }
         },
         {
-          "description": "The script source.",
+          "description": "The script source.\nFor search templates, an object containing the search template.",
           "name": "source",
           "required": true,
           "type": {
@@ -52027,7 +52071,7 @@
           }
         }
       ],
-      "specLocation": "_types/Scripting.ts#L47-L57"
+      "specLocation": "_types/Scripting.ts#L47-L59"
     },
     {
       "kind": "type_alias",
diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json
index b312d62d19..7b481fb259 100644
--- a/output/schema/validation-errors.json
+++ b/output/schema/validation-errors.json
@@ -309,12 +309,6 @@
       ],
       "response": []
     },
-    "put_script": {
-      "request": [
-        "Request: missing json spec query parameter 'context'"
-      ],
-      "response": []
-    },
     "reindex": {
       "request": [
         "Request: query parameter 'require_alias' does not exist in the json spec",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index 7dba85cb2d..7151cd8336 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -511,7 +511,11 @@ rollup-stop-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}
 routing,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/docs-get.html#get-routing
 run-as-privilege,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html
 runtime-search-request,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/runtime-search-request.html
+script-contexts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-script-contexts-api.html
+script-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-stored-script-api.html
+script-languages,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-script-languages-api.html
 script-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/script-processor.html
+script-put,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/create-stored-script-api.html
 scroll-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#scroll-search-results
 search-after,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after
 search-aggregations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations.html
diff --git a/specification/_global/delete_script/DeleteScriptRequest.ts b/specification/_global/delete_script/DeleteScriptRequest.ts
index 9058812f57..586e1a29ae 100644
--- a/specification/_global/delete_script/DeleteScriptRequest.ts
+++ b/specification/_global/delete_script/DeleteScriptRequest.ts
@@ -27,7 +27,9 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name delete_script
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage
  * @doc_tag script
+ * @doc_id script-delete
  */
 export interface Request extends RequestBase {
   urls: [
@@ -38,20 +40,22 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * Identifier for the stored script or search template.
+     * The identifier for the stored script or search template.
      */
     id: Id
   }
   query_parameters: {
     /**
-     * Period to wait for a connection to the master node.
+     * The period to wait for a connection to the master node.
      * If no response is received before the timeout expires, the request fails and returns an error.
+     * It can also be set to `-1` to indicate that the request should never timeout.
      * @server_default 30s
      */
     master_timeout?: Duration
     /**
-     * Period to wait for a response.
+     * The period to wait for a response.
      * If no response is received before the timeout expires, the request fails and returns an error.
+     * It can also be set to `-1` to indicate that the request should never timeout.
      * @server_default 30s
      */
     timeout?: Duration
diff --git a/specification/_global/get_script/GetScriptRequest.ts b/specification/_global/get_script/GetScriptRequest.ts
index 8d52547b2b..ee1b49fd01 100644
--- a/specification/_global/get_script/GetScriptRequest.ts
+++ b/specification/_global/get_script/GetScriptRequest.ts
@@ -27,6 +27,7 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name get_script
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage
  * @doc_tag script
  */
 export interface Request extends RequestBase {
@@ -38,12 +39,17 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * Identifier for the stored script or search template.
+     * The identifier for the stored script or search template.
      */
     id: Id
   }
   query_parameters: {
-    /** Specify timeout for connection to master */
+    /**
+     * The period to wait for the master node.
+     * If the master node is not available before the timeout expires, the request fails and returns an error.
+     * It can also be set to `-1` to indicate that the request should never timeout.
+     * @server_default
+     */
     master_timeout?: Duration
   }
 }
diff --git a/specification/_global/get_script_context/GetScriptContextRequest.ts b/specification/_global/get_script_context/GetScriptContextRequest.ts
index f8af3e1a75..1b69e9025b 100644
--- a/specification/_global/get_script_context/GetScriptContextRequest.ts
+++ b/specification/_global/get_script_context/GetScriptContextRequest.ts
@@ -25,7 +25,9 @@ import { RequestBase } from '@_types/Base'
  * Get a list of supported script contexts and their methods.
  * @rest_spec_name get_script_context
  * @availability stack stability=stable
+ * @cluster_privileges manage
  * @doc_tag script
+ * @doc_id script-contexts
  */
 export interface Request extends RequestBase {
   urls: [
diff --git a/specification/_global/get_script_languages/GetScriptLanguagesRequest.ts b/specification/_global/get_script_languages/GetScriptLanguagesRequest.ts
index 9fe257a96e..95ceed49c3 100644
--- a/specification/_global/get_script_languages/GetScriptLanguagesRequest.ts
+++ b/specification/_global/get_script_languages/GetScriptLanguagesRequest.ts
@@ -25,7 +25,9 @@ import { RequestBase } from '@_types/Base'
  * Get a list of available script types, languages, and contexts.
  * @rest_spec_name get_script_languages
  * @availability stack stability=stable
+ * @cluster_privileges manage
  * @doc_tag script
+ * @doc_id script-languages
  */
 export interface Request extends RequestBase {
   urls: [
diff --git a/specification/_global/put_script/PutScriptRequest.ts b/specification/_global/put_script/PutScriptRequest.ts
index 11b6fcda38..d31a4420be 100644
--- a/specification/_global/put_script/PutScriptRequest.ts
+++ b/specification/_global/put_script/PutScriptRequest.ts
@@ -28,7 +28,10 @@ import { Duration } from '@_types/Time'
  * @rest_spec_name put_script
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges manage
  * @doc_tag script
+ * @doc_id script-put
+ * @ext_doc_id search-template
  */
 export interface Request extends RequestBase {
   urls: [
@@ -43,33 +46,41 @@ export interface Request extends RequestBase {
   ]
   path_parts: {
     /**
-     * Identifier for the stored script or search template.
-     * Must be unique within the cluster.
+     * The identifier for the stored script or search template.
+     * It must be unique within the cluster.
      */
     id: Id
     /**
-     * Context in which the script or search template should run.
+     * The context in which the script or search template should run.
      * To prevent errors, the API immediately compiles the script or template in this context.
      */
     context?: Name
   }
   query_parameters: {
     /**
-     * Period to wait for a connection to the master node.
+     * The context in which the script or search template should run.
+     * To prevent errors, the API immediately compiles the script or template in this context.
+     * If you specify both this and the `<context>` path parameter, the API uses the request path parameter.
+     */
+    context?: Name
+    /**
+     * The period to wait for a connection to the master node.
      * If no response is received before the timeout expires, the request fails and returns an error.
+     * It can also be set to `-1` to indicate that the request should never timeout.
      * @server_default 30s
      */
     master_timeout?: Duration
     /**
-     * Period to wait for a response.
+     * The period to wait for a response.
      * If no response is received before the timeout expires, the request fails and returns an error.
+     * It can also be set to `-1` to indicate that the request should never timeout.
      * @server_default 30s
      */
     timeout?: Duration
   }
   body: {
     /**
-     * Contains the script or search template, its parameters, and its language.
+     * The script or search template, its parameters, and its language.
      */
     script: StoredScript
   }
diff --git a/specification/_global/put_script/examples/request/PutScriptRequestExample1.yaml b/specification/_global/put_script/examples/request/PutScriptRequestExample1.yaml
new file mode 100644
index 0000000000..0d7ff22281
--- /dev/null
+++ b/specification/_global/put_script/examples/request/PutScriptRequestExample1.yaml
@@ -0,0 +1,20 @@
+summary: Create a search template
+# method_request: PUT _scripts/my-search-template
+description: >
+  Run `PUT _scripts/my-search-template` to create a search template.
+# type: request
+value: |-
+  {
+    "script": {
+      "lang": "mustache",
+      "source": {
+        "query": {
+          "match": {
+            "message": "{{query_string}}"
+          }
+        },
+        "from": "{{from}}",
+        "size": "{{size}}"
+      }
+    }
+  }
diff --git a/specification/_global/put_script/examples/request/PutScriptRequestExample2.yaml b/specification/_global/put_script/examples/request/PutScriptRequestExample2.yaml
new file mode 100644
index 0000000000..ca3bf8593b
--- /dev/null
+++ b/specification/_global/put_script/examples/request/PutScriptRequestExample2.yaml
@@ -0,0 +1,12 @@
+summary: Create a stored script
+# method_request: PUT _scripts/my-stored-script
+description: >
+  Run `PUT _scripts/my-stored-script` to create a stored script.
+# type: request
+value: |-
+  {
+    "script": {
+      "lang": "painless",
+      "source": "Math.log(_score * 2) + params['my_modifier']"
+    }
+  }
diff --git a/specification/_types/Scripting.ts b/specification/_types/Scripting.ts
index 685d4ee789..fe76655c5d 100644
--- a/specification/_types/Scripting.ts
+++ b/specification/_types/Scripting.ts
@@ -47,11 +47,13 @@ export enum ScriptLanguage {
 export class StoredScript {
   /**
    * The language the script is written in.
+   * For serach templates, use `mustache`.
    */
   lang: ScriptLanguage
   options?: Dictionary<string, string>
   /**
    * The script source.
+   * For search templates, an object containing the search template.
    */
   source: string
 }