Improves Endpoint management API docs content (#191932)

## Summary

Resolves https://github.com/elastic/security-docs-internal/issues/37 by
improving the Endpoint management API docs content. Adds missing and
improves existing operation summaries and operation descriptions to
adhere to our [OAS
standards](450494532/API+reference+docs).

**Note**: Couldn’t add descriptions for the following operations, since
they’re not documented in [ESS API
docs](https://www.elastic.co/guide/en/security/8.15/management-api-overview.html):

- POST /api/endpoint/protection_updates_note/{package_policy_id}
- GET /api/endpoint/protection_updates_note/{package_policy_id}
- GET /api/endpoint/policy/summaries
- GET /api/endpoint/policy_response
- POST /api/endpoint/suggestions/{suggestion_type}
- GET /api/endpoint/metadata
- GET /api/endpoint/metadata/{id}
- GET /api/endpoint/metadata/transforms

---------

Co-authored-by: Ash <1849116+ashokaditya@users.noreply.github.com>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

x-pack/plugins/security_solution/common/api/endpoint/actions/action_log/deprecated_action_log.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action_log/{agent_id}:
     get:
-      summary: Get action requests log schema
+      summary: Get an action request log
       operationId: EndpointGetActionLog
-      description: Get action requests log
+      description: Get an action request log for the specified agent ID.
       deprecated: true
       x-codegen-enabled: false
       x-labels: [ess, serverless]

x-pack/plugins/security_solution/common/api/endpoint/actions/details/details.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/{action_id}:
     get:
-      summary: Get Action details schema
+      summary: Get action details
       operationId: EndpointGetActionsDetails
-      description: Get action details
+      description: Get the details of a response action using the action ID.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:

x-pack/plugins/security_solution/common/api/endpoint/actions/file_download/file_download.schema.yaml

@@ -3,11 +3,11 @@ info:
   title: File Download Schema
   version: '2023-10-31'
 paths:
-  /api/endpoint/action/{action_id}/file/{file_id}/download`:
+  /api/endpoint/action/{action_id}/file/{file_id}/download:
     get:
-      summary: File Download schema
+      summary: Download a file
       operationId: EndpointFileDownload
-      description: Download a file from an endpoint
+      description: Download a file from an endpoint.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:

x-pack/plugins/security_solution/common/api/endpoint/actions/file_info/file_info.schema.yaml

@@ -3,11 +3,11 @@ info:
   title: File Info Schema
   version: '2023-10-31'
 paths:
-  /api/endpoint/action/{action_id}/file/{file_id}`:
+  /api/endpoint/action/{action_id}/file/{file_id}:
     get:
-      summary: File Info schema
+      summary: Get file information
       operationId: EndpointFileInfo
-      description: Get file info
+      description: Get information for the specified file using the file ID.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:

x-pack/plugins/security_solution/common/api/endpoint/actions/list/list.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action:
     get:
-      summary: Get Actions List schema
+      summary: Get response actions
       operationId: EndpointGetActionsList
-      description: Get a list of action requests and their responses
+      description: Get a list of all response actions.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/execute/execute.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/execute:
     post:
-      summary: Execute Action
+      summary: Run a command
       operationId: EndpointExecuteAction
-      description: Execute a given command on an endpoint
+      description: Run a shell command on an endpoint.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/get_file/get_file.schema.yaml

@@ -6,9 +6,9 @@ info:
 paths:
   /api/endpoint/action/get_file:
     post:
-      summary: Get File Action
+      summary: Get a file
       operationId: EndpointGetFileAction
-      description: Get a file from an endpoint
+      description: Get a file from an endpoint.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/isolate/deprecated_isolate.schema.yaml

@@ -5,7 +5,11 @@ info:
 paths:
   /api/endpoint/isolate:
     post:
-      summary: Permanently redirects to a new location
+      summary: Isolate an endpoint
+      description: |
+        Isolate an endpoint from the network.
+        > info
+        > This URL will return a 308 permanent redirect to `POST <kibana host>:<port>/api/endpoint/action/isolate`.
       operationId: EndpointIsolateRedirect
       deprecated: true
       x-codegen-enabled: true

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/isolate/isolate.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/isolate:
     post:
-      summary: Isolate Action
+      summary: Isolate an endpoint
       operationId: EndpointIsolateAction
-      description: Isolate an endpoint
+      description: Isolate an endpoint from the network. The endpoint remains isolated until it's released.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/kill_process/kill_process.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/kill_process:
     post:
-      summary: Kill process Action
+      summary: Terminate a process
       operationId: EndpointKillProcessAction
-      description: Kill a running process on an endpoint
+      description: Terminate a running process on an endpoint.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/running_procs/running_procs.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/running_procs:
     post:
-      summary: Get Running Processes Action
+      summary: Get running processes
       operationId: EndpointGetProcessesAction
-      description: Get list of running processes on an endpoint
+      description: Get a list of all processes running on an endpoint.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/scan/scan.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/scan:
     post:
-      summary: Scan Action
+      summary: Scan a file or directory
       operationId: EndpointScanAction
-      description: Scan a file or directory
+      description: Scan a specific file or directory on an endpoint for malware.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/suspend_process/suspend_process.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/suspend_process:
     post:
-      summary: Suspend process Action
+      summary: Suspend a process
       operationId: EndpointSuspendProcessAction
-      description: Suspend a running process on an endpoint
+      description: Suspend a running process on an endpoint.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/unisolate/deprecated_unisolate.schema.yaml

@@ -5,7 +5,11 @@ info:
 paths:
   /api/endpoint/unisolate:
     post:
-      summary: Permanently redirects to a new location
+      summary: Release an isolated endpoint
+      description: |
+        Release an isolated endpoint, allowing it to rejoin a network.
+        > info
+        > This URL will return a 308 permanent redirect to `POST <kibana host>:<port>/api/endpoint/action/unisolate`.
       operationId: EndpointUnisolateRedirect
       deprecated: true
       x-codegen-enabled: true

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/unisolate/unisolate.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/unisolate:
     post:
-      summary: Unisolate Action
+      summary: Release an isolated endpoint
       operationId: EndpointUnisolateAction
-      description: Release an endpoint
+      description: Release an isolated endpoint, allowing it to rejoin a network.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/response_actions/upload/upload.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action/upload:
     post:
-      summary: Upload Action
+      summary: Upload a file
       operationId: EndpointUploadAction
-      description: Upload a file to an endpoint
+      description: Upload a file to an endpoint.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       requestBody:

x-pack/plugins/security_solution/common/api/endpoint/actions/state/state.schema.yaml

@@ -5,7 +5,8 @@ info:
 paths:
   /api/endpoint/action/state:
     get:
-      summary: Get Action State schema
+      summary: Get actions state
+      description: Get a response actions state, which reports whether encryption is enabled.
       operationId: EndpointGetActionsState
       x-codegen-enabled: true
       x-labels: [ess, serverless]

x-pack/plugins/security_solution/common/api/endpoint/actions/status/status.schema.yaml

@@ -5,9 +5,9 @@ info:
 paths:
   /api/endpoint/action_status:
     get:
-      summary: Get Actions status schema
+      summary: Get response actions status 
       operationId: EndpointGetActionsStatus
-      description: Get action status
+      description: Get the status of response actions for the specified agent IDs.
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:

x-pack/plugins/security_solution/common/api/endpoint/metadata/get_metadata.schema.yaml

@@ -5,7 +5,7 @@ info:
 paths:
   /api/endpoint/metadata:
     get:
-      summary: Get Metadata List schema
+      summary: Get a metadata list
       operationId: GetEndpointMetadataList
       x-codegen-enabled: true
       x-labels: [ess, serverless]
@@ -25,7 +25,7 @@ paths:
 
   /api/endpoint/metadata/transforms:
     get:
-      summary: Get Metadata Transform schema
+      summary: Get metadata transforms
       operationId: GetEndpointMetadataTransform
       x-codegen-enabled: false
       x-labels: [ess, serverless]
@@ -39,7 +39,7 @@ paths:
 
   /api/endpoint/metadata/{id}:
     get:
-      summary: Get Metadata schema
+      summary: Get metadata
       operationId: GetEndpointMetadata
       x-codegen-enabled: false
       x-labels: [ess, serverless]

x-pack/plugins/security_solution/common/api/endpoint/policy/deprecated_agent_policy_summary.schema.yaml

@@ -5,7 +5,7 @@ info:
 paths:
   /api/endpoint/policy/summaries:
     get:
-      summary: Get Agent Policy Summary schema
+      summary: Get an agent policy summary
       operationId: GetAgentPolicySummary
       deprecated: true
       x-codegen-enabled: true

x-pack/plugins/security_solution/common/api/endpoint/policy/policy_response.schema.yaml

@@ -5,7 +5,7 @@ info:
 paths:
   /api/endpoint/policy_response:
     get:
-      summary: Get Policy Response schema
+      summary: Get a policy response
       operationId: GetPolicyResponse
       x-codegen-enabled: true
       x-labels: [ess, serverless]

x-pack/plugins/security_solution/common/api/endpoint/protection_updates_note/protection_updates_note.schema.yaml

@@ -5,7 +5,7 @@ info:
 paths:
   /api/endpoint/protection_updates_note/{package_policy_id}:
     get:
-      summary: Get Protection Updates Note schema
+      summary: Get a protection updates note
       operationId: GetProtectionUpdatesNote
       x-codegen-enabled: true
       x-labels: [ess, serverless]
@@ -23,7 +23,7 @@ paths:
               schema:
                 $ref: '../model/schema/common.schema.yaml#/components/schemas/ProtectionUpdatesNoteResponse'
     post:
-      summary: Create Update Protection Updates Note schema
+      summary: Create or update a protection updates note
       operationId: CreateUpdateProtectionUpdatesNote
       x-codegen-enabled: true
       x-labels: [ess, serverless]

x-pack/plugins/security_solution/docs/openapi/ess/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml

@@ -13,7 +13,7 @@ servers:
 paths:
   /api/endpoint/action:
     get:
-      description: Get a list of action requests and their responses
+      description: Get a list of all response actions.
       operationId: EndpointGetActionsList
       parameters:
         - in: query
@@ -28,13 +28,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Actions List schema
+      summary: Get response actions
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/action_log/{agent_id}':
     get:
       deprecated: true
-      description: Get action requests log
+      description: Get an action request log for the specified agent ID.
       operationId: EndpointGetActionLog
       parameters:
         - in: path
@@ -54,12 +54,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get action requests log schema
+      summary: Get an action request log
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action_status:
     get:
-      description: Get action status
+      description: Get the status of response actions for the specified agent IDs.
       operationId: EndpointGetActionsStatus
       parameters:
         - in: query
@@ -77,12 +77,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/ActionStatusSuccessResponse'
           description: OK
-      summary: Get Actions status schema
+      summary: Get response actions status
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/action/{action_id}':
     get:
-      description: Get action details
+      description: Get the details of a response action using the action ID.
       operationId: EndpointGetActionsDetails
       parameters:
         - in: path
@@ -97,37 +97,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Action details schema
+      summary: Get action details
       tags:
         - Security Solution Endpoint Management API
-  '/api/endpoint/action/{action_id}/file/{file_id}/download`':
+  '/api/endpoint/action/{action_id}/file/{file_id}':
     get:
-      description: Download a file from an endpoint
-      operationId: EndpointFileDownload
-      parameters:
-        - in: path
-          name: action_id
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: file_id
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/SuccessResponse'
-          description: OK
-      summary: File Download schema
-      tags:
-        - Security Solution Endpoint Management API
-  '/api/endpoint/action/{action_id}/file/{file_id}`':
-    get:
-      description: Get file info
+      description: Get information for the specified file using the file ID.
       operationId: EndpointFileInfo
       parameters:
         - in: path
@@ -147,12 +122,37 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: File Info schema
+      summary: Get file information
+      tags:
+        - Security Solution Endpoint Management API
+  '/api/endpoint/action/{action_id}/file/{file_id}/download':
+    get:
+      description: Download a file from an endpoint.
+      operationId: EndpointFileDownload
+      parameters:
+        - in: path
+          name: action_id
+          required: true
+          schema:
+            type: string
+        - in: path
+          name: file_id
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SuccessResponse'
+          description: OK
+      summary: Download a file
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/execute:
     post:
-      description: Execute a given command on an endpoint
+      description: Run a shell command on an endpoint.
       operationId: EndpointExecuteAction
       requestBody:
         content:
@@ -167,12 +167,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Execute Action
+      summary: Run a command
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/get_file:
     post:
-      description: Get a file from an endpoint
+      description: Get a file from an endpoint.
       operationId: EndpointGetFileAction
       requestBody:
         content:
@@ -187,12 +187,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get File Action
+      summary: Get a file
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/isolate:
     post:
-      description: Isolate an endpoint
+      description: >-
+        Isolate an endpoint from the network. The endpoint remains isolated
+        until it's released.
       operationId: EndpointIsolateAction
       requestBody:
         content:
@@ -207,12 +209,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Isolate Action
+      summary: Isolate an endpoint
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/kill_process:
     post:
-      description: Kill a running process on an endpoint
+      description: Terminate a running process on an endpoint.
       operationId: EndpointKillProcessAction
       requestBody:
         content:
@@ -227,12 +229,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Kill process Action
+      summary: Terminate a process
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/running_procs:
     post:
-      description: Get list of running processes on an endpoint
+      description: Get a list of all processes running on an endpoint.
       operationId: EndpointGetProcessesAction
       requestBody:
         content:
@@ -247,12 +249,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Running Processes Action
+      summary: Get running processes
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/scan:
     post:
-      description: Scan a file or directory
+      description: Scan a specific file or directory on an endpoint for malware.
       operationId: EndpointScanAction
       requestBody:
         content:
@@ -267,11 +269,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Scan Action
+      summary: Scan a file or directory
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/state:
     get:
+      description: >-
+        Get a response actions state, which reports whether encryption is
+        enabled.
       operationId: EndpointGetActionsState
       responses:
         '200':
@@ -280,12 +285,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/ActionStateSuccessResponse'
           description: OK
-      summary: Get Action State schema
+      summary: Get actions state
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/suspend_process:
     post:
-      description: Suspend a running process on an endpoint
+      description: Suspend a running process on an endpoint.
       operationId: EndpointSuspendProcessAction
       requestBody:
         content:
@@ -300,12 +305,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Suspend process Action
+      summary: Suspend a process
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/unisolate:
     post:
-      description: Release an endpoint
+      description: 'Release an isolated endpoint, allowing it to rejoin a network.'
       operationId: EndpointUnisolateAction
       requestBody:
         content:
@@ -320,12 +325,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Unisolate Action
+      summary: Release an isolated endpoint
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/upload:
     post:
-      description: Upload a file to an endpoint
+      description: Upload a file to an endpoint.
       operationId: EndpointUploadAction
       requestBody:
         content:
@@ -340,12 +345,19 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Upload Action
+      summary: Upload a file
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/isolate:
     post:
       deprecated: true
+      description: >
+        Isolate an endpoint from the network.
+
+        > info
+
+        > This URL will return a 308 permanent redirect to `POST <kibana
+        host>:<port>/api/endpoint/action/isolate`.
       operationId: EndpointIsolateRedirect
       requestBody:
         content:
@@ -383,7 +395,7 @@ paths:
               schema:
                 example: /api/endpoint/action/isolate
                 type: string
-      summary: Permanently redirects to a new location
+      summary: Isolate an endpoint
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/metadata:
@@ -402,7 +414,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Metadata List schema
+      summary: Get a metadata list
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/metadata/{id}':
@@ -421,7 +433,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Metadata schema
+      summary: Get metadata
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/metadata/transforms:
@@ -434,7 +446,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Metadata Transform schema
+      summary: Get metadata transforms
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/policy_response:
@@ -456,7 +468,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Policy Response schema
+      summary: Get a policy response
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/policy/summaries:
@@ -482,7 +494,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Agent Policy Summary schema
+      summary: Get an agent policy summary
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/protection_updates_note/{package_policy_id}':
@@ -501,7 +513,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProtectionUpdatesNoteResponse'
           description: OK
-      summary: Get Protection Updates Note schema
+      summary: Get a protection updates note
       tags:
         - Security Solution Endpoint Management API
     post:
@@ -528,7 +540,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProtectionUpdatesNoteResponse'
           description: OK
-      summary: Create Update Protection Updates Note schema
+      summary: Create or update a protection updates note
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/suggestions/{suggestion_type}':
@@ -570,6 +582,13 @@ paths:
   /api/endpoint/unisolate:
     post:
       deprecated: true
+      description: >
+        Release an isolated endpoint, allowing it to rejoin a network.
+
+        > info
+
+        > This URL will return a 308 permanent redirect to `POST <kibana
+        host>:<port>/api/endpoint/action/unisolate`.
       operationId: EndpointUnisolateRedirect
       requestBody:
         content:
@@ -607,7 +626,7 @@ paths:
               schema:
                 example: /api/endpoint/action/unisolate
                 type: string
-      summary: Permanently redirects to a new location
+      summary: Release an isolated endpoint
       tags:
         - Security Solution Endpoint Management API
 components:

x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml

@@ -13,7 +13,7 @@ servers:
 paths:
   /api/endpoint/action:
     get:
-      description: Get a list of action requests and their responses
+      description: Get a list of all response actions.
       operationId: EndpointGetActionsList
       parameters:
         - in: query
@@ -28,13 +28,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Actions List schema
+      summary: Get response actions
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/action_log/{agent_id}':
     get:
       deprecated: true
-      description: Get action requests log
+      description: Get an action request log for the specified agent ID.
       operationId: EndpointGetActionLog
       parameters:
         - in: path
@@ -54,12 +54,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get action requests log schema
+      summary: Get an action request log
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action_status:
     get:
-      description: Get action status
+      description: Get the status of response actions for the specified agent IDs.
       operationId: EndpointGetActionsStatus
       parameters:
         - in: query
@@ -77,12 +77,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/ActionStatusSuccessResponse'
           description: OK
-      summary: Get Actions status schema
+      summary: Get response actions status
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/action/{action_id}':
     get:
-      description: Get action details
+      description: Get the details of a response action using the action ID.
       operationId: EndpointGetActionsDetails
       parameters:
         - in: path
@@ -97,37 +97,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Action details schema
+      summary: Get action details
       tags:
         - Security Solution Endpoint Management API
-  '/api/endpoint/action/{action_id}/file/{file_id}/download`':
+  '/api/endpoint/action/{action_id}/file/{file_id}':
     get:
-      description: Download a file from an endpoint
-      operationId: EndpointFileDownload
-      parameters:
-        - in: path
-          name: action_id
-          required: true
-          schema:
-            type: string
-        - in: path
-          name: file_id
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/SuccessResponse'
-          description: OK
-      summary: File Download schema
-      tags:
-        - Security Solution Endpoint Management API
-  '/api/endpoint/action/{action_id}/file/{file_id}`':
-    get:
-      description: Get file info
+      description: Get information for the specified file using the file ID.
       operationId: EndpointFileInfo
       parameters:
         - in: path
@@ -147,12 +122,37 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: File Info schema
+      summary: Get file information
+      tags:
+        - Security Solution Endpoint Management API
+  '/api/endpoint/action/{action_id}/file/{file_id}/download':
+    get:
+      description: Download a file from an endpoint.
+      operationId: EndpointFileDownload
+      parameters:
+        - in: path
+          name: action_id
+          required: true
+          schema:
+            type: string
+        - in: path
+          name: file_id
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SuccessResponse'
+          description: OK
+      summary: Download a file
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/execute:
     post:
-      description: Execute a given command on an endpoint
+      description: Run a shell command on an endpoint.
       operationId: EndpointExecuteAction
       requestBody:
         content:
@@ -167,12 +167,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Execute Action
+      summary: Run a command
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/get_file:
     post:
-      description: Get a file from an endpoint
+      description: Get a file from an endpoint.
       operationId: EndpointGetFileAction
       requestBody:
         content:
@@ -187,12 +187,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get File Action
+      summary: Get a file
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/isolate:
     post:
-      description: Isolate an endpoint
+      description: >-
+        Isolate an endpoint from the network. The endpoint remains isolated
+        until it's released.
       operationId: EndpointIsolateAction
       requestBody:
         content:
@@ -207,12 +209,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Isolate Action
+      summary: Isolate an endpoint
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/kill_process:
     post:
-      description: Kill a running process on an endpoint
+      description: Terminate a running process on an endpoint.
       operationId: EndpointKillProcessAction
       requestBody:
         content:
@@ -227,12 +229,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Kill process Action
+      summary: Terminate a process
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/running_procs:
     post:
-      description: Get list of running processes on an endpoint
+      description: Get a list of all processes running on an endpoint.
       operationId: EndpointGetProcessesAction
       requestBody:
         content:
@@ -247,12 +249,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Running Processes Action
+      summary: Get running processes
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/scan:
     post:
-      description: Scan a file or directory
+      description: Scan a specific file or directory on an endpoint for malware.
       operationId: EndpointScanAction
       requestBody:
         content:
@@ -267,11 +269,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Scan Action
+      summary: Scan a file or directory
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/state:
     get:
+      description: >-
+        Get a response actions state, which reports whether encryption is
+        enabled.
       operationId: EndpointGetActionsState
       responses:
         '200':
@@ -280,12 +285,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/ActionStateSuccessResponse'
           description: OK
-      summary: Get Action State schema
+      summary: Get actions state
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/suspend_process:
     post:
-      description: Suspend a running process on an endpoint
+      description: Suspend a running process on an endpoint.
       operationId: EndpointSuspendProcessAction
       requestBody:
         content:
@@ -300,12 +305,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Suspend process Action
+      summary: Suspend a process
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/unisolate:
     post:
-      description: Release an endpoint
+      description: 'Release an isolated endpoint, allowing it to rejoin a network.'
       operationId: EndpointUnisolateAction
       requestBody:
         content:
@@ -320,12 +325,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Unisolate Action
+      summary: Release an isolated endpoint
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/action/upload:
     post:
-      description: Upload a file to an endpoint
+      description: Upload a file to an endpoint.
       operationId: EndpointUploadAction
       requestBody:
         content:
@@ -340,7 +345,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Upload Action
+      summary: Upload a file
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/metadata:
@@ -359,7 +364,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Metadata List schema
+      summary: Get a metadata list
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/metadata/{id}':
@@ -378,7 +383,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Metadata schema
+      summary: Get metadata
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/metadata/transforms:
@@ -391,7 +396,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Metadata Transform schema
+      summary: Get metadata transforms
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/policy_response:
@@ -413,7 +418,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Policy Response schema
+      summary: Get a policy response
       tags:
         - Security Solution Endpoint Management API
   /api/endpoint/policy/summaries:
@@ -439,7 +444,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SuccessResponse'
           description: OK
-      summary: Get Agent Policy Summary schema
+      summary: Get an agent policy summary
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/protection_updates_note/{package_policy_id}':
@@ -458,7 +463,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProtectionUpdatesNoteResponse'
           description: OK
-      summary: Get Protection Updates Note schema
+      summary: Get a protection updates note
       tags:
         - Security Solution Endpoint Management API
     post:
@@ -485,7 +490,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProtectionUpdatesNoteResponse'
           description: OK
-      summary: Create Update Protection Updates Note schema
+      summary: Create or update a protection updates note
       tags:
         - Security Solution Endpoint Management API
   '/api/endpoint/suggestions/{suggestion_type}':

x-pack/test/api_integration/services/security_solution_api.gen.ts

@@ -366,7 +366,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
     /**
-     * Execute a given command on an endpoint
+     * Run a shell command on an endpoint.
      */
     endpointExecuteAction(props: EndpointExecuteActionProps) {
       return supertest
@@ -377,32 +377,29 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Download a file from an endpoint
+     * Download a file from an endpoint.
      */
     endpointFileDownload(props: EndpointFileDownloadProps) {
       return supertest
         .get(
-          replaceParams(
-            '/api/endpoint/action/{action_id}/file/{file_id}/download`',
-            props.params
-          )
+          replaceParams('/api/endpoint/action/{action_id}/file/{file_id}/download', props.params)
         )
         .set('kbn-xsrf', 'true')
         .set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
     /**
-     * Get file info
+     * Get information for the specified file using the file ID.
      */
     endpointFileInfo(props: EndpointFileInfoProps) {
       return supertest
-        .get(replaceParams('/api/endpoint/action/{action_id}/file/{file_id}`', props.params))
+        .get(replaceParams('/api/endpoint/action/{action_id}/file/{file_id}', props.params))
         .set('kbn-xsrf', 'true')
         .set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
     /**
-     * Get action details
+     * Get the details of a response action using the action ID.
      */
     endpointGetActionsDetails(props: EndpointGetActionsDetailsProps) {
       return supertest
@@ -412,7 +409,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
     /**
-     * Get a list of action requests and their responses
+     * Get a list of all response actions.
      */
     endpointGetActionsList(props: EndpointGetActionsListProps) {
       return supertest
@@ -422,6 +419,9 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get a response actions state, which reports whether encryption is enabled.
+     */
     endpointGetActionsState() {
       return supertest
         .get('/api/endpoint/action/state')
@@ -430,7 +430,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
     /**
-     * Get action status
+     * Get the status of response actions for the specified agent IDs.
      */
     endpointGetActionsStatus(props: EndpointGetActionsStatusProps) {
       return supertest
@@ -441,7 +441,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .query(props.query);
     },
     /**
-     * Get a file from an endpoint
+     * Get a file from an endpoint.
      */
     endpointGetFileAction(props: EndpointGetFileActionProps) {
       return supertest
@@ -452,7 +452,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Get list of running processes on an endpoint
+     * Get a list of all processes running on an endpoint.
      */
     endpointGetProcessesAction(props: EndpointGetProcessesActionProps) {
       return supertest
@@ -463,7 +463,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Isolate an endpoint
+     * Isolate an endpoint from the network. The endpoint remains isolated until it's released.
      */
     endpointIsolateAction(props: EndpointIsolateActionProps) {
       return supertest
@@ -473,6 +473,12 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+      * Isolate an endpoint from the network.
+> info
+> This URL will return a 308 permanent redirect to `POST <kibana host>:<port>/api/endpoint/action/isolate`.
+
+      */
     endpointIsolateRedirect(props: EndpointIsolateRedirectProps) {
       return supertest
         .post('/api/endpoint/isolate')
@@ -482,7 +488,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Kill a running process on an endpoint
+     * Terminate a running process on an endpoint.
      */
     endpointKillProcessAction(props: EndpointKillProcessActionProps) {
       return supertest
@@ -493,7 +499,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Scan a file or directory
+     * Scan a specific file or directory on an endpoint for malware.
      */
     endpointScanAction(props: EndpointScanActionProps) {
       return supertest
@@ -504,7 +510,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Suspend a running process on an endpoint
+     * Suspend a running process on an endpoint.
      */
     endpointSuspendProcessAction(props: EndpointSuspendProcessActionProps) {
       return supertest
@@ -515,7 +521,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Release an endpoint
+     * Release an isolated endpoint, allowing it to rejoin a network.
      */
     endpointUnisolateAction(props: EndpointUnisolateActionProps) {
       return supertest
@@ -525,6 +531,12 @@ Migrations are initiated per index. While the process is neither destructive nor
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+      * Release an isolated endpoint, allowing it to rejoin a network.
+> info
+> This URL will return a 308 permanent redirect to `POST <kibana host>:<port>/api/endpoint/action/unisolate`.
+
+      */
     endpointUnisolateRedirect(props: EndpointUnisolateRedirectProps) {
       return supertest
         .post('/api/endpoint/unisolate')
@@ -534,7 +546,7 @@ Migrations are initiated per index. While the process is neither destructive nor
         .send(props.body as object);
     },
     /**
-     * Upload a file to an endpoint
+     * Upload a file to an endpoint.
      */
     endpointUploadAction(props: EndpointUploadActionProps) {
       return supertest