From bd844177233e527bf348a355274bbcf647f82bec Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Mon, 8 Jan 2024 22:41:51 -0500
Subject: [PATCH] [8.12] [Request] ESS docs for "Alert User Assignment" API 
 (backport #4475) (#4566)

* First draft

* Moved docs to correct location

* Removed space

* Update title

* Minor change

* request schema

* Update docs/detections/api/rules/signals-api-overview.asciidoc

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>

* Update docs/detections/api/rules/signals-api-overview.asciidoc

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>

* Update docs/detections/api/rules/signals-api-overview.asciidoc

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>

* Update docs/detections/api/rules/signals-api-overview.asciidoc

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>

* Styled text

---------

Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com>
(cherry picked from commit 474ac29506574e314b5246c87cc94cb6c822b974)

Co-authored-by: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com>
---
 .../api/rules/signals-api-overview.asciidoc   | 88 ++++++++++++++++++-
 1 file changed, 85 insertions(+), 3 deletions(-)

diff --git a/docs/detections/api/rules/signals-api-overview.asciidoc b/docs/detections/api/rules/signals-api-overview.asciidoc
index 086cabe3b7..bd4b95eba6 100644
--- a/docs/detections/api/rules/signals-api-overview.asciidoc
+++ b/docs/detections/api/rules/signals-api-overview.asciidoc
@@ -272,8 +272,8 @@ A JSON object with the `tags` and `ids` fields:
 
 Properties of the `tags` object:
 
-* tags_to_add: (Required, string[]) Array of tags you want to add.
-* tags_to_remove: (Required, string[]) Array of tags you want to remove.
+* `tags_to_add`: (Required, string[]) Array of tags you want to add.
+* `tags_to_remove`: (Required, string[]) Array of tags you want to remove.
 
 NOTE: You cannot add and remove the same alert tag. 
 
@@ -353,4 +353,86 @@ Example response:
         }
     ]
 }
---------------------------------------------------
\ No newline at end of file
+--------------------------------------------------
+
+==== Assign or unassign users from alerts
+
+Allows you to assign and unassign users from alerts. 
+
+===== Request URL
+
+`POST <kibana host>:<port>/api/detection_engine/signals/assignees`
+
+===== Request body
+
+A JSON object with the `assignees` and `ids` fields:
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`assignees` |Object[] a|An array of unique identifiers (UIDs) for user profiles. Properties of the `assignees` object:
+
+* `add`: (Required, string[]) An array of assignees you want to add.
+* `remove`: (Required, string[]) An array of assignees you want to unassign. 
+
+NOTE: You cannot add and remove the same assignee. 
+|Yes
+
+|`ids` |String[] |An array of alert IDs. |Yes
+
+|==============================================
+
+====== Example request
+
+Assigns and unassigns users to alerts:
+
+[source,console]
+--------------------------------------------------
+POST api/detection_engine/signals/assignees
+
+{
+  "assignees": {
+    "add": ["u_o4kzon2tUP0u189YjKVT0rTR_HBOED3JmyLLE6MrulY_0"],
+    "remove": ["u_P4HW8xg4_xRVI7Oa-i6Ys1Gxe7k3jqZteAeZe6ZctEc_0"]
+  },
+  "ids": [
+    "854f5eceeec1b4cd5495ad18c4259d6e5631a6677bc10c033edb318397d45459",
+    "00968e97805854d0aa356968cad971d5184cdf91ebd458720c5b4099f4a5229a"
+  ]
+}
+--------------------------------------------------
+// KIBANA
+
+===== Response code
+
+`200`::
+    Indicates a successful call.
+
+====== Response payload
+
+A JSON object containing the number of updated alerts.
+
+Example response:
+
+[source,json]
+--------------------------------------------------
+{
+  "took": 67,
+  "timed_out": false,
+  "total": 2,
+  "updated": 2,
+  "deleted": 0,
+  "batches": 1,
+  "version_conflicts": 0,
+  "noops": 0,
+  "retries": {
+    "bulk": 0,
+    "search": 0
+  },
+  "throttled_millis": 0,
+  "requests_per_second": -1,
+  "throttled_until_millis": 0,
+  "failures": []
+}
+--------------------------------------------------