ENT-4244: Added the Host cleanup API documentation & updated Settings api fields

content/api/enterprise-api-ref/host-cleanup.markdown

@@ -0,0 +1,82 @@
+---
+layout: default
+title: Host cleanup API
+---
+
+The Host cleanup API removes hosts from the hub based on multiple
+criteria configured in the hub settings.
+
+## Run hosts cleanup
+
+Runs all enabled cleanup stages sequentially and returns statistics for each stage.
+
+**URI:** https://hub.cfengine.com/api/host-cleanup
+
+**Method:** POST
+
+**Prerequisites:**
+
+Hosts cleanup is configured through the [hub settings][Host cleanup API#Settings]
+
+This endpoint is not available on a [federated reporting][Federated reporting] superhub.
+
+**Example request (curl):**
+
+```console
+curl --user <username>:<password> \
+  -X POST \
+  https://hub.cfengine.com/api/host-cleanup
+```
+
+**Example response:**
+
+```
+HTTP 200 OK
+{
+  "deletedHostsCleanup": {
+    "found": 0,
+    "permanentlyDeleted": 0,
+    "failed": 0
+  },
+  "duplicateHostnameHostsCleanup": {
+    "found": 0,
+    "softDeleted": 0,
+    "permanentlyDeleted": 0,
+    "failed": 0
+  },
+  "duplicateIpHostsCleanup": {
+    "found": 1,
+    "softDeleted": 1,
+    "permanentlyDeleted": 0,
+    "failed": 0
+  },
+  "groupHostsCleanup": {
+    "found": 0,
+    "softDeleted": 0,
+    "permanentlyDeleted": 0,
+    "failed": 0
+  },
+  "InactiveHostsCleanup": {
+    "found": 0,
+    "softDeleted": 0,
+    "permanentlyDeleted": 0,
+    "failed": 0
+  }
+}
+```
+
+Each stage runs independently. If a stage fails, an `error` field with the error message
+is returned in place of the counters and the remaining stages still run. A maximum of
+1000 hosts is processed per stage per call.
+
+**Responses:**
+
+| HTTP response code | Description                                          |
+| ------------------ | ---------------------------------------------------- |
+| 200 OK             | Cleanup ran; the body contains per-stage statistics. |
+| 403 Forbidden      | Endpoint called on a federated reporting superhub.   |
+
+## Settings
+
+The behavior of each stage is controlled by the settings keys, managed
+through the [Status and settings REST API][Status and settings REST API#Update settings].

content/api/enterprise-api-ref/status-settings.markdown

@@ -147,6 +147,27 @@ administrator.
 - **passwordExpirationAfterResetHours** _(integer)_
   Specifies the number of hours after which a password must expire following a reset.
   Default value: `48`
+- **disableAI** _(boolean)_
+  Disables all AI features, including the [AI chat][AI chat API] endpoint.
+  Default value: `false`
+- **allowLlmViewAccessToAttributesNames** _(boolean)_
+  Allows the LLM used by the [AI chat][AI chat API] to receive the names of inventory attributes when generating SQL queries. When `false`, the AI chat operates without knowledge of attribute names defined on the hub.
+  Default value: `false`
+- **deletedHostsCleanup** _(object)_
+  Configuration for the deleted-hosts stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "days": integer }`. Deleted hosts older than `days` are permanently removed when enabled.
+  Default value: `{ "enabled": false, "days": 90 }`
+- **duplicateHostnameHostsCleanup** _(object)_
+  Configuration for the duplicate-hostname stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "completelyClear": boolean }`. When `completelyClear` is `true`, deleted duplicates are also permanently removed in the same run.
+  Default value: `{ "enabled": false, "completelyClear": false }`
+- **duplicateIpHostsCleanup** _(object)_
+  Configuration for the duplicate-IP stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "completelyClear": boolean }`.
+  Default value: `{ "enabled": false, "completelyClear": false }`
+- **groupHostsCleanup** _(object)_
+  Configuration for the group stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "groupId": integer, "completelyClear": boolean }`. Every host in the given shared group is deleted when enabled.
+  Default value: `{ "enabled": false, "groupId": "", "completelyClear": false }`
+- **inactiveHostsCleanup** _(object)_
+  Configuration for the inactivity stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "days": integer, "completelyClear": boolean }`. Hosts that have not reported in for `days` days are deleted when enabled.
+  Default value: `{ "enabled": false, "days": 30, "completelyClear": false }`
 
 **Example Request Body:**
 
@@ -161,7 +182,14 @@ administrator.
   "minPasswordLength": 12,
   "passwordComplexity": 4,
   "passwordExpirationAfterResetHours": 24,
-  "enforce2FA": true
+  "enforce2FA": true,
+  "disableAI": false,
+  "allowLlmViewAccessToAttributesNames": true,
+  "deletedHostsCleanup": { "enabled": true, "days": 90 },
+  "duplicateHostnameHostsCleanup": { "enabled": true, "completelyClear": false },
+  "duplicateIpHostsCleanup": { "enabled": false, "completelyClear": false },
+  "groupHostsCleanup": { "enabled": false, "groupId": 12, "completelyClear": false },
+  "inactiveHostsCleanup": { "enabled": true, "days": 30, "completelyClear": true }
 }
 ```