[9.0] [DOCS][API] Update Security endpoint management APIs (#232205) (#232380)

natasha-moore-elastic · web-flow · commit 002008a72dfe · 2025-08-20T21:46:02.000+02:00
# Backport This will backport the following commits from `main` to `9.0`: - [[DOCS][API] Update Security endpoint management APIs (#232205)](#232205)
diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml
@@ -101,17 +101,11 @@ tags:
     description: Manage the roles that grant Elasticsearch and Kibana privileges.
     externalDocs:
       description: Kibana role management
-<<<<<<< HEAD
-      url: https://www.elastic.co/guide/en/kibana/master/kibana-role-management.html
-  - description: |
-      Export sets of saved objects that you want to import into Kibana, resolve import errors, and rotate an encryption key for encrypted saved objects with the saved objects APIs.
-=======
       url: https://www.elastic.co/docs/deploy-manage/users-roles/serverless-custom-roles
   - name: saved objects
     x-displayName: Saved objects
     description: |
       Export or import sets of saved objects.
->>>>>>> 128b8457a61 ([DOCS] Fix URLs in Kibana API documentation (#215989))
 
       To manage a specific type of saved object, use the corresponding APIs.
       For example, use:
@@ -12086,7 +12080,11 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}:
     get:
-      description: Get information for the specified file using the file ID.
+      description: |
+        Get information for the specified file using the file ID.
+        > info
+        > To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileInfo
       parameters:
         - in: path
@@ -12111,7 +12109,11 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}/download:
     get:
-      description: Download a file from an endpoint.
+      description: |
+        Download a file from an endpoint. 
+        > info
+        > To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileDownload
       parameters:
         - in: path
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
@@ -13976,7 +13976,11 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}:
     get:
-      description: Get information for the specified file using the file ID.
+      description: |
+        Get information for the specified file using the file ID.
+        > info
+        > To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileInfo
       parameters:
         - in: path
@@ -14001,7 +14005,11 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}/download:
     get:
-      description: Download a file from an endpoint.
+      description: |
+        Download a file from an endpoint. 
+        > info
+        > To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileDownload
       parameters:
         - in: path
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/endpoint/actions/file_download/file_download.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/endpoint/actions/file_download/file_download.schema.yaml
@@ -7,7 +7,11 @@ paths:
     get:
       summary: Download a file
       operationId: EndpointFileDownload
-      description: Download a file from an endpoint.
+      description: |
+        Download a file from an endpoint. 
+        > info
+        > To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/endpoint/actions/file_info/file_info.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/endpoint/actions/file_info/file_info.schema.yaml
@@ -7,7 +7,11 @@ paths:
     get:
       summary: Get file information
       operationId: EndpointFileInfo
-      description: Get information for the specified file using the file ID.
+      description: |
+        Get information for the specified file using the file ID.
+        > info
+        > To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       x-codegen-enabled: true
       x-labels: [ess, serverless]
       parameters:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts
@@ -865,8 +865,12 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Download a file from an endpoint.
-   */
+    * Download a file from an endpoint. 
+> info
+> To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+> {`file_id`} = {`action_id`}`.`{`agent_id`}
+
+    */
   async endpointFileDownload(props: EndpointFileDownloadProps) {
     this.log.info(`${new Date().toISOString()} Calling API EndpointFileDownload`);
     return this.kbnClient
@@ -883,8 +887,12 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Get information for the specified file using the file ID.
-   */
+    * Get information for the specified file using the file ID.
+> info
+> To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+> {`file_id`} = {`action_id`}`.`{`agent_id`}
+
+    */
   async endpointFileInfo(props: EndpointFileInfoProps) {
     this.log.info(`${new Date().toISOString()} Calling API EndpointFileInfo`);
     return this.kbnClient
diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml
@@ -123,7 +123,15 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}:
     get:
-      description: Get information for the specified file using the file ID.
+      description: >
+        Get information for the specified file using the file ID.
+
+        > info
+
+        > To construct a `file_id`, combine the `action_id` and `agent_id`
+        values using a dot separator:
+
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileInfo
       parameters:
         - in: path
@@ -148,7 +156,15 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}/download:
     get:
-      description: Download a file from an endpoint.
+      description: >
+        Download a file from an endpoint. 
+
+        > info
+
+        > To construct a `file_id`, combine the `action_id` and `agent_id`
+        values using a dot separator:
+
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileDownload
       parameters:
         - in: path
diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_endpoint_management_api_2023_10_31.bundled.schema.yaml
@@ -123,7 +123,15 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}:
     get:
-      description: Get information for the specified file using the file ID.
+      description: >
+        Get information for the specified file using the file ID.
+
+        > info
+
+        > To construct a `file_id`, combine the `action_id` and `agent_id`
+        values using a dot separator:
+
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileInfo
       parameters:
         - in: path
@@ -148,7 +156,15 @@ paths:
         - Security Endpoint Management API
   /api/endpoint/action/{action_id}/file/{file_id}/download:
     get:
-      description: Download a file from an endpoint.
+      description: >
+        Download a file from an endpoint. 
+
+        > info
+
+        > To construct a `file_id`, combine the `action_id` and `agent_id`
+        values using a dot separator:
+
+        > {`file_id`} = {`action_id`}`.`{`agent_id`}
       operationId: EndpointFileDownload
       parameters:
         - in: path
diff --git a/x-pack/test/api_integration/services/security_solution_api.gen.ts b/x-pack/test/api_integration/services/security_solution_api.gen.ts
@@ -543,8 +543,12 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
         .send(props.body as object);
     },
     /**
-     * Download a file from an endpoint.
-     */
+      * Download a file from an endpoint. 
+> info
+> To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+> {`file_id`} = {`action_id`}`.`{`agent_id`}
+
+      */
     endpointFileDownload(props: EndpointFileDownloadProps, kibanaSpace: string = 'default') {
       return supertest
         .get(
@@ -558,8 +562,12 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
     },
     /**
-     * Get information for the specified file using the file ID.
-     */
+      * Get information for the specified file using the file ID.
+> info
+> To construct a `file_id`, combine the `action_id` and `agent_id` values using a dot separator:
+> {`file_id`} = {`action_id`}`.`{`agent_id`}
+
+      */
     endpointFileInfo(props: EndpointFileInfoProps, kibanaSpace: string = 'default') {
       return supertest
         .get(
