Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity

API docs: Combine policies and team policies (#27167)

Browse Source 
Document all policies API endpoints under "Policies" instead of having 2
separate sections:

![Screenshot 2025-03-14 at 4 51
44 PM](https://github.com/user-attachments/assets/96546c23-dea9-41cd-8ef9-ad692a6667fb)


Also renamed "Remove policy" to "Delete policy" to make language more
consistent w/ other endpoints.
This commit is contained in:
Rachael Shaw
2025-03-14 16:54:03 -05:00
committed by GitHub
parent 3ed4bc6fe4
commit 3679471a99
1 changed files with 289 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REST API/rest-api.md
+289 -269
View File
@@ -6581,11 +6581,17 @@ None.
## Policies
- [List policies](#list-policies)
- [List team policies](#list-team-policies)
- [Count policies](#count-policies)
- [Count team policies](#count-team-policies)
- [Get policy by ID](#get-policy-by-id)
- [Get team policy by ID](#get-team-policy-by-id)
- [Add policy](#add-policy)
- [Remove policies](#remove-policies)
- [Add team policy](#add-team-policy)
- [Delete policies](#delete-policies)
- [Delete team policies](#delete-team-policies)
- [Edit policy](#edit-policy)
- [Edit team policy](#edit-team-policy)
- [Reset automations for all hosts failing policies](#reset-automations-for-all-hosts-failing-policies)
Policies are yes or no questions you can ask about your hosts.
@@ -6662,276 +6668,10 @@ For example, a policy might ask “Is Gatekeeper enabled on macOS devices?“ Th
---
### Count policies
`GET /api/v1/fleet/policies/count`
#### Parameters
| Name | Type | In | Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| query | string | query | Search query keywords. Searchable fields include `name`. |
#### Example
`GET /api/v1/fleet/policies/count`
##### Default response
`Status: 200`
```json
{
"count": 43
}
```
---
### Get policy by ID
`GET /api/v1/fleet/global/policies/:id`
#### Parameters
| Name | Type | In | Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| id | integer | path | **Required.** The policy's ID. |
#### Example
`GET /api/v1/fleet/global/policies/1`
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 1,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": false,
"author_id": 42,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2021-12-15T15:23:57Z",
"updated_at": "2021-12-15T15:23:57Z",
"passing_host_count": 2000,
"failing_host_count": 300,
"host_count_updated_at": "2023-12-20T15:23:57Z"
}
}
```
### Add policy
`POST /api/v1/fleet/global/policies`
#### Parameters
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| name | string | body | The policy's name. |
| query | string | body | The policy's query in SQL. |
| description | string | body | The policy's description. |
| resolution | string | body | The resolution steps for the policy. |
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
#### Example (preferred)
`POST /api/v1/fleet/global/policies`
#### Request body
```json
{
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"resolution": "Resolution steps",
"platform": "darwin",
"critical": true
}
```
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 43,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"author_id": 42,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2022-03-17T20:15:55Z",
"updated_at": "2022-03-17T20:15:55Z",
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null
}
}
```
### Remove policies
`POST /api/v1/fleet/global/policies/delete`
#### Parameters
| Name | Type | In | Description |
| -------- | ------- | ---- | ------------------------------------------------- |
| ids | array | body | **Required.** The IDs of the policies to delete. |
#### Example
`POST /api/v1/fleet/global/policies/delete`
#### Request body
```json
{
"ids": [ 1 ]
}
```
##### Default response
`Status: 200`
```json
{
"deleted": 1
}
```
### Edit policy
`PATCH /api/v1/fleet/global/policies/:id`
#### Parameters
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| id | integer | path | The policy's ID. |
| name | string | body | The query's name. |
| query | string | body | The query in SQL. |
| description | string | body | The query's description. |
| resolution | string | body | The resolution steps for the policy. |
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
#### Example
`PATCH /api/v1/fleet/global/policies/42`
##### Request body
```json
{
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"resolution": "Resolution steps",
"platform": "darwin"
}
```
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 42,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"author_id": 43,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2022-03-17T20:15:55Z",
"updated_at": "2022-03-17T20:15:55Z",
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null
}
}
```
### Reset automations for all hosts failing policies
Resets [automation](https://fleetdm.com/docs/using-fleet/automations#policy-automations) status for *all* hosts failing the specified policies. On the next automation run, any failing host will be considered newly failing.
`POST /api/v1/fleet/automations/reset`
#### Parameters
| Name | Type | In | Description |
| ---------- | -------- | ---- | -------------------------------------------------------- |
| policy_ids | array | body | Filters to only run policy automations for the specified policies. |
| team_ids | array | body | _Available in Fleet Premium_. Filters to only run policy automations for hosts in the specified teams. |
#### Example
`POST /api/v1/fleet/automations/reset`
##### Request body
```json
{
"team_ids": [1],
"policy_ids": [1, 2, 3]
}
```
##### Default response
`Status: 200`
```json
{}
```
---
## Team policies
- [List team policies](#list-team-policies)
- [Count team policies](#count-team-policies)
- [Get team policy by ID](#get-team-policy-by-id)
- [Add team policy](#add-team-policy)
- [Remove team policies](#remove-team-policies)
- [Edit team policy](#edit-team-policy)
### List team policies
_Available in Fleet Premium_
Team policies work the same as policies, but at the team level.
### List team policies
`GET /api/v1/fleet/teams/:id/policies`
#### Parameters
@@ -7114,8 +6854,38 @@ Team policies work the same as policies, but at the team level.
}
```
---
### Count policies
`GET /api/v1/fleet/policies/count`
#### Parameters
| Name | Type | In | Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| query | string | query | Search query keywords. Searchable fields include `name`. |
#### Example
`GET /api/v1/fleet/policies/count`
##### Default response
`Status: 200`
```json
{
"count": 43
}
```
---
### Count team policies
_Available in Fleet Premium_
`GET /api/v1/fleet/team/:team_id/policies/count`
#### Parameters
@@ -7141,8 +6911,53 @@ Team policies work the same as policies, but at the team level.
---
### Get policy by ID
`GET /api/v1/fleet/global/policies/:id`
#### Parameters
| Name | Type | In | Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| id | integer | path | **Required.** The policy's ID. |
#### Example
`GET /api/v1/fleet/global/policies/1`
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 1,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": false,
"author_id": 42,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2021-12-15T15:23:57Z",
"updated_at": "2021-12-15T15:23:57Z",
"passing_host_count": 2000,
"failing_host_count": 300,
"host_count_updated_at": "2023-12-20T15:23:57Z"
}
}
```
---
### Get team policy by ID
_Available in Fleet Premium_
`GET /api/v1/fleet/teams/:team_id/policies/:policy_id`
#### Parameters
@@ -7192,8 +7007,74 @@ Team policies work the same as policies, but at the team level.
}
```
---
### Add policy
`POST /api/v1/fleet/global/policies`
#### Parameters
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| name | string | body | The policy's name. |
| query | string | body | The policy's query in SQL. |
| description | string | body | The policy's description. |
| resolution | string | body | The resolution steps for the policy. |
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
#### Example (preferred)
`POST /api/v1/fleet/global/policies`
#### Request body
```json
{
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"resolution": "Resolution steps",
"platform": "darwin",
"critical": true
}
```
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 43,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"author_id": 42,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2022-03-17T20:15:55Z",
"updated_at": "2022-03-17T20:15:55Z",
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null
}
}
```
---
### Add team policy
_Available in Fleet Premium_
> **Experimental feature**. Software related features (like install software policy automation) are undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
The semantics for creating a team policy are the same as for global policies, see [Add policy](#add-policy).
@@ -7269,7 +7150,45 @@ Either `query` or `query_id` must be provided.
}
```
### Remove team policies
---
### Delete policies
`POST /api/v1/fleet/global/policies/delete`
#### Parameters
| Name | Type | In | Description |
| -------- | ------- | ---- | ------------------------------------------------- |
| ids | array | body | **Required.** The IDs of the policies to delete. |
#### Example
`POST /api/v1/fleet/global/policies/delete`
#### Request body
```json
{
"ids": [ 1 ]
}
```
##### Default response
`Status: 200`
```json
{
"deleted": 1
}
```
---
### Delete team policies
_Available in Fleet Premium_
`POST /api/v1/fleet/teams/:team_id/policies/delete`
@@ -7302,8 +7221,12 @@ Either `query` or `query_id` must be provided.
}
```
---
### Edit team policy
_Available in Fleet Premium_
> **Experimental feature**. Software related features (like install software policy automation) are undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
`PATCH /api/v1/fleet/teams/:team_id/policies/:policy_id`
@@ -7378,6 +7301,103 @@ Either `query` or `query_id` must be provided.
}
```
### Edit policy
`PATCH /api/v1/fleet/global/policies/:id`
#### Parameters
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| id | integer | path | The policy's ID. |
| name | string | body | The query's name. |
| query | string | body | The query in SQL. |
| description | string | body | The query's description. |
| resolution | string | body | The resolution steps for the policy. |
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
#### Example
`PATCH /api/v1/fleet/global/policies/42`
##### Request body
```json
{
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"resolution": "Resolution steps",
"platform": "darwin"
}
```
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 42,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"author_id": 43,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2022-03-17T20:15:55Z",
"updated_at": "2022-03-17T20:15:55Z",
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null
}
}
```
### Reset automations for all hosts failing policies
Resets [automation](https://fleetdm.com/docs/using-fleet/automations#policy-automations) status for *all* hosts failing the specified policies. On the next automation run, any failing host will be considered newly failing.
`POST /api/v1/fleet/automations/reset`
#### Parameters
| Name | Type | In | Description |
| ---------- | -------- | ---- | -------------------------------------------------------- |
| policy_ids | array | body | Filters to only run policy automations for the specified policies. |
| team_ids | array | body | _Available in Fleet Premium_. Filters to only run policy automations for hosts in the specified teams. |
#### Example
`POST /api/v1/fleet/automations/reset`
##### Request body
```json
{
"team_ids": [1],
"policy_ids": [1, 2, 3]
}
```
##### Default response
`Status: 200`
```json
{}
```
---
## Queries