[Entity Analytics] Add Asset Criticality public API docs (#5660)

* add asset criticality API docs

* fix crititcality_level

* remove unused schema

* Editorial review

* change list API to GET

* Update docs/advanced-entity-analytics/api/asset-criticality-api-list.asciidoc

* Update asset-criticality-api-bulk-upsert.asciidoc

---------

Co-authored-by: natasha-moore-elastic <[email protected]>
Co-authored-by: natasha-moore-elastic <[email protected]>

docs/advanced-entity-analytics/api/asset-criticality-api-bulk-upsert.asciidoc

@@ -0,0 +1,78 @@
+[[asset-criticality-api-bulk-upsert]]
+=== Bulk upsert (create or update) asset criticality records
+
+Create or update asset criticality records for multiple entities.
+
+If asset criticality records already exist for the entities specified in the request, this API overwrites those records with the specified values.
+
+If asset criticality records don't exist for the specified entities, new records are created.
+
+==== Request URL
+
+`POST <kibana host>:<port>/api/asset_criticality/bulk`
+
+==== Request body
+
+A JSON object defining the asset criticality records.
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+|`records` |Array |Array of asset criticality records to be created or updated. The maximum number of records is 1000.
+|Yes
+|`records.id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`.
+|Yes
+|`records.id_value` |String |The ID (host name or user name) of the entity specified in the `records.id_field` field.
+|Yes
+|`records.criticality_level` |String a|The asset criticality level to assign, which must be one of the following:
+
+* `low_impact`
+* `medium_impact`
+* `high_impact`
+* `extreme_impact`
+
+For example, you can assign `extreme_impact` to business-critical entities, or `low_impact` to entities that pose minimal risk to your security posture.
+|Yes
+|==============================================
+
+===== Example requests
+
+[source,console]
+--------------------------------------------------
+POST /api/asset_criticality/bulk
+{
+  "records": [
+    {
+      "id_field": "host.name",
+      "id_value": "my_host",
+      "criticality_level": "medium_impact"
+    },
+    {
+      "id_field": "host.name",
+      "id_value": "my_other_host",
+      "criticality_level": "low_impact"
+    }
+  ]
+}
+--------------------------------------------------
+
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+==== Example response
+
+Successful response
+
+[source,json]
+--------------------------------------------------
+{
+  "errors": [],
+  "stats": {
+    "successful": 2,
+    "failed": 0,
+    "total": 2
+  }
+}
+--------------------------------------------------

docs/advanced-entity-analytics/api/asset-criticality-api-delete.asciidoc

@@ -0,0 +1,64 @@
+[[delete-criticality-api-delete]]
+=== Delete asset criticality record
+
+Delete a single asset criticality record by ID field and ID value.
+
+==== Request URL
+
+`DELETE <kibana host>:<port>/api/asset_criticality`
+
+==== URL query parameters
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`.
+|Yes
+|`id_value` |String |The ID (host name or user name) of the entity specified in the `id_field` field.
+|Yes
+
+|==============================================
+
+===== Example requests
+
+[source,console]
+--------------------------------------------------
+DELETE /api/asset_criticality?id_field=host.name&id_value=my_host
+
+--------------------------------------------------
+
+==== Response code
+
+`200`::
+    Indicates a successful call. Check the response body to see if the record was deleted.
+
+==== Example responses
+
+*Example 1*
+
+If the record was deleted.
+
+[source,json]
+--------------------------------------------------
+{
+  "deleted": true,
+  "record": {
+    "id_field": "host.name",
+    "id_value": "my_host",
+    "criticality_level": "medium_impact",
+    "@timestamp": "2024-08-05T09:42:11.240Z"
+  }
+}
+--------------------------------------------------
+
+*Example 2*
+
+If the record was not found and could not be deleted.
+
+[source,json]
+--------------------------------------------------
+{
+  "deleted": false
+}
+--------------------------------------------------

docs/advanced-entity-analytics/api/asset-criticality-api-get.asciidoc

@@ -0,0 +1,48 @@
+[[asset-criticality-api-get]]
+=== Get asset criticality record
+
+Retrieve a single asset criticality record by ID field and ID value.
+
+==== Request URL
+
+`GET <kibana host>:<port>/api/asset_criticality`
+
+==== URL query parameters
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`.
+|Yes
+|`id_value` |String |The ID (host name or user name) of the entity specified in the `id_field` field.
+|Yes
+
+|==============================================
+
+===== Example requests
+
+[source,console]
+--------------------------------------------------
+GET /api/asset_criticality?id_field=host.name&id_value=my_host
+
+--------------------------------------------------
+
+==== Response code
+
+`200`::
+    Indicates a successful call.
+`404`::
+    Indicates the criticality record was not found.
+
+==== Example response
+
+[source,json]
+--------------------------------------------------
+{
+  "id_field": "host.name",
+  "id_value": "my_host",
+  "criticality_level": "high_impact",
+  "@timestamp": "2024-08-02T11:15:34.290Z"
+}
+--------------------------------------------------

docs/advanced-entity-analytics/api/asset-criticality-api-index.asciidoc

@@ -0,0 +1,11 @@
+include::asset-criticality-api-overview.asciidoc[]
+
+include::asset-criticality-api-upsert.asciidoc[]
+
+include::asset-criticality-api-bulk-upsert.asciidoc[]
+
+include::asset-criticality-api-get.asciidoc[]
+
+include::asset-criticality-api-list.asciidoc[]
+
+include::asset-criticality-api-delete.asciidoc[]

docs/advanced-entity-analytics/api/asset-criticality-api-list.asciidoc

@@ -0,0 +1,72 @@
+[[asset-criticality-api-list]]
+=== List asset criticality records
+
+Retrieve a list of asset criticality records.
+
+Use the query parameters to filter and sort the results as needed. By default, the first page is returned, with 10 results per page.
+
+==== Request URL
+
+`GET <kibana host>:<port>/api/asset_criticality/list`
+
+==== URL query parameters
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`sort_field` |String a|The field to sort the results by, which must be one of the following:
+
+* `id_value`
+* `id_field`
+* `criticality_level`
+* `@timestamp`
+
+|No
+|`sort_direction` |String |The order to sort the results in, which must be either `asc` or `desc`.
+|No
+|`page` |Number | The page number to return, which must be at least 1. Defaults to `1`.
+|No
+|`per_page` |Number |The number of results to return per page, which must be between 1 and 1000. Defaults to `10`. 
+|No
+|`kuery` |String a|A KQL query to filter results by, for example `criticality_level:low_impact OR criticality_level:medium_impact`
+|No
+|==============================================
+
+===== Example requests
+
+[source,console]
+--------------------------------------------------
+GET api/asset_criticality/list?kuery=criticality_level:high_impact%20OR%20criticality_level:medium_impact
+
+--------------------------------------------------
+
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+==== Example response
+
+[source,json]
+--------------------------------------------------
+{
+  "records": [
+    {
+      "id_field": "host.name",
+      "id_value": "my_other_host",
+      "criticality_level": "medium_impact",
+      "@timestamp": "2024-08-02T14:40:35.705Z"
+    },
+    {
+      "id_field": "host.name",
+      "id_value": "my_host",
+      "criticality_level": "high_impact",
+      "@timestamp": "2024-08-02T11:15:34.290Z"
+    }
+  ],
+  "total": 2,
+  "page": 1,
+  "per_page": 10
+}
+--------------------------------------------------

docs/advanced-entity-analytics/api/asset-criticality-api-overview.asciidoc

@@ -0,0 +1,5 @@
+[[asset-criticality-api-overview]]
+[role="xpack"]
+== Asset criticality API
+
+You can manage <<asset-criticality, asset criticality>> records through the API. To use this API, you must first turn on the `securitySolution:enableAssetCriticality` <<enable-asset-criticality, advanced setting>>.

docs/advanced-entity-analytics/api/asset-criticality-api-upsert.asciidoc

@@ -0,0 +1,63 @@
+[[asset-criticality-api-upsert]]
+=== Upsert (create or update) asset criticality record
+
+Create or update an asset criticality record.
+
+If an asset criticality record already exists for the entity specified in the request, this API overwrites that record with the specified value.
+
+If an asset criticality record doesn't exist for the specified entity, a new record is created.
+
+==== Request URL
+
+`POST <kibana host>:<port>/api/asset_criticality`
+
+==== Request body
+
+A JSON object defining the asset criticality record.
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+|`id_field` |String |The field that contains the entity ID. This must be either `user.name` or `host.name`.
+|Yes
+|`id_value` |String |The ID (host name or user name) of the entity specified in the `id_field` field.
+|Yes
+|`criticality_level` |String a|The asset criticality level to assign, which must be one of the following:
+
+* `low_impact`
+* `medium_impact`
+* `high_impact`
+* `extreme_impact`
+
+For example, you can assign `extreme_impact` to business-critical entities, or `low_impact` to entities that pose minimal risk to your security posture.
+|Yes
+|==============================================
+
+===== Example requests
+
+[source,console]
+--------------------------------------------------
+POST /api/asset_criticality
+{
+  "id_field": "host.name",
+  "id_value": "my_host",
+  "criticality_level": "high_impact"
+}
+--------------------------------------------------
+
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+==== Example response
+
+[source,json]
+--------------------------------------------------
+{
+  "id_field": "host.name",
+  "id_value": "my_host",
+  "criticality_level": "high_impact",
+  "@timestamp": "2024-08-02T11:15:34.290Z"
+}
+--------------------------------------------------

docs/advanced-entity-analytics/asset-criticality.asciidoc

@@ -26,7 +26,7 @@ For example, you can assign **Extreme impact** to business-critical entities, or
 [discrete]
 == View and assign asset criticality
 
-Entities do not have a default asset criticality level. You can either assign asset criticality to your entities individually, or <<bulk-assign-asset-criticality, bulk assign>> it to multiple entities by importing a text file.
+Entities do not have a default asset criticality level. You can either assign asset criticality to your entities individually, or <<bulk-assign-asset-criticality, bulk assign>> it to multiple entities by importing a text file. Alternatively, you can assign and manage asset criticality records through the <<asset-criticality-api-overview>>.
 
 When you assign, change, or unassign an individual entity's asset criticality level, that entity's risk score is immediately recalculated.
 

docs/siem-apis.asciidoc

@@ -13,6 +13,7 @@ NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API end
 * <<lists-api-overview>>: Create source event value lists for use with rule exceptions
 * <<timeline-api-overview>>: Import and export timelines
 * <<cases-api-overview>>: Open and manage cases
+* <<asset-criticality-api-overview>>: Create and manage asset criticality records
 
 Additionally, the {kib} <<actions-api-overview, Actions API>> is partially
 documented to enable opening and updating cases in external ticketing systems.
@@ -103,5 +104,7 @@ include::cases/api/actions-api/cases-actions-api-index.asciidoc[]
 
 include::management/api/management-api-index.asciidoc[]
 
+include::advanced-entity-analytics/api/asset-criticality-api-index.asciidoc[]
+
 NOTE: For the {fleet} APIs, see the
 {fleet-guide}/fleet-api-docs.html[Fleet API Documentation].