[8.16] Improves Exceptions API docs content (#193040) (#204733)

# Backport

This will backport the following commits from `main` to `8.16`:
- [Improves Exceptions API docs content
(#193040)](https://github.com/elastic/kibana/pull/193040)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT
[{"author":{"name":"natasha-moore-elastic","email":"137783811+natasha-moore-elastic@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-09-19T08:13:14Z","message":"Improves
Exceptions API docs content (#193040)\n\n## Summary\r\n\r\nResolves
https://github.com/elastic/security-docs-internal/issues/33
by\r\nimproving the Exceptions API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"c676d2bd72f87fceecd8d459335ed56e36acf661","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","backport:skip","v9.0.0","docs","Team:Detections
and Resp","Team: SecuritySolution","APIDocs","Team:Detection Rule
Management","Team:Detection
Engine"],"number":193040,"url":"https://github.com/elastic/kibana/pull/193040","mergeCommit":{"message":"Improves
Exceptions API docs content (#193040)\n\n## Summary\r\n\r\nResolves
https://github.com/elastic/security-docs-internal/issues/33
by\r\nimproving the Exceptions API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"c676d2bd72f87fceecd8d459335ed56e36acf661"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/193040","number":193040,"mergeCommit":{"message":"Improves
Exceptions API docs content (#193040)\n\n## Summary\r\n\r\nResolves
https://github.com/elastic/security-docs-internal/issues/33
by\r\nimproving the Exceptions API docs content. Adds missing and
improves\r\nexisting operation summaries and operation descriptions to
adhere to
our\r\n[OAS\r\nstandards](450494532/API+reference+docs).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"c676d2bd72f87fceecd8d459335ed56e36acf661"}}]}]
BACKPORT-->

---------

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

oas_docs/output/kibana.yaml

@@ -8781,6 +8781,7 @@ paths:
         - Security Detections API
   /api/detection_engine/rules/{id}/exceptions:
     post:
+      description: Create exception items that apply to a single detection rule.
       operationId: CreateRuleExceptionListItems
       parameters:
         - description: Detection rule's identifier
@@ -8838,7 +8839,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates rule exception list items
+      summary: Create rule exception list items
       tags:
         - Security Exceptions API
   /api/detection_engine/rules/prepackaged:
@@ -10869,6 +10870,7 @@ paths:
         - Security Entity Analytics API
   /api/exception_lists:
     delete:
+      description: Delete an exception list using the `id` or `list_id` field.
       operationId: DeleteExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -10928,10 +10930,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list
+      summary: Delete an exception list
       tags:
         - Security Exceptions API
     get:
+      description: Get the details of an exception list using the `id` or `list_id` field.
       operationId: ReadExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -10991,10 +10994,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list using its `id` or `list_id` field
+      summary: Get exception list details
       tags:
         - Security Exceptions API
     post:
+      description: |
+        An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists.
+        > info
+        > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
       operationId: CreateExceptionList
       requestBody:
         content:
@@ -11068,10 +11075,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list
+      summary: Create an exception list
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list using the `id` or `list_id` field.
       operationId: UpdateExceptionList
       requestBody:
         content:
@@ -11148,11 +11156,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list
+      summary: Update an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_duplicate:
     post:
+      description: Duplicate an existing exception list.
       operationId: DuplicateExceptionList
       parameters:
         - description: Exception list's human identifier
@@ -11215,12 +11224,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Duplicates an exception list
+      summary: Duplicate an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_export:
     post:
-      description: Exports an exception list and its associated items to an .ndjson file
+      description: Export an exception list and its associated items to an NDJSON file.
       operationId: ExportExceptionList
       parameters:
         - description: Exception list's identifier
@@ -11291,11 +11300,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Exports an exception list
+      summary: Export an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_find:
     get:
+      description: Get a list of all exception lists.
       operationId: FindExceptionLists
       parameters:
         - description: |
@@ -11403,12 +11413,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception lists
+      summary: Get exception lists
       tags:
         - Security Exceptions API
   /api/exception_lists/_import:
     post:
-      description: Imports an exception list and associated items
+      description: Import an exception list and its associated items from an NDJSON file.
       operationId: ImportExceptionList
       parameters:
         - description: |
@@ -11512,11 +11522,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Imports an exception list
+      summary: Import an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/items:
     delete:
+      description: Delete an exception list item using the `id` or `item_id` field.
       operationId: DeleteExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -11576,10 +11587,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list item
+      summary: Delete an exception list item
       tags:
         - Security Exceptions API
     get:
+      description: Get the details of an exception list item using the `id` or `item_id` field.
       operationId: ReadExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -11639,10 +11651,14 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Gets an exception list item
+      summary: Get an exception list item
       tags:
         - Security Exceptions API
     post:
+      description: |
+        Create an exception item and associate it with the specified exception list.
+        > info
+        > Before creating exception items, you must create an exception list.
       operationId: CreateExceptionListItem
       requestBody:
         content:
@@ -11726,10 +11742,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list item
+      summary: Create an exception list item
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list item using the `id` or `item_id` field.
       operationId: UpdateExceptionListItem
       requestBody:
         content:
@@ -11817,11 +11834,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list item
+      summary: Update an exception list item
       tags:
         - Security Exceptions API
   /api/exception_lists/items/_find:
     get:
+      description: Get a list of all exception list items in the specified list.
       operationId: FindExceptionListItems
       parameters:
         - description: List's id
@@ -11949,11 +11967,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception list items
+      summary: Get exception list items
       tags:
         - Security Exceptions API
   /api/exception_lists/summary:
     get:
+      description: Get a summary of the specified exception list.
       operationId: ReadExceptionListSummary
       parameters:
         - description: Exception list's identifier generated upon creation
@@ -12032,11 +12051,15 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list summary
+      summary: Get an exception list summary
       tags:
         - Security Exceptions API
   /api/exceptions/shared:
     post:
+      description: |
+        An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules.
+        > info
+        > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
       operationId: CreateSharedExceptionList
       requestBody:
         content:
@@ -12091,7 +12114,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
           description: Internal server error response
-      summary: Creates a shared exception list
+      summary: Create a shared exception list
       tags:
         - Security Exceptions API
   /api/fleet/agent_download_sources:

packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml

@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateExceptionList
       x-codegen-enabled: true
-      summary: Creates an exception list
+      summary: Create an exception list
+      description: |
+        An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists.
+        > info
+        > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
       requestBody:
         description: Exception list's properties
         required: true

packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml

@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateExceptionListItem
       x-codegen-enabled: true
-      summary: Creates an exception list item
+      summary: Create an exception list item
+      description: |
+        Create an exception item and associate it with the specified exception list.
+        > info
+        > Before creating exception items, you must create an exception list.
       requestBody:
         description: Exception list item's properties
         required: true

packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateRuleExceptionListItems
       x-codegen-enabled: true
-      summary: Creates rule exception list items
+      summary: Create rule exception list items
+      description: Create exception items that apply to a single detection rule. 
       parameters:
         - name: id
           in: path

packages/kbn-securitysolution-exceptions-common/api/create_shared_exceptions_list/create_shared_exceptions_list.schema.yaml

@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: CreateSharedExceptionList
       x-codegen-enabled: true
-      summary: Creates a shared exception list
+      summary: Create a shared exception list
+      description: |
+        An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules.
+        > info
+        > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
       requestBody:
         required: true
         content:

packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DeleteExceptionList
       x-codegen-enabled: true
-      summary: Deletes an exception list
+      summary: Delete an exception list
+      description: Delete an exception list using the `id` or `list_id` field.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DeleteExceptionListItem
       x-codegen-enabled: true
-      summary: Deletes an exception list item
+      summary: Delete an exception list item
+      description: Delete an exception list item using the `id` or `item_id` field.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: DuplicateExceptionList
       x-codegen-enabled: true
-      summary: Duplicates an exception list
+      summary: Duplicate an exception list
+      description: Duplicate an existing exception list.
       parameters:
         - name: list_id
           in: query

packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml

@@ -8,8 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ExportExceptionList
       x-codegen-enabled: true
-      summary: Exports an exception list
-      description: Exports an exception list and its associated items to an .ndjson file
+      summary: Export an exception list
+      description: Export an exception list and its associated items to an NDJSON file.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: FindExceptionListItems
       x-codegen-enabled: true
-      summary: Finds exception list items
+      summary: Get exception list items
+      description: Get a list of all exception list items in the specified list.
       parameters:
         - name: list_id
           in: query

packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: FindExceptionLists
       x-codegen-enabled: true
-      summary: Finds exception lists
+      summary: Get exception lists
+      description: Get a list of all exception lists.
       parameters:
         - name: filter
           in: query

packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml

@@ -8,8 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ImportExceptionList
       x-codegen-enabled: true
-      summary: Imports an exception list
-      description: Imports an exception list and associated items
+      summary: Import an exception list
+      description: Import an exception list and its associated items from an NDJSON file.
       requestBody:
         required: true
         content:

packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts

@@ -98,6 +98,12 @@ export class Client {
     this.kbnClient = options.kbnClient;
     this.log = options.log;
   }
+  /**
+    * An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists.
+> info
+> All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
+
+    */
   async createExceptionList(props: CreateExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateExceptionList`);
     return this.kbnClient
@@ -111,6 +117,12 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * Create an exception item and associate it with the specified exception list.
+> info
+> Before creating exception items, you must create an exception list.
+
+    */
   async createExceptionListItem(props: CreateExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateExceptionListItem`);
     return this.kbnClient
@@ -124,6 +136,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Create exception items that apply to a single detection rule.
+   */
   async createRuleExceptionListItems(props: CreateRuleExceptionListItemsProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateRuleExceptionListItems`);
     return this.kbnClient
@@ -137,6 +152,12 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+    * An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules.
+> info
+> All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
+
+    */
   async createSharedExceptionList(props: CreateSharedExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API CreateSharedExceptionList`);
     return this.kbnClient
@@ -150,6 +171,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete an exception list using the `id` or `list_id` field.
+   */
   async deleteExceptionList(props: DeleteExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteExceptionList`);
     return this.kbnClient
@@ -164,6 +188,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Delete an exception list item using the `id` or `item_id` field.
+   */
   async deleteExceptionListItem(props: DeleteExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API DeleteExceptionListItem`);
     return this.kbnClient
@@ -178,6 +205,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Duplicate an existing exception list.
+   */
   async duplicateExceptionList(props: DuplicateExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API DuplicateExceptionList`);
     return this.kbnClient
@@ -193,7 +223,7 @@ export class Client {
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Exports an exception list and its associated items to an .ndjson file
+   * Export an exception list and its associated items to an NDJSON file.
    */
   async exportExceptionList(props: ExportExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API ExportExceptionList`);
@@ -209,6 +239,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a list of all exception list items in the specified list.
+   */
   async findExceptionListItems(props: FindExceptionListItemsProps) {
     this.log.info(`${new Date().toISOString()} Calling API FindExceptionListItems`);
     return this.kbnClient
@@ -223,6 +256,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a list of all exception lists.
+   */
   async findExceptionLists(props: FindExceptionListsProps) {
     this.log.info(`${new Date().toISOString()} Calling API FindExceptionLists`);
     return this.kbnClient
@@ -238,7 +274,7 @@ export class Client {
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Imports an exception list and associated items
+   * Import an exception list and its associated items from an NDJSON file.
    */
   async importExceptionList(props: ImportExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API ImportExceptionList`);
@@ -254,6 +290,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of an exception list using the `id` or `list_id` field.
+   */
   async readExceptionList(props: ReadExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadExceptionList`);
     return this.kbnClient
@@ -268,6 +307,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get the details of an exception list item using the `id` or `item_id` field.
+   */
   async readExceptionListItem(props: ReadExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadExceptionListItem`);
     return this.kbnClient
@@ -282,6 +324,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Get a summary of the specified exception list.
+   */
   async readExceptionListSummary(props: ReadExceptionListSummaryProps) {
     this.log.info(`${new Date().toISOString()} Calling API ReadExceptionListSummary`);
     return this.kbnClient
@@ -296,6 +341,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Update an exception list using the `id` or `list_id` field.
+   */
   async updateExceptionList(props: UpdateExceptionListProps) {
     this.log.info(`${new Date().toISOString()} Calling API UpdateExceptionList`);
     return this.kbnClient
@@ -309,6 +357,9 @@ export class Client {
       })
       .catch(catchAxiosErrorFormatAndThrow);
   }
+  /**
+   * Update an exception list item using the `id` or `item_id` field.
+   */
   async updateExceptionListItem(props: UpdateExceptionListItemProps) {
     this.log.info(`${new Date().toISOString()} Calling API UpdateExceptionListItem`);
     return this.kbnClient

packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadExceptionList
       x-codegen-enabled: true
-      summary: Retrieves an exception list using its `id` or `list_id` field
+      summary: Get exception list details
+      description: Get the details of an exception list using the `id` or `list_id` field.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadExceptionListItem
       x-codegen-enabled: true
-      summary: Gets an exception list item
+      summary: Get an exception list item
+      description: Get the details of an exception list item using the `id` or `item_id` field.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: ReadExceptionListSummary
       x-codegen-enabled: true
-      summary: Retrieves an exception list summary
+      summary: Get an exception list summary
+      description: Get a summary of the specified exception list.
       parameters:
         - name: id
           in: query

packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: UpdateExceptionList
       x-codegen-enabled: true
-      summary: Updates an exception list
+      summary: Update an exception list
+      description: Update an exception list using the `id` or `list_id` field.
       requestBody:
         description: Exception list's properties
         required: true

packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml

@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: UpdateExceptionListItem
       x-codegen-enabled: true
-      summary: Updates an exception list item
+      summary: Update an exception list item
+      description: Update an exception list item using the `id` or `item_id` field.
       requestBody:
         description: Exception list item's properties
         required: true

packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml

@@ -16,6 +16,7 @@ servers:
 paths:
   '/api/detection_engine/rules/{id}/exceptions':
     post:
+      description: Create exception items that apply to a single detection rule.
       operationId: CreateRuleExceptionListItems
       parameters:
         - description: Detection rule's identifier
@@ -73,11 +74,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates rule exception list items
+      summary: Create rule exception list items
       tags:
         - Security Exceptions API
   /api/exception_lists:
     delete:
+      description: Delete an exception list using the `id` or `list_id` field.
       operationId: DeleteExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -137,10 +139,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list
+      summary: Delete an exception list
       tags:
         - Security Exceptions API
     get:
+      description: Get the details of an exception list using the `id` or `list_id` field.
       operationId: ReadExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -200,10 +203,23 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list using its `id` or `list_id` field
+      summary: Get exception list details
       tags:
         - Security Exceptions API
     post:
+      description: >
+        An exception list groups exception items and can be associated with
+        detection rules. You can assign detection rules with multiple exception
+        lists.
+
+        > info
+
+        > All exception items added to the same list are evaluated using `OR`
+        logic. That is, if any of the items in a list evaluate to `true`, the
+        exception prevents the rule from generating an alert. Likewise, `OR`
+        logic is used for evaluating exceptions when more than one exception
+        list is assigned to a rule. To use the `AND` operator, you can define
+        multiple clauses (`entries`) in a single exception item.
       operationId: CreateExceptionList
       requestBody:
         content:
@@ -277,10 +293,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list
+      summary: Create an exception list
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list using the `id` or `list_id` field.
       operationId: UpdateExceptionList
       requestBody:
         content:
@@ -357,11 +374,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list
+      summary: Update an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_duplicate:
     post:
+      description: Duplicate an existing exception list.
       operationId: DuplicateExceptionList
       parameters:
         - description: Exception list's human identifier
@@ -426,12 +444,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Duplicates an exception list
+      summary: Duplicate an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_export:
     post:
-      description: Exports an exception list and its associated items to an .ndjson file
+      description: Export an exception list and its associated items to an NDJSON file.
       operationId: ExportExceptionList
       parameters:
         - description: Exception list's identifier
@@ -506,11 +524,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Exports an exception list
+      summary: Export an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_find:
     get:
+      description: Get a list of all exception lists.
       operationId: FindExceptionLists
       parameters:
         - description: >
@@ -626,12 +645,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception lists
+      summary: Get exception lists
       tags:
         - Security Exceptions API
   /api/exception_lists/_import:
     post:
-      description: Imports an exception list and associated items
+      description: Import an exception list and its associated items from an NDJSON file.
       operationId: ImportExceptionList
       parameters:
         - description: >
@@ -742,11 +761,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Imports an exception list
+      summary: Import an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/items:
     delete:
+      description: Delete an exception list item using the `id` or `item_id` field.
       operationId: DeleteExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -806,10 +826,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list item
+      summary: Delete an exception list item
       tags:
         - Security Exceptions API
     get:
+      description: >-
+        Get the details of an exception list item using the `id` or `item_id`
+        field.
       operationId: ReadExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -869,10 +892,17 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Gets an exception list item
+      summary: Get an exception list item
       tags:
         - Security Exceptions API
     post:
+      description: >
+        Create an exception item and associate it with the specified exception
+        list.
+
+        > info
+
+        > Before creating exception items, you must create an exception list.
       operationId: CreateExceptionListItem
       requestBody:
         content:
@@ -956,10 +986,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list item
+      summary: Create an exception list item
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list item using the `id` or `item_id` field.
       operationId: UpdateExceptionListItem
       requestBody:
         content:
@@ -1047,11 +1078,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list item
+      summary: Update an exception list item
       tags:
         - Security Exceptions API
   /api/exception_lists/items/_find:
     get:
+      description: Get a list of all exception list items in the specified list.
       operationId: FindExceptionListItems
       parameters:
         - description: List's id
@@ -1183,11 +1215,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception list items
+      summary: Get exception list items
       tags:
         - Security Exceptions API
   /api/exception_lists/summary:
     get:
+      description: Get a summary of the specified exception list.
       operationId: ReadExceptionListSummary
       parameters:
         - description: Exception list's identifier generated upon creation
@@ -1266,11 +1299,24 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list summary
+      summary: Get an exception list summary
       tags:
         - Security Exceptions API
   /api/exceptions/shared:
     post:
+      description: >
+        An exception list groups exception items and can be associated with
+        detection rules. A shared exception list can apply to multiple detection
+        rules.
+
+        > info
+
+        > All exception items added to the same list are evaluated using `OR`
+        logic. That is, if any of the items in a list evaluate to `true`, the
+        exception prevents the rule from generating an alert. Likewise, `OR`
+        logic is used for evaluating exceptions when more than one exception
+        list is assigned to a rule. To use the `AND` operator, you can define
+        multiple clauses (`entries`) in a single exception item.
       operationId: CreateSharedExceptionList
       requestBody:
         content:
@@ -1325,7 +1371,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates a shared exception list
+      summary: Create a shared exception list
       tags:
         - Security Exceptions API
 components:

packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml

@@ -16,6 +16,7 @@ servers:
 paths:
   '/api/detection_engine/rules/{id}/exceptions':
     post:
+      description: Create exception items that apply to a single detection rule.
       operationId: CreateRuleExceptionListItems
       parameters:
         - description: Detection rule's identifier
@@ -73,11 +74,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates rule exception list items
+      summary: Create rule exception list items
       tags:
         - Security Exceptions API
   /api/exception_lists:
     delete:
+      description: Delete an exception list using the `id` or `list_id` field.
       operationId: DeleteExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -137,10 +139,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list
+      summary: Delete an exception list
       tags:
         - Security Exceptions API
     get:
+      description: Get the details of an exception list using the `id` or `list_id` field.
       operationId: ReadExceptionList
       parameters:
         - description: Either `id` or `list_id` must be specified
@@ -200,10 +203,23 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list using its `id` or `list_id` field
+      summary: Get exception list details
       tags:
         - Security Exceptions API
     post:
+      description: >
+        An exception list groups exception items and can be associated with
+        detection rules. You can assign detection rules with multiple exception
+        lists.
+
+        > info
+
+        > All exception items added to the same list are evaluated using `OR`
+        logic. That is, if any of the items in a list evaluate to `true`, the
+        exception prevents the rule from generating an alert. Likewise, `OR`
+        logic is used for evaluating exceptions when more than one exception
+        list is assigned to a rule. To use the `AND` operator, you can define
+        multiple clauses (`entries`) in a single exception item.
       operationId: CreateExceptionList
       requestBody:
         content:
@@ -277,10 +293,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list
+      summary: Create an exception list
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list using the `id` or `list_id` field.
       operationId: UpdateExceptionList
       requestBody:
         content:
@@ -357,11 +374,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list
+      summary: Update an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_duplicate:
     post:
+      description: Duplicate an existing exception list.
       operationId: DuplicateExceptionList
       parameters:
         - description: Exception list's human identifier
@@ -426,12 +444,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Duplicates an exception list
+      summary: Duplicate an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_export:
     post:
-      description: Exports an exception list and its associated items to an .ndjson file
+      description: Export an exception list and its associated items to an NDJSON file.
       operationId: ExportExceptionList
       parameters:
         - description: Exception list's identifier
@@ -506,11 +524,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Exports an exception list
+      summary: Export an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/_find:
     get:
+      description: Get a list of all exception lists.
       operationId: FindExceptionLists
       parameters:
         - description: >
@@ -626,12 +645,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception lists
+      summary: Get exception lists
       tags:
         - Security Exceptions API
   /api/exception_lists/_import:
     post:
-      description: Imports an exception list and associated items
+      description: Import an exception list and its associated items from an NDJSON file.
       operationId: ImportExceptionList
       parameters:
         - description: >
@@ -742,11 +761,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Imports an exception list
+      summary: Import an exception list
       tags:
         - Security Exceptions API
   /api/exception_lists/items:
     delete:
+      description: Delete an exception list item using the `id` or `item_id` field.
       operationId: DeleteExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -806,10 +826,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Deletes an exception list item
+      summary: Delete an exception list item
       tags:
         - Security Exceptions API
     get:
+      description: >-
+        Get the details of an exception list item using the `id` or `item_id`
+        field.
       operationId: ReadExceptionListItem
       parameters:
         - description: Either `id` or `item_id` must be specified
@@ -869,10 +892,17 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Gets an exception list item
+      summary: Get an exception list item
       tags:
         - Security Exceptions API
     post:
+      description: >
+        Create an exception item and associate it with the specified exception
+        list.
+
+        > info
+
+        > Before creating exception items, you must create an exception list.
       operationId: CreateExceptionListItem
       requestBody:
         content:
@@ -956,10 +986,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates an exception list item
+      summary: Create an exception list item
       tags:
         - Security Exceptions API
     put:
+      description: Update an exception list item using the `id` or `item_id` field.
       operationId: UpdateExceptionListItem
       requestBody:
         content:
@@ -1047,11 +1078,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Updates an exception list item
+      summary: Update an exception list item
       tags:
         - Security Exceptions API
   /api/exception_lists/items/_find:
     get:
+      description: Get a list of all exception list items in the specified list.
       operationId: FindExceptionListItems
       parameters:
         - description: List's id
@@ -1183,11 +1215,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Finds exception list items
+      summary: Get exception list items
       tags:
         - Security Exceptions API
   /api/exception_lists/summary:
     get:
+      description: Get a summary of the specified exception list.
       operationId: ReadExceptionListSummary
       parameters:
         - description: Exception list's identifier generated upon creation
@@ -1266,11 +1299,24 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Retrieves an exception list summary
+      summary: Get an exception list summary
       tags:
         - Security Exceptions API
   /api/exceptions/shared:
     post:
+      description: >
+        An exception list groups exception items and can be associated with
+        detection rules. A shared exception list can apply to multiple detection
+        rules.
+
+        > info
+
+        > All exception items added to the same list are evaluated using `OR`
+        logic. That is, if any of the items in a list evaluate to `true`, the
+        exception prevents the rule from generating an alert. Likewise, `OR`
+        logic is used for evaluating exceptions when more than one exception
+        list is assigned to a rule. To use the `AND` operator, you can define
+        multiple clauses (`entries`) in a single exception item.
       operationId: CreateSharedExceptionList
       requestBody:
         content:
@@ -1325,7 +1371,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/SiemErrorResponse'
           description: Internal server error response
-      summary: Creates a shared exception list
+      summary: Create a shared exception list
       tags:
         - Security Exceptions API
 components:

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

@@ -46,6 +46,12 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
   const supertest = getService('supertest');
 
   return {
+    /**
+      * An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists.
+> info
+> All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
+
+      */
     createExceptionList(props: CreateExceptionListProps, kibanaSpace: string = 'default') {
       return supertest
         .post(routeWithNamespace('/api/exception_lists', kibanaSpace))
@@ -54,6 +60,12 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+      * Create an exception item and associate it with the specified exception list.
+> info
+> Before creating exception items, you must create an exception list.
+
+      */
     createExceptionListItem(props: CreateExceptionListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .post(routeWithNamespace('/api/exception_lists/items', kibanaSpace))
@@ -62,6 +74,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+     * Create exception items that apply to a single detection rule.
+     */
     createRuleExceptionListItems(
       props: CreateRuleExceptionListItemsProps,
       kibanaSpace: string = 'default'
@@ -78,6 +93,12 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+      * An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules.
+> info
+> All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item.
+
+      */
     createSharedExceptionList(
       props: CreateSharedExceptionListProps,
       kibanaSpace: string = 'default'
@@ -89,6 +110,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+     * Delete an exception list using the `id` or `list_id` field.
+     */
     deleteExceptionList(props: DeleteExceptionListProps, kibanaSpace: string = 'default') {
       return supertest
         .delete(routeWithNamespace('/api/exception_lists', kibanaSpace))
@@ -97,6 +121,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Delete an exception list item using the `id` or `item_id` field.
+     */
     deleteExceptionListItem(props: DeleteExceptionListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .delete(routeWithNamespace('/api/exception_lists/items', kibanaSpace))
@@ -105,6 +132,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Duplicate an existing exception list.
+     */
     duplicateExceptionList(props: DuplicateExceptionListProps, kibanaSpace: string = 'default') {
       return supertest
         .post(routeWithNamespace('/api/exception_lists/_duplicate', kibanaSpace))
@@ -114,7 +144,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .query(props.query);
     },
     /**
-     * Exports an exception list and its associated items to an .ndjson file
+     * Export an exception list and its associated items to an NDJSON file.
      */
     exportExceptionList(props: ExportExceptionListProps, kibanaSpace: string = 'default') {
       return supertest
@@ -124,6 +154,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get a list of all exception list items in the specified list.
+     */
     findExceptionListItems(props: FindExceptionListItemsProps, kibanaSpace: string = 'default') {
       return supertest
         .get(routeWithNamespace('/api/exception_lists/items/_find', kibanaSpace))
@@ -132,6 +165,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get a list of all exception lists.
+     */
     findExceptionLists(props: FindExceptionListsProps, kibanaSpace: string = 'default') {
       return supertest
         .get(routeWithNamespace('/api/exception_lists/_find', kibanaSpace))
@@ -141,7 +177,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .query(props.query);
     },
     /**
-     * Imports an exception list and associated items
+     * Import an exception list and its associated items from an NDJSON file.
      */
     importExceptionList(props: ImportExceptionListProps, kibanaSpace: string = 'default') {
       return supertest
@@ -151,6 +187,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get the details of an exception list using the `id` or `list_id` field.
+     */
     readExceptionList(props: ReadExceptionListProps, kibanaSpace: string = 'default') {
       return supertest
         .get(routeWithNamespace('/api/exception_lists', kibanaSpace))
@@ -159,6 +198,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get the details of an exception list item using the `id` or `item_id` field.
+     */
     readExceptionListItem(props: ReadExceptionListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .get(routeWithNamespace('/api/exception_lists/items', kibanaSpace))
@@ -167,6 +209,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Get a summary of the specified exception list.
+     */
     readExceptionListSummary(
       props: ReadExceptionListSummaryProps,
       kibanaSpace: string = 'default'
@@ -178,6 +223,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .query(props.query);
     },
+    /**
+     * Update an exception list using the `id` or `list_id` field.
+     */
     updateExceptionList(props: UpdateExceptionListProps, kibanaSpace: string = 'default') {
       return supertest
         .put(routeWithNamespace('/api/exception_lists', kibanaSpace))
@@ -186,6 +234,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
         .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
         .send(props.body as object);
     },
+    /**
+     * Update an exception list item using the `id` or `item_id` field.
+     */
     updateExceptionListItem(props: UpdateExceptionListItemProps, kibanaSpace: string = 'default') {
       return supertest
         .put(routeWithNamespace('/api/exception_lists/items', kibanaSpace))