[Request] ESS docs for "Alert User Assignment" API (#4475)

* 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 <[email protected]> * Update docs/detections/api/rules/signals-api-overview.asciidoc Co-authored-by: natasha-moore-elastic <[email protected]> * Update docs/detections/api/rules/signals-api-overview.asciidoc Co-authored-by: natasha-moore-elastic <[email protected]> * Update docs/detections/api/rules/signals-api-overview.asciidoc Co-authored-by: natasha-moore-elastic <[email protected]> * Styled text --------- Co-authored-by: natasha-moore-elastic <[email protected]>
elastic · Jan 4, 2024 · 474ac29 · 474ac29
1 parent b930aa6
commit 474ac29
Showing 1 changed file with 85 additions and 3 deletions.
diff --git 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:
         }
     ]
 }
---------------------------------------------------
+--------------------------------------------------
+
+==== 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": []
+}
+--------------------------------------------------