[8.17] Improves Exceptions API docs content (#193040)

oas_docs/output/kibana.yaml

@@ -9138,6 +9138,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
@@ -9195,7 +9196,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:
@@ -11221,6 +11222,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
@@ -11280,10 +11282,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
@@ -11343,10 +11346,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:
@@ -11420,10 +11427,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:
@@ -11500,11 +11508,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
@@ -11567,12 +11576,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
@@ -11643,11 +11652,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: |
@@ -11755,12 +11765,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: |
@@ -11864,11 +11874,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
@@ -11928,10 +11939,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
@@ -11991,10 +12003,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:
@@ -12078,10 +12094,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:
@@ -12169,11 +12186,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
@@ -12301,11 +12319,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
@@ -12384,11 +12403,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:
@@ -12443,7 +12466,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: