From b5fdaf2acde56c76eb57cdec93a62e85e8a81a92 Mon Sep 17 00:00:00 2001
From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>
Date: Tue, 16 Jan 2024 18:01:55 -0600
Subject: [PATCH] Correct SA findings alerts API (#6179)

* Correct SA findings alerts API

Signed-off-by: Naarcha-AWS <naarcha@amazon.com>

* Apply suggestions from code review

Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Apply suggestions from code review

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

---------

Signed-off-by: Naarcha-AWS <naarcha@amazon.com>
Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>
Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
---
 .../api-tools/alert-finding-api.md            | 32 ++++++++++++++-----
 1 file changed, 24 insertions(+), 8 deletions(-)

diff --git a/_security-analytics/api-tools/alert-finding-api.md b/_security-analytics/api-tools/alert-finding-api.md
index 129ebf058e..a22b601b08 100644
--- a/_security-analytics/api-tools/alert-finding-api.md
+++ b/_security-analytics/api-tools/alert-finding-api.md
@@ -11,7 +11,8 @@ nav_order: 50
 The following APIs can be used for tasks related to alerts and findings.
 
 ---
-## Get Alerts
+
+## Get alerts
 
 Provides an option for retrieving alerts related to a specific detector type or detector ID.
 
@@ -21,12 +22,12 @@ You can specify the following parameters when requesting an alert.
 
 Parameter | Description 
 :--- | :---
-`detectorId` | The ID of the detector used to fetch alerts. Optional when the `detectorType` is specified. Otherwise required.
-`detectorType` | The type of detector used to fetch alerts. Optional when the `detectorId` is specified. Otherwise required.
+`detector_id` | The ID of the detector used to fetch alerts. Optional when the `detectorType` is specified. Otherwise required.
+`detectorType` | The type of detector used to fetch alerts. Optional when the `detector_Id` is specified. Otherwise required.
 `severityLevel` | Used to filter by alert severity level. Optional.
-`alertState` | Used to filter by alert state. Possible values: ACTIVE, ACKNOWLEDGED, COMPLETED, ERROR, DELETED. Optional.
+`alertState` | Used to filter by alert state. Possible values are ACTIVE, ACKNOWLEDGED, COMPLETED, ERROR, or DELETED. Optional.
 `sortString` | This field specifies which string Security Analytics uses to sort the alerts. Optional.
-`sortOrder` | The order used to sort the list of findings, either `ascending` or `descending`. Optional.
+`sortOrder` | The order used to sort the list of findings. Possible values are `asc` or `desc`. Optional.
 `missing` | A list of fields for which there are no found alias mappings. Optional.
 `size` | An optional limit for the maximum number of results returned in the response. Optional.
 `startIndex` | The pagination indicator. Optional.
@@ -83,7 +84,10 @@ State | Description
 `DELETED` | Someone deleted the detector or trigger associated with this alert while the alert was ongoing.
 
 ---
-## Acknowledge Alerts
+
+## Acknowledge alerts
+
+Sends an acknowledgement when an alert is triggered.
 
 ### Example request
 
@@ -134,9 +138,21 @@ POST /_plugins/_security_analytics/<detector_id>/_acknowledge/alerts
 ```
 
 ---
-## Get Findings
 
-The Get findings API based on detector attributes.
+## Get findings
+
+The Get findings API returns findings based on the detector attributes.
+
+### Parameters
+
+You can specify the following parameters when getting findings.
+
+Parameter | Description 
+:--- | :---
+`detector_id` | The ID of the detector used to fetch alerts. Optional when the `detectorType` is specified. Otherwise required.
+`detectorType` | The type of detector used to fetch alerts. Optional when the `detector_id` is specified. Otherwise required.
+`sortOrder` | The order used to sort the list of findings. Possible values are `asc` or `desc`. Optional.
+`size` | An optional limit for the maximum number of results returned in the response. Optional.
 
 ### Example request