Update formatting for "Modify team" API docs (#26840)
Match the format of [Modify configuration](https://fleetdm.com/docs/rest-api/rest-api#modify-configuration)
This commit is contained in:
Rachael Shaw
+293
-47
@@ -10600,53 +10600,10 @@ _Available in Fleet Premium_
|
||||
| name | string | body | The team's name. |
|
||||
| host_ids | array | body | A list of hosts that belong to the team. |
|
||||
| user_ids | array | body | A list of users on the team. |
|
||||
| webhook_settings | object | body | Webhook settings contains for the team. |
|
||||
| failing_policies_webhook | object | body | Failing policies webhook settings. |
|
||||
| enable_failing_policies_webhook | boolean | body | Whether or not the failing policies webhook is enabled. |
|
||||
| destination_url | string | body | The URL to deliver the webhook requests to. |
|
||||
| policy_ids | array | body | List of policy IDs to enable failing policies webhook. |
|
||||
| host_status_webhook | object | body | Host status webhook settings. |
|
||||
| enable_host_status_webhook | boolean | body | Whether or not the host status webhook is enabled. |
|
||||
| destination_url | string | body | The URL to deliver the webhook request to. |
|
||||
| host_percentage | integer | body | The minimum percentage of hosts that must fail to check in to Fleet in order to trigger the webhook request. |
|
||||
| days_count | integer | body | The minimum number of days that the configured `host_percentage` must fail to check in to Fleet in order to trigger the webhook request. |
|
||||
| host_batch_size | integer | body | Maximum number of hosts to batch on failing policy webhook requests. The default, 0, means no batching (all hosts failing a policy are sent on one request). |
|
||||
| integrations | object | body | Integrations settings for the team. Note that integrations referenced here must already exist globally, created by a call to [Modify configuration](#modify-configuration). |
|
||||
| jira | array | body | Jira integrations configuration. |
|
||||
| url | string | body | The URL of the Jira server to use. |
|
||||
| project_key | string | body | The project key of the Jira integration to use. Jira tickets will be created in this project. |
|
||||
| enable_failing_policies | boolean | body | Whether or not that Jira integration is enabled for failing policies. Only one failing policy automation can be enabled at a given time (enable_failing_policies_webhook and enable_failing_policies). |
|
||||
| zendesk | array | body | Zendesk integrations configuration. |
|
||||
| url | string | body | The URL of the Zendesk server to use. |
|
||||
| group_id | integer | body | The Zendesk group id to use. Zendesk tickets will be created in this group. |
|
||||
| enable_failing_policies | boolean | body | Whether or not that Zendesk integration is enabled for failing policies. Only one failing policy automation can be enabled at a given time (enable_failing_policies_webhook and enable_failing_policies). |
|
||||
| mdm | object | body | MDM settings for the team. |
|
||||
| macos_updates | object | body | macOS updates settings. |
|
||||
| minimum_version | string | body | Hosts that belong to this team and are enrolled into Fleet's MDM will be prompted to update when their OS is below this version. |
|
||||
| deadline | string | body | Hosts that belong to this team and are enrolled into Fleet's MDM will be forced to update their OS after this deadline (noon local time for hosts already on macOS 14 or above, 20:00 UTC for hosts on earlier macOS versions). |
|
||||
| ios_updates | object | body | iOS updates settings. |
|
||||
| minimum_version | string | body | Hosts that belong to this team will be prompted to update when their OS is below this version. |
|
||||
| deadline | string | body | Hosts that belong to this team will be forced to update their OS after this deadline (noon local time). |
|
||||
| ipados_updates | object | body | iPadOS updates settings. |
|
||||
| minimum_version | string | body | Hosts that belong to this team will be prompted to update when their OS is below this version. |
|
||||
| deadline | string | body | Hosts that belong to this team will be forced to update their OS after this deadline (noon local time). |
|
||||
| windows_updates | object | body | Windows updates settings. |
|
||||
| deadline_days | integer | body | Hosts that belong to this team and are enrolled into Fleet's MDM will have this number of days before updates are installed on Windows. |
|
||||
| grace_period_days | integer | body | Hosts that belong to this team and are enrolled into Fleet's MDM will have this number of days before Windows restarts to install updates. |
|
||||
| macos_settings | object | body | macOS-specific settings. |
|
||||
| custom_settings | array | body | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add macOS configuration profiles using Fleet's API, use the [Add configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#add-custom-os-setting-configuration-profile) instead. |
|
||||
| enable_disk_encryption | boolean | body | Hosts that belong to this team will have disk encryption enabled if set to true. |
|
||||
| windows_settings | object | body | Windows-specific settings. |
|
||||
| custom_settings | array | body | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add Windows configuration profiles using Fleet's API, use the [Add configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#add-custom-os-setting-configuration-profile) instead. |
|
||||
| macos_setup | object | body | Setup for automatic MDM enrollment of macOS hosts. |
|
||||
| enable_end_user_authentication | boolean | body | If set to true, end user authentication will be required during automatic MDM enrollment of new macOS hosts. Settings for your IdP provider must also be [configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula). |
|
||||
| integrations | object | body | Integration settings for this team. |
|
||||
| google_calendar | object | body | Google Calendar integration settings. |
|
||||
| enable_calendar_events | boolean | body | Whether or not calendar events are enabled for this team. |
|
||||
| webhook_url | string | body | The URL to send a request to during calendar events, to trigger auto-remediation. |
|
||||
| host_expiry_settings | object | body | Host expiry settings for the team. |
|
||||
| host_expiry_enabled | boolean | body | When enabled, allows automatic cleanup of hosts that have not communicated with Fleet in some number of days. When disabled, defaults to the global setting. |
|
||||
| host_expiry_window | integer | body | If a host has not communicated with Fleet in the specified number of days, it will be removed. |
|
||||
| webhook_settings | object | body | Webhook settings for the team. See [webhook_settings](#webhook-settings2). |
|
||||
| integrations | object | body | Integrations settings for the team. See [integrations](#integrations3) for details. Note that integrations referenced here must already exist globally, created by a call to [Modify configuration](#modify-configuration). |
|
||||
| mdm | object | body | MDM settings for the team. See [mdm](#mdm2) for details. |
|
||||
| host_expiry_settings | object | body | Host expiry settings for the team. See [host_expiry_settings](#host-expiry-settings2) for details. |
|
||||
|
||||
#### Example (transfer hosts to a team)
|
||||
|
||||
@@ -10704,6 +10661,295 @@ _Available in Fleet Premium_
|
||||
}
|
||||
```
|
||||
|
||||
#### webhook_settings
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ----- | ---------------------------------------------------------------------------------------------- |
|
||||
| failing_policies_webhook | array | See [`webhook_settings.failing_policies_webhook`](#webhook-settings-failing-policies-webhook2). |
|
||||
| host_status_webhook | array | See [`webhook_settings.host_status_webhook`](#webhook-settings-host-status-webhook2). |
|
||||
|
||||
<br/>
|
||||
|
||||
##### webhook_settings.failing_policies_webhook
|
||||
|
||||
`webhook_settings.failing_policies_webhook` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| enable_failing_policies_webhook | boolean | Whether or not the failing policies webhook is enabled. |
|
||||
| destination_url | string | The URL to deliver the webhook requests to. |
|
||||
| policy_ids | array | List of policy IDs to enable failing policies webhook. |
|
||||
| host_batch_size | integer | Maximum number of hosts to batch on failing policy webhook requests. The default, `0`, means no batching (all hosts failing a policy are sent on one request). |
|
||||
|
||||
<br/>
|
||||
|
||||
##### webhook_settings.host_status_webhook
|
||||
|
||||
`webhook_settings.host_status_webhook` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| enable_host_status_webhook | boolean | Whether or not the host status webhook is enabled. |
|
||||
| destination_url | string | The URL to deliver the webhook request to. |
|
||||
| host_percentage | integer | The minimum percentage of hosts that must fail to check in to Fleet in order to trigger the webhook request. |
|
||||
| days_count | integer | body | The minimum number of days that the configured `host_percentage` must fail to check in to Fleet in order to trigger the webhook request. |
|
||||
|
||||
<br/>
|
||||
|
||||
##### Example request body
|
||||
|
||||
```json
|
||||
{
|
||||
"webhook_settings": {
|
||||
"failing_policies_webhook":{
|
||||
"enable_failing_policies_webhook": true,
|
||||
"destination_url": "https://server.com",
|
||||
"policy_ids": [1, 2, 3],
|
||||
"host_batch_size": 1000
|
||||
},
|
||||
"host_status_webhook": {
|
||||
"enable_host_status_webhook": true,
|
||||
"destination_url": "https://server.com",
|
||||
"host_percentage": 5,
|
||||
"days_count": 7
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
#### integrations
|
||||
|
||||
| Name | Type | Description |
|
||||
|-----------------|--------|----------------------------------------------------------------------|
|
||||
| jira | array | See [`integrations.jira`](#integrations-jira2). |
|
||||
| zendesk | array | See [`integrations.zendesk`](#integrations-zendesk2). |
|
||||
| google_calendar | array | See [`integrations.google_calendar`](#integrations-google-calendar2). |
|
||||
|
||||
<br/>
|
||||
|
||||
##### integrations.jira
|
||||
|
||||
`integrations.jira` is an array of objects with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| url | string | The URL of the Jira server to use. |
|
||||
| project_key | string | The project key of the Jira integration to use. Jira tickets will be created in this project. |
|
||||
| enable_failing_policies | boolean | Whether or not that Jira integration is enabled for failing policies. Only one failing policy automation can be enabled at a given time (`enable_failing_policies_webhook` and `enable_failing_policies`). |
|
||||
|
||||
<br/>
|
||||
|
||||
##### integrations.zendesk
|
||||
|
||||
`integrations.zendesk` is an array of objects with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| url | string | The URL of the Zendesk server to use. |
|
||||
| group_id | integer | The Zendesk group ID to use. Zendesk tickets will be created in this group. |
|
||||
| enable_failing_policies | boolean | Whether or not that Zendesk integration is enabled for failing policies. Only one failing policy automation can be enabled at a given time (`enable_failing_policies_webhook` and `enable_failing_policies`). |
|
||||
|
||||
<br/>
|
||||
|
||||
##### integrations.google_calendar
|
||||
|
||||
`integrations.google_calendar` is an array of objects with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| enable_calendar_events | boolean | Whether or not calendar events are enabled for this team. |
|
||||
| webhook_url | string | The URL to send a request to during calendar events, to trigger auto-remediation. |
|
||||
|
||||
##### Example request body
|
||||
|
||||
```json
|
||||
{
|
||||
"integrations": {
|
||||
"jira": [
|
||||
{
|
||||
"enable_software_vulnerabilities": false,
|
||||
"enable_failing_poilicies": true,
|
||||
"url": "https://jiraserver.com",
|
||||
"username": "some_user",
|
||||
"api_token": "<TOKEN>",
|
||||
"project_key": "jira_project",
|
||||
}
|
||||
],
|
||||
"zendesk": [],
|
||||
"google_calendar": [
|
||||
{
|
||||
"domain": "https://domain.com",
|
||||
"api_key_json": "<API KEY JSON>"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### mdm
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| macos_updates | object | See [`mdm.macos_updates`](#mdm-macos-updates2). |
|
||||
| ios_updates | object | See [`mdm.ios_updates`](#mdm-ios-updates2). |
|
||||
| ipados_updates | object | See [`mdm.ipados_updates`](#mdm-ipados-updates2). |
|
||||
| windows_updates | object | See [`mdm.windows_updates`](#mdm-windows-updates2). |
|
||||
| macos_settings | object | See [`mdm.macos_settings`](#mdm-macos-settings2). |
|
||||
| windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings2). |
|
||||
| macos_setup | object | See [`mdm.macos_setup`](#mdm-macos-setup2). |
|
||||
|
||||
<br/>
|
||||
|
||||
##### mdm.macos_updates
|
||||
|
||||
|
||||
`mdm.macos_updates` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| minimum_version | string | Hosts that belong to this team and are enrolled into Fleet's MDM will be prompted to update when their OS is below this version. |
|
||||
| deadline | string | Hosts that belong to this team and are enrolled into Fleet's MDM will be forced to update their OS after this deadline (noon local time for hosts already on macOS 14 or above, 20:00 UTC for hosts on earlier macOS versions). |
|
||||
|
||||
<br/>
|
||||
|
||||
##### mdm.ios_updates
|
||||
|
||||
`mdm.ios_updates` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| minimum_version | string | Hosts that belong to this team will be prompted to update when their OS is below this version. |
|
||||
| deadline | string | Hosts that belong to this team will be forced to update their OS after this deadline (noon local time). |
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
##### mdm.ipados_updates
|
||||
|
||||
`mdm.ipados_updates` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| minimum_version | string | Hosts that belong to this team will be prompted to update when their OS is below this version. |
|
||||
| deadline | string | Hosts that belong to this team will be forced to update their OS after this deadline (noon local time). |
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
##### mdm.windows_updates
|
||||
|
||||
`mdm.windows_updates` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| deadline_days | integer | Hosts that belong to this team and are enrolled into Fleet's MDM will have this number of days before updates are installed on Windows. |
|
||||
| grace_period_days | integer | Hosts that belong to this team and are enrolled into Fleet's MDM will have this number of days before Windows restarts to install updates. |
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
##### mdm.macos_settings
|
||||
|
||||
`mdm.macos_settings` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| enable_disk_encryption | boolean | Hosts that belong to this team will have disk encryption enabled if set to true. |
|
||||
| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add macOS configuration profiles using Fleet's API, use the [Add configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#add-custom-os-setting-configuration-profile) instead. |
|
||||
|
||||
<br/>
|
||||
|
||||
##### mdm.windows_settings
|
||||
|
||||
`mdm.windows_settings` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add Windows configuration profiles using Fleet's API, use the [Add configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#add-custom-os-setting-configuration-profile) instead. |
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
##### mdm.macos_setup
|
||||
|
||||
|
||||
`mdm.macos_setup` is an object with the following structure:
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| enable_end_user_authentication | boolean | If set to true, end user authentication will be required during automatic MDM enrollment of new macOS hosts. Settings for your IdP provider must also be [configured](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula). |
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
##### Example request body
|
||||
|
||||
```json
|
||||
{
|
||||
"mdm": {
|
||||
"macos_updates": {
|
||||
"minimum_version": "12.3.1",
|
||||
"deadline": "2025-04-01"
|
||||
},
|
||||
"ios_updates": {
|
||||
"minimum_version": "18.3.1",
|
||||
"deadline": "2025-04-01"
|
||||
},
|
||||
"windows_updates": {
|
||||
"deadline_days": 5,
|
||||
"grace_period_days": 1
|
||||
},
|
||||
"macos_settings": {
|
||||
"custom_settings": [
|
||||
{
|
||||
"path": "path/to/profile1.mobileconfig",
|
||||
"labels": ["Label 1", "Label 2"]
|
||||
},
|
||||
{
|
||||
"path": "path/to/profile2.json",
|
||||
"labels": ["Label 3", "Label 4"]
|
||||
},
|
||||
]
|
||||
},
|
||||
"windows_settings": {
|
||||
"custom_settings": [
|
||||
{
|
||||
"path": "path/to/profile3.xml",
|
||||
"labels": ["Label 1", "Label 2"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"macos_setup": {
|
||||
"enable_end_user_authentication": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### host_expiry_settings
|
||||
|
||||
| Name | Type | Description |
|
||||
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| host_expiry_enabled | boolean | When enabled, allows automatic cleanup of hosts that have not communicated with Fleet in some number of days. When disabled, defaults to the global setting. |
|
||||
| host_expiry_window | integer | If a host has not communicated with Fleet in the specified number of days, it will be removed. |
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
##### Example request body
|
||||
|
||||
```json
|
||||
{
|
||||
"host_expiry_settings": {
|
||||
"host_expiry_enabled": true,
|
||||
"host_expiry_window": 7
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Add users to a team
|
||||
|
||||
_Available in Fleet Premium_
|
||||
|
||||
Reference in New Issue
Block a user