# REST API Use the Fleet APIs to automate Fleet. This page includes a list of available resources and their API routes. Unless otherwise specified, endpoints that accept a request body limit its size to the configured `FLEET_SERVER_DEFAULT_MAX_REQUEST_BODY_SIZE` (default 1MiB). ## Authentication - [Retrieve your API token](#retrieve-your-api-token) - [Log in](#log-in) - [Log out](#log-out) - [Forgot password](#forgot-password) - [Update password](#update-password) - [Reset password](#reset-password) - [Me](#me) - [SSO config](#sso-config) - [Initiate SSO](#initiate-sso) - [SSO callback](#sso-callback) ### Retrieve your API token All API requests to the Fleet server require API token authentication unless noted in the documentation. API tokens are tied to your Fleet user account. To get an API token, retrieve it from "My account" > "Get API token" in the Fleet UI (`/profile`). Or, you can send a request to the [login API endpoint](#log-in) to get your token. Then, use that API token to authenticate all subsequent API requests by sending it in the "Authorization" request header, prefixed with "Bearer ": ```http Authorization: Bearer ``` > For SSO and MFA users, email/password login is disabled. The API token can instead be retrieved from the "My account" page in the UI (/profile). On this page, choose "Get API token". ### Log in Authenticates the user with the specified credentials. Use the token returned from this endpoint to authenticate further API requests. `POST /api/v1/fleet/login` > Logging in via the API is not supported for SSO and MFA users. The API token can instead be retrieved from the "My account" page in the UI (/profile). On this page, choose "Get API token". #### Parameters | Name | Type | In | Description | | -------- | ------ | ---- | --------------------------------------------- | | email | string | body | **Required**. The user's email. | | password | string | body | **Required**. The user's plain text password. | #### Example `POST /api/v1/fleet/login` ##### Request body ```json { "email": "janedoe@example.com", "password": "VArCjNW7CfsxGp67" } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "2020-11-13T22:57:12Z", "updated_at": "2020-11-13T22:57:12Z", "id": 1, "name": "Jane Doe", "email": "janedoe@example.com", "enabled": true, "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "global_role": "admin", "teams": [], "fleets": [] }, "token": "{your token}" } ``` ##### Authentication failed `Status: 401 Unauthorized` ```json { "message": "Authentication failed", "errors": [ { "name": "base", "reason": "Authentication failed" } ], "uuid": "1272014b-902b-4b36-bcdb-75fde5eac1fc" } ``` ##### MFA Required `Status: 202 Accepted` ```json { "message": "We sent an email to you. Please click the magic link in the email to sign in.", } ``` ##### Too many requests / Rate limiting `Status: 429 Too Many Requests` `Header: retry-after: N` > This response includes a header `retry-after` that indicates how many more seconds you are blocked before you can try again. ```json { "message": "limit exceeded, retry after: Ns", "errors": [ { "name": "base", "reason": "limit exceeded, retry after: Ns" } ] } ``` --- ### Log out Logs out the authenticated user. `POST /api/v1/fleet/logout` #### Example `POST /api/v1/fleet/logout` ##### Default response `Status: 200` --- ### Forgot password Sends a password reset email to the specified email. Requires that SMTP or SES is configured for your Fleet server. `POST /api/v1/fleet/forgot_password` #### Parameters | Name | Type | In | Description | | ----- | ------ | ---- | ----------------------------------------------------------------------- | | email | string | body | **Required**. The email of the user requesting the reset password link. | #### Example `POST /api/v1/fleet/forgot_password` ##### Request body ```json { "email": "janedoe@example.com" } ``` ##### Default response `Status: 200` ##### Unknown error `Status: 500` ```json { "message": "Unknown Error", "errors": [ { "name": "base", "reason": "email not configured" } ] } ``` --- ### Update password `POST /api/v1/fleet/change_password` Changes the password for the authenticated user. #### Parameters | Name | Type | In | Description | | ------------ | ------ | ---- | -------------------------------------- | | old_password | string | body | **Required**. The user's old password. | | new_password | string | body | **Required**. The user's new password. | #### Example `POST /api/v1/fleet/change_password` ##### Request body ```json { "old_password": "VArCjNW7CfsxGp67", "new_password": "zGq7mCLA6z4PzArC" } ``` ##### Default response `Status: 200` ##### Validation failed `Status: 422 Unprocessable entity` ```json { "message": "Validation Failed", "errors": [ { "name": "old_password", "reason": "old password does not match" } ] } ``` ### Reset password Resets a user's password. Which user is determined by the password reset token used. The password reset token can be found in the password reset email sent to the desired user. `POST /api/v1/fleet/reset_password` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ---- | ------------------------------------------------------------------------- | | new_password | string | body | **Required**. The new password. | | new_password_confirmation | string | body | **Required**. Confirmation for the new password. | | password_reset_token | string | body | **Required**. The token provided to the user in the password reset email. | #### Example `POST /api/v1/fleet/reset_password` ##### Request body ```json { "new_password": "abc123", "new_password_confirmation": "abc123", "password_reset_token": "UU5EK0JhcVpsRkY3NTdsaVliMEZDbHJ6TWdhK3oxQ1Q=" } ``` ##### Default response `Status: 200` --- ### Me Retrieves the user data for the authenticated user. `GET /api/v1/fleet/me` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ---- | ------------------------------------------------------------------------- | | include_ui_settings | boolean | query | If set to true, includes the columns the user hides on the **Hosts** page (default: `false`). | #### Example `GET /api/v1/fleet/me` ##### Default response `Status: 200` ```json { "user": { "created_at": "2020-11-13T22:57:12Z", "updated_at": "2020-11-16T23:49:41Z", "id": 1, "name": "Jane Doe", "email": "janedoe@example.com", "global_role": "admin", "enabled": true, "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "teams": [], "fleets": [] }, "available_teams" : [ { "id": 1, "name": "Workstations", "description": "Employee workstations" } ], "available_fleets" : [ { "id": 1, "name": "Workstations", "description": "Employee workstations" } ] } ``` --- ### Perform required password reset Resets the password of the authenticated user. Requires that `force_password_reset` is set to `true` prior to the request. `POST /api/v1/fleet/perform_required_password_reset` #### Example `POST /api/v1/fleet/perform_required_password_reset` ##### Request body ```json { "new_password": "sdPz8CV5YhzH47nK" } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "2020-11-13T22:57:12Z", "updated_at": "2020-11-17T00:09:23Z", "id": 1, "name": "Jane Doe", "email": "janedoe@example.com", "enabled": true, "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "global_role": "admin", "teams": [], "fleets": [] } } ``` --- ### SSO config Gets the current SSO configuration. `GET /api/v1/fleet/sso` #### Example `GET /api/v1/fleet/sso` ##### Default response `Status: 200` ```json { "settings": { "idp_name": "IDP Vendor 1", "idp_image_url": "", "sso_enabled": false } } ``` --- ### Initiate SSO `POST /api/v1/fleet/sso` A successful response contains an HTTP cookie `__Host-FLEETSSOSESSIONID` that needs to be sent on the `POST /api/v1/fleet/sso/callback` request (this HTTP cookie is used to identify the SSO login session). #### Parameters | Name | Type | In | Description | | --------- | ------ | ---- | --------------------------------------------------------------------------- | | relay_url | string | body | **Required**. The relative url to be navigated to after successful sign in. | #### Example `POST /api/v1/fleet/sso` ##### Request body ```json { "relay_url": "/hosts/manage" } ``` ##### Default response `Status: 200` Example response cookie in the HTTP `Set-Cookie` header: ``` Set-Cookie: __Host-FLEETSSOSESSIONID=slI727JZ+j0FvyBRLyD/gri1rxtwpaZT; Path=/; Max-Age=300; HttpOnly; Secure ``` ##### Unknown error `Status: 500` ```json { "message": "Unknown Error", "errors": [ { "name": "base", "reason": "InitiateSSO getting metadata: Get \"https://idp.example.org/idp-meta.xml\": dial tcp: lookup idp.example.org on [2001:558:feed::1]:53: no such host" } ] } ``` ### SSO callback This is the callback endpoint that the identity provider will use to send security assertions to Fleet. This is where Fleet receives and processes the response from the identify provider. `POST /api/v1/fleet/sso/callback` The `__Host-FLEETSSOSESSIONID` HTTP cookie must be set for non-IdP initiated SSO login requests. The value for this cookie is returned in the `POST /api/v1/fleet/sso` request. For IdP-initiated SSO logins the cookie doesn't need to be set. #### Parameters | Name | Type | In | Description | | ------------------------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------- | | SAMLResponse | string | body | **Required**. The SAML response from the identity provider. | | __Host-FLEETSSOSESSIONID | string | cookie | HTTP Cookie returned in the `POST /api/v1/fleet/sso` request. This is not set/required for IdP initiated SSO logins | #### Example `POST /api/v1/fleet/sso/callback` ##### Request body ```json { "SAMLResponse": "" } ``` Example session cookie set in the `Cookie` request header: ``` Cookie: __Host-FLEETSSOSESSIONID=slI727JZ+j0FvyBRLyD/gri1rxtwpaZT ``` ##### Default response `Status: 200` --- ## Activities + [List activities](#list-activities) + [List policy automation activities](#list-policy-automation-activities) + [Reset policy results](#reset-policy-results) ### List activities Returns a list of the activities that have been performed in Fleet. For a comprehensive list of activity types and detailed information, please see the [audit logs](https://fleetdm.com/docs/using-fleet/audit-activities) page. `GET /api/v1/fleet/activities` #### Parameters | Name | Type | In | Description | |:--------------- |:------- |:----- |:------------------------------------------------------------| | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. Maximum is 10,000 records. If no pagination parameters are specified, defaults to 10,000. | | order_key | string | query | What to order results by. Can be any column in the `activities` table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | query | string | query | Search query keywords. Searchable fields include `actor_full_name` and `actor_email`. | activity_type | string | query | Indicates the activity `type` to filter by. See available activity types in the [Audit logs docs](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/audit-logs.md). | start_created_at | string | query | Filters to include only activities that happened after this date. If not specified, set to the earliest possible date. | end_created_at | string | query | Filters to include only activities that happened before this date. If not specified, set to now. | #### Example `GET /api/v1/fleet/activities?page=0&per_page=10&order_key=created_at&order_direction=desc` ##### Default response ```json { "activities": [ { "created_at": "2023-07-27T14:35:08Z", "id": 25, "actor_full_name": "Anna Chao", "actor_id": 3, "actor_gravatar": "", "actor_email": "", "type": "installed_software", "fleet_initiated": false, "details": { "status": "installed", "host_id": 1272, "host_display_name": "MacBook Pro", "policy_id": null, "policy_name": null, "install_uuid": "23c18ea1-8cd7-4af4-a1d8-f2666993a66b", "self_service": false, "software_title": "zoom.us.app", "software_package": "ZoomInstallerIT.pkg" } }, { "created_at": "2021-07-29T14:40:27Z", "id": 21, "actor_full_name": "name", "actor_id": 1, "actor_gravatar": "", "actor_email": "name@example.com", "type": "created_team", "type": "created_fleet", "fleet_initiated": false, "details": { "team_id": 2, "fleet_id": 2, "team_name": "Apples", "fleet_name": "Apples" } }, { "created_at": "2023-07-27T14:35:08Z", "id": 25, "type": "installed_software", "fleet_initiated": true, "details": { "status": "installed", "host_id": 1272, "host_display_name": "MacBook Pro", "policy_id": 24, "policy_name": "[Install software] Zoom", "install_uuid": "077970ab-0ed6-4573-9cdc-ca9ef9015283", "self_service": false, "software_title": "zoom.us.app", "software_package": "ZoomInstallerIT.pkg" } } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### List policy automation activities `GET /api/v1/fleet/policies/:id/automation_activities` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The policy ID. | | status | string | path | Optional filter by automation status. Either "success" or "error" | | query | string | path | Search query to filter by. Can search by host's name. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page. Maximum is 10,000 records. If no pagination parameters are specified, defaults to 10,000.| | order_key | string | query | What to order results by. Allowed fields are `id`, `created_at`, and `activity_type`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/policies/12/automation_activities?query=Anna's%20MacBook` ##### Default response `Status: 200` ```json { "activities": [ { "created_at": "2023-07-27T14:35:08Z", "id": 412, "actor_full_name": "Fleet", "actor_id": null, "actor_gravatar": "", "actor_email": "", "type": "failed_webhook_policy_automation", "fleet_initiated": true, "details": { "policy_id": 42, "policy_name": "Gatekeeper enabled" }, "host_id": 10, "host_display_name": "Anna's MacBook Pro", "status": "error", "output": null }, { "created_at": "2023-07-27T14:34:22Z", "id": 410, "actor_full_name": "Anna Chao", "actor_id": 3, "actor_gravatar": "", "actor_email": "anna@example.com", "type": "ran_script", "fleet_initiated": false, "details": { "host_id": 10, "host_display_name": "Anna's MacBook Pro", "script_name": "remediate-gatekeeper.sh", "script_execution_id": "d6cffa75-b5b5-41ef-9230-15073c8a88cf", "policy_id": 42, "policy_name": "Gatekeeper enabled" }, "host_id": 10, "host_display_name": "Anna's MacBook Pro", "status": "success", "output": "Gatekeeper enabled\n" }, { "created_at": "2023-07-27T14:33:01Z", "id": 407, "actor_full_name": "Fleet", "actor_id": null, "actor_gravatar": "", "actor_email": "", "type": "installed_software", "fleet_initiated": true, "details": { "host_id": 11, "host_display_name": "Marco's Windows", "install_uuid": "23c18ea1-8cd7-4af4-a1d8-f2666993a66b", "software_title": "1Password", "software_package": "1Password.msi", "policy_id": 42, "policy_name": "Gatekeeper enabled" }, "host_id": 11, "host_display_name": "Marco's Windows", "status": "error", "output": "Installing software...\nFailed\nExit code: 1" }, { "created_at": "2023-07-27T14:31:47Z", "id": 404, "actor_full_name": "Fleet", "actor_id": null, "actor_gravatar": "", "actor_email": "", "type": "installed_app_store_app", "fleet_initiated": true, "details": { "host_id": 10, "host_display_name": "Anna's MacBook Pro", "software_title": "Logic Pro", "app_store_id": "1234567", "command_uuid": "98765432-1234-1234-1234-1234567890ab", "policy_id": 42, "policy_name": "Gatekeeper enabled" }, "host_id": 10, "host_display_name": "Anna's MacBook Pro", "status": "success", "output": null } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Reset policy results Clears a policy's pass/fail results, identical to the side effect of editing its query. Immediately sets `passing_host_count` and `failing_host_count` to `0` and wipes membership records so the counts remain `0` until hosts re-report. Pass the `host_id` query parameter to instead reset only a single host's result for the policy. `POST /api/v1/fleet/policies/:policy_id/reset` #### Parameters | Name | Type | In | Description | | --------- | ------- | ---- | --------------------------------------------------------------------------------------------- | | policy_id | integer | path | **Required.** The policy's ID. | | host_id | integer | query | When set, resets only this host's result for the policy instead of resetting all hosts. | #### Example `POST /api/v1/fleet/policies/123/reset?host_id=42` ##### Default response `Status: 200` #### Errors | Status | Description | | ------ | ---------------------------------------------------------------------- | | 403 | The authenticated user does not have write access to the policy. | | 404 | No policy with the given `policy_id` exists. | --- ## Certificates - [Connect certificate authority (CA)](#connect-certificate-authority-ca) - [Add certificate template](#add-certificate-template) - [Update certificate authority (CA)](#update-certificate-authority-ca) - [List certificate authorities (CAs)](#list-certificate-authorities-cas) - [Get certificate authority (CA)](#get-certificate-authority-ca) - [List certificate templates](#list-certificate-templates) - [Get certificate template](#get-certificate-template) - [Delete certificate authority (CA)](#delete-certificate-authority-ca) - [Delete certificate template](#delete-certificate-template) - [Request certificate](#request-certificate) - [Resend host's certificate](#resend-hosts-certificate) ### Connect certificate authority (CA) Connect Fleet to a certificate authority (CA). Fleet currently supports [DigiCert](https://www.digicert.com/digicert-one), [Microsoft NDES](https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/network-device-enrollment-service-overview), [Hydrant](https://www.hidglobal.com/), [Smallstep](https://smallstep.com/), and any custom [SCEP](https://en.wikipedia.org/wiki/Simple_Certificate_Enrollment_Protocol) or [EST](https://en.wikipedia.org/wiki/Enrollment_over_Secure_Transport) CA. `POST /api/v1/fleet/certificate_authorities` Only one of the objects is allowed in a single request. #### Parameters | Name | Type | In | Description | |---------------- |-------- |------|-------------------------------------------------------------| | digicert | object | body | See [digicert](#digicert) | | ndes_scep_proxy | object | body | See [ndes_scep_proxy](#ndes-scep-proxy) | | custom_scep_proxy | object | body | See [custom_scep_proxy](#custom-scep-proxy) | | custom_est_proxy | object | body | See [custom_est_proxy](#custom-est-proxy) | | hydrant | object | body | See [hydrant](#hydrant) | | smallstep | object | body | See [smallstep](#smallstep) | ##### digicert Object with the following structure: | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | **Required**. Name of the certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed. | | url | string | **Required** DigiCert instance URL, used as base URL for DigiCert API requests. | | api_token | string | **Required** API token used to authenticate requests to DigiCert. | | profile_id | string | **Required** The ID of certificate profile in DigiCert. | | certificate_common_name | string | **Required** The certificate's common name. | | certificate_user_principal_names | array | Use with type `digicert`. The certificate's user principal names (UPN) attribute in Subject Alternative Name (SAN). | | certificate_seat_id | string | **Required** The ID of the DigiCert seat. Seats are license units in DigiCert. | ##### ndes_scep_proxy Object with the following structure: | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | **Required**. The URL of the NDES SCEP endpoint. | | admin_url | string | **Required**. The URL of the NDES admin endpoint. | | password | string | **Required**. The password for the NDES admin endpoint. | | username | string | **Required**. The username for the NDES admin endpoint. | ##### custom_scep_proxy Object with the following structure: | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | **Required**. Name of the certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed. | | url | string | **Required**. URL of the Simple Certificate Enrollment Protocol (SCEP) server | | challenge | string | **Required**. Static challenge password used to authenticate requests to SCEP server. | ##### custom_est_proxy Object with the following structure: | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | **Required**. Name of the certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed. | | url | string | **Required**. The EST (Enrollment Over Secure Transport) endpoint's URL. | | username | string | **Required**. The username used to authenticate with the EST endpoint. | | password | string | **Required**. The password used to authenticate with the EST endpoint. | ##### hydrant Object with the following structure: | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | **Required**. Name of the certificate authority. Only letters, numbers, and underscores are allowed. | | url | string | **Required**. The EST (Enrollment Over Secure Transport) endpoint provided by Hydrant. | | client_id | string | **Required**. The client ID provided by Hydrant.| | client_secret | string | **Required**. The client secret provided by Hydrant. | ##### smallstep Object with the following structure: | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | **Required**. The **SCEP URL** from Smallstep. | | challenge_url | string | **Required**. The **Webhook URL** from Smallstep.| | username | string | **Required**. The **Challenge Basic Authentication Username** from Smallstep. | | password | string | **Required**. The **Challenge Basic Authentication Password** from Smallstep. | #### Example `POST /api/v1/fleet/certificate_authorities` ##### Request body ```json { "digicert": { "name": "WIFI_CERTIFICATE", "url": "https://one.digicert.com", "api_token": "********", "profile_id": "b416e058-1bdc-4844-9c3f-7c71d58d0eff", "certificate_common_name": "$FLEET_VAR_HOST_HARDWARE_SERIAL", "certificate_user_principal_names": [ "$FLEET_VAR_HOST_HARDWARE_SERIAL" ], "certificate_seat_id": "$FLEET_VAR_HOST_END_USER_EMAIL_IDP" } } ``` ##### Default response `Status: 200` ```json { "id": 1, "name": "WIFI_CERTIFICATE", "type": "digicert" } ``` ### Add certificate template Add a certificate template to deploy a certificate to all hosts on the fleet. Fleet currently supports adding certificates for Android that are issued from a custom [SCEP](https://en.wikipedia.org/wiki/Simple_Certificate_Enrollment_Protocol) certificate authority. `POST /api/v1/fleet/certificates` #### Parameters | Name | Type | In | Description | | -------- | ------- | ---- | ------------------------------------------- | | name | string | body | **Required.** The name of the certificate. Name can be used as certificate alias to reference in configuration profiles. | | fleet_id | string | body | _Available in Fleet Premium_. The ID of the fleet to add profiles to. | | certificate_authority_id | integer | body | **Required.** The certificate authority (CA) ID to issue certificate from. Currently, only custom SCEP CA is supported. To get ID use [List certificate authorities](#list-certificate-authorities-cas). | | subject_name | string | body |**Required** The certificate's subject name (SN). Separate subject fields with a comma (`,`). For example: "CN=john@example.com,O=Acme Inc.". | | subject_alternative_name | string | body | The certificate's subject alternative name (SAN). Separate SAN fields with a comma (`,`). Each field is a key-value pair. See [supported keys](https://fleetdm.com/docs/configuration/yaml-files#android-settings-certificates). Example: `DNS=wifi.example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME`. | #### Example `POST /api/v1/fleet/certificates` ##### Request body ```json { "name": "wifi-certificate", "team_id": 1, "fleet_id": 1, "certificate_authority_id": 1, "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME" } ``` ##### Default response `Status: 200` ```json { "certificate_authority_id": 1, "id": 1, "name": "wifi-certificate", "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME" } ``` ### Update certificate authority (CA) `PATCH /api/v1/fleet/certificate_authorities/:id` When editing a CA, specify one object and only its fields that you want to update. #### Parameters | Name | Type | In | Description | |---------------- |-------- |------|-------------------------------------------------------------| | id | integer | path | **Required.** The certificate authority (CA) ID in Fleet. You can see your CAs IDs using the [List certificate authorities endpoint](#list-certificate-authorities-cas). | | digicert | object | body | See [digicert](#digicert) | | ndes_scep_proxy | object | body | See [ndes_scep_proxy](#ndes-scep-proxy) | | custom_scep_proxy | object | body | See [custom_scep_proxy](#custom-scep-proxy) | | custom_est_proxy | object | body | See [custom_est_proxy](#custom-est-proxy) | | hydrant | object | body | See [hydrant](#hydrant) | | smallstep | object | body | See [smallstep](#smallstep) | See [Connect certificate authority](#connect-certificate-authority-ca) above for the structure of each CA object. #### Example `PATCH /api/v1/fleet/certificate_authorities/1` ##### Request body ```json { "digicert": { "certificate_common_name": "$FLEET_VAR_HOST_HARDWARE_SERIAL", } } ``` ##### Default response `Status: 200` ### List certificate authorities (CAs) `GET /api/v1/fleet/certificate_authorities` #### Example `GET /api/v1/fleet/certificate_authorities` ##### Default response `Status: 200` ```json { "certificate_authorities": [ { "id": 3, "name": "DIGICERT_PROD", "type": "digicert" }, { "id": 2, "name": "DIGICERT_STAGE", "type": "digicert" }, { "id": 5, "name": "HYDRANT_WIFI_STAGE", "type": "hydrant" }, { "id": 1, "name": "NDES_VPN", "type": "ndes_scep_proxy" }, { "id": 4, "name": "SCEP_CERTIFICATE_PROD", "type": "custom_scep_proxy" }, { "id": 5, "name": "SECTIGO_WIFI", "type": "custom_est_proxy" }, { "id": 6, "name": "SMALLSTEP_WIFI", "type": "smallstep" } ] } ``` ### Get certificate authority (CA) Get details of the certificate authority. `GET /api/v1/fleet/certificate_authorities/:id` #### Parameters | Name | Type | In | Description | |---------------- |-------- |------|-------------------------------------------------------------| | id | integer | body | **Required**. The ID of certificate authority. | #### Example `GET /api/v1/fleet/certificate_authorities/1` ##### Default response `Status: 200` ```json { "id": 1, "type": "digicert", "name": "WIFI_CERTIFICATE", "url": "https://one.digicert.com", "api_token": "********", "profile_id": "b416e058-1bdc-4844-9c3f-7c71d58d0eff", "certificate_common_name": "$FLEET_VAR_HOST_HARDWARE_SERIAL", "certificate_user_principal_names": [ "$FLEET_VAR_HOST_HARDWARE_SERIAL" ], "certificate_seat_id": "$FLEET_VAR_HOST_END_USER_EMAIL_IDP" } ``` ### List certificate templates List certificates added to Fleet. `GET /api/v1/fleet/certificates` #### Parameters | Name | Type | In | Description | | ----------| ------- | ---- | -------------------------------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. The fleet ID to filter certificate templates. If not specified, this defaults to "Unassigned". | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed field is `id`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Request headers This endpoint accepts the node key from Fleet's Android agent for authentication in addition to [default authentication](#retrieve-your-api-token) with a Bearer token. The `Authorization` header must be formatted as follows: ``` Authorization: Node key ``` OR ``` Authorization: Bearer ``` When you pass a node key in the authorization header the server will look up the host and replace the `$FLEET_*` variables with the values associated to that host. If you use a regular bearer token the `$FLEET_*` variables will not be replaced. #### Example `GET /api/v1/fleet/certificates/` ##### Request headers ```http Authorization: Node key 24dd9ebf-02cd-4d4c-888a-5caa441ee5d5 ``` OR ```http Authorization: Bearer sunVIQ+wqYQvJlXf1aqYTt8LrlUGKBigNdWmdH5bhT1MH ``` ##### Default response `Status: 200` ```json { "certificates": [ { "id": 1, "name": "wifi-certificate", "certificate_authority_id": "1", "certificate_authority_name": "PRODUCTION_SCEP_SERVER", "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME", "created_at": "2025-11-04T00:00:00Z" }, { "id": 2, "name": "vpn-certificate", "certificate_authority_id": "1", "certificate_authority_name": "PRODUCTION_SCEP_SERVER", "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID", "created_at": "2025-11-04T00:00:00Z" } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Get certificate template Get details of the certificate added to Fleet. `GET /api/v1/fleet/certificates/:id` #### Parameters | Name | Type | In | Description | |---------------- |-------- |------|-------------------------------------------------------------| | id | integer | path | **Required**. The ID of the certificate. | | host_id | integer | query | ID of the host. If included, variables in `subject_name`, and `subject_alternative_name` will be replaced with host's values. | #### Request headers This endpoint accepts the node key from Fleet's Android agent for authentication in addition to [default authentication](#retrieve-your-api-token) with a Bearer token. The `Authorization` header must be formatted as follows: ``` Authorization: Node key ``` OR ``` Authorization: Bearer ``` When you pass a node key in the authorization header the server will look up the host and replace the `$FLEET_*` variables with the values associated to that host. If you use a regular bearer token the `$FLEET_*` variables will not be replaced. #### Example `GET /api/v1/fleet/certificates/1` ##### Request headers ```http Authorization: Node key 24dd9ebf-02cd-4d4c-888a-5caa441ee5d5 ``` OR ```http Authorization: Bearer sunVIQ+wqYQvJlXf1aqYTt8LrlUGKBigNdWmdH5bhT1MH ``` ##### Default response `Status: 200` ```json { "certificate_authority_id": 2, "certificate_authority_name": "PRODUCTION_SCEP_SERVER", "created_at": "2025-11-04T00:00:00Z", "id": 1, "name": "wifi-certificate", "subject_name": "CN=marko@example.com, O=Fleet Inc", "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME" } ``` ### Delete certificate authority (CA) When the CA is deleted, the issued certificates will remain on existing hosts. `DELETE /api/v1/fleet/certificate_authorities/:id` #### Parameters | Name | Type | In | Description | |---------------- |-------- |------|-------------------------------------------------------------| | id | integer | path | **Required.** The certificate authority (CA) ID in Fleet. You can see your CAs IDs using the [List certificate authorities endpoint](#list-certificate-authorities-cas). | #### Example `DELETE /api/v1/fleet/certificate_authorities/1` ##### Default response `Status: 204` ### Delete certificate template Deletes the certificate template added to Fleet. When a certificate template is deleted from Fleet, the certificate will be uninstalled from the hosts. `DELETE /api/v1/fleet/certificates/:id` #### Parameters | Name | Type | In | Description | |---------------- |-------- |------|-------------------------------------------------------------| | id | integer | path | **Required.** The certificate ID in Fleet. You can see your certificate IDs using the [List certificate templates endpoint](#list-certificate-templates). | #### Example `DELETE /api/v1/fleet/certificates/1` ##### Default response `Status: 204` ### Request certificate Requests a certificate from a certificate authority (CA). Currently, this endpoint is only supported for [Hydrant](#hydrant) and [custom EST](#custom-est-proxy) CAs. DigiCert, NDES, and custom SCEP coming soon. By default, the `certificate` field in the response is a PEM-encoded PKCS7 envelope (`-----BEGIN PKCS7-----`/`-----END PKCS7-----`). Set `return_pem_certificate` to `true` to receive a standard PEM `CERTIFICATE` block instead. As an alternative to [API token authentication](https://fleetdm.com/docs/rest-api/rest-api#retrieve-your-api-token), you can send an [HTTP signature in the request header](#example-http-signature). `POST /api/v1/fleet/certificate_authorities/:id/request_certificate` #### Parameters | Name | Type | In | Description | | -------- | ------- | ---- | ------------------------------------------- | | id | string | path | **Required.** The certificate authority (CA) ID in Fleet. You can see your CAs IDs using the [List certificate authorities endpoint](#list-certificate-authorities-cas). | | csr | string | body |**Required** The signed certificate signing request (CSR). | | idp_oauth_url | string | body | OAuth introspection URL from your identity provider (IdP). Required if `idp_token` is specified. | | idp_token | string | body | Active session token from your identity provider (IdP). Required if `idp_oauth_url` is specified.| | idp_client_id | string | body | Client ID for which the token was issued from your identity provider (IdP). Required if `idp_oauth_url` is specified.| | return_pem_certificate | boolean | body | If `true`, the issued certificate is returned as a PEM-encoded `CERTIFICATE` block instead of the default PEM-encoded PKCS7 envelope. Defaults to `false`. | #### Example `POST /api/v1/fleet/certificate_authorities/5/request_certificate` ##### Request body ```json { "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC/jCCAeYCAQAwITEfMB0GA1UEAwwWQ2lzY29Vc2VyTmV0d29ya0FjY2VzczCC\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJZtbxathh+RfK+Z613ar4E\nYSIem8yAvv2JZJtopjD3noy1yF+nGRyF/ocm+FhYvjR5u7teJXlcv24tAAHuWL4U\nuPIql0Slakjdsfl098salkj324lkjmtElWDi6XRjUIXEj1zyCnZTCxGmyHcYB/+f3fyv/\ngZ8SkPqocNOCpX6cSW8hxOlaF9aZUC+xMHRdjQgxQ79hleb5K/n2gCJjiW1sV0Es\nRg+MX0cbPCpahpzlvIAkzA7TTUTOd7ZN+V0GW0fH86uMstrqeW2QUuZmSDC9fNyj\nQhk6n5iURaHXdFjSmyrhW5AVvw1nIblHodhUtD6J+g9kjhBg1frss3ndQtnNrnMC\nAwEAAaCBlzCkldflkjc098dlkj2KoZIhvcNAQkOMYGGMIGDMIGABgNVHREEeTB3ggljaXNjby5j\nb22BEWthYW53YXJAY2lzY28uY29thjRJRDpGbGVldERNOkdVSUQ6Y2FkMTM4OTEt\nMzU3Ni00NzhmLTk1MzAtZmM1Y2VlZTEzZTkwoCEGCisGAQQBgjcUAgOgEwwRa2Fh\nbndhckBjaXNjby5jb20wDQYJKoZIhvcNAQELBQADggEBAH2U6Or14b4O22YjM22k\nXI9QDC5P+sDczcLjivv4MyXQL1ks8R6B1nXCrOmiLPPLaZ09f+UkeMnyuGAxW8Ce\n6LTKquwvlifZ+5TjyANz0I/d9ETLQF2MTphEZd4ySNLtq2RwYyDOBKaxMdW0sUsd\n6M3WyAuTBVgBkTVIqbMJBzFsgXSrr2a0LJEHszOO2BN3yT5muDQsKPJ1uXL7tNUv\n16pGaYpQZR8yGAmWyISHhAyLaJ1N1R8L77SLxdd/Sj7RunNNxqFqaEgIJMgsyu08\nGharLkQcIoW7qPHZuaLa54xMF/s/vfKH6rgGbbCAgw9kw8Klt+6H3OH1FSMeRfZ/\nDWs=\n-----END CERTIFICATE REQUEST-----", "idp_oauth_url": "https://idp.oauth.com/introspection", "idp_token": "88683de5858044aaacaf4046aeeef778044aaacaf4046", "idp_client_id": "1o2czkDnUVwTqSOc747" } ``` #### Default response `Status: 200` ```json { "certificate": "-----BEGIN PKCS7-----\nMIIGmAYJKoZIhvcNAQcCoIIGiTCCBoUCAQExADALBgkqhkiG9w0BBwGgggZtMIIG\naTCCBVGgAwIBAgITHQAAAAQszG7Pr1bRVwABAAAABDANBgkqhkiG9w0BAQsFADBd\nMRMwEQYKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhhbXBsZTEt\nMCsGA1UEAxMkRXhhbXBsZSBJc3N1aW5nIENBIDEgLSBDQSBDb21wYXJ0bWVudDAe\nFw0yNjA0MzAxNjMwMDBaFw0yNjA3MjkxNjMwMDBaMBcxFTATBgNVBAMMDGZsZWV0\naWUtdXNlcjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALMrkHOVZWVG\nv9PqU20NgpWed9MdRtMc8406GGWQJ3Rj9/8Jcy8LOx1d5/XWLKK5VbN2c1hD/a26\nqkgHtDMfzRXnv5oFybkhaI5tlc9yhQmJVFI2RIBsSkZvIlX+SNWV2RuiyVHyGbjh\nzi3wZen1s0aOeXMMHdD5FVEngX4Fz3TuTb/Z8romrsSmWb32fQyQxola9/xe0IAn\nXZocrxi4xPjNKQbEN/2+gQ/MRJx+c+xnV3MVIrXn+8Av8MMBsXhCDlmT2QrpRezN\nAwWwRni9yKOb0sZMtTDrsCOgAmWsj0Qxf/ASMPh7xbozXK4ubf5ombYxEdwGgYl/\nIKQUKvBKYMMCAwEAAaA=\n-----END PKCS7-----\n" } ``` #### Example (return PEM-encoded certificate) ##### Request body ```json { "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC/jCCAeYCAQAwITEfMB0GA1UEAwwWQ2lzY29Vc2VyTmV0d29ya0FjY2VzczCC\n...\n-----END CERTIFICATE REQUEST-----", "return_pem_certificate": true } ``` ##### Default response `Status: 200` ```json { "certificate": "-----BEGIN CERTIFICATE-----\nMIIC5DCCAcwCCQChs1cFRAzRCTANBgkqhkiG9w0BAQsFADA0MTIwMAYDVQQDDClD\ndXN0b21lclVzZXJOZXR3b3JrQWNjZXNzOmJvYkBleGFtcGxlLmNvbTAeFw0yNTA5\nMDgxODM0MzNaFw0yODA2MDUxODM0MzNaMDQxMjAwBgNVBAMMKUN1c3RvbWVyVXNl\nck5ldHdvcmtBY2Nlc3M6Ym9iQGV4YW1wbGUuY29tMIIBIjANBgkqhkiG9w0BAQEF\nAAOCAQ8AMIIBCgKCAQEAuojcu8UBxTjpz5krPX4KmWNAmWvJ4U7yh8pGXOp6kngz\n1iRmGkBYdr0CQXlkrASejqglbdDfaRt3hz8S4raIlKyiU59gFK6f2Lory54ndzJw\nhVeNGqpLrnW1T763zvjcSKaASfVzdnsa66v6pZQte2fZAk7+q5o9ezyirSQmTuks\ndxXAZ5OiDafFwzXlanGZIvCsHBTJtbi881/QU701aTdFFrxLd+jsiaFhKSoQQcL5\nt0zu96cPS2dJivxpaogZ1f8dispWeRiMbt3njaxfWazm4RqvwvDouTSstqUxTzC8\n28Kbh7bnxPcSiuajnf35q53juhTLmB2CKEf0m1eqEwIDAQABMA0GCSqGSIb3DQEB\nCwUAA4IBAQCp75tK8cxR6A0Sfu3vg7TMPD3MkGrpdgh2giAVoCa4hOxOdHl/nYgu\nfPHodsRUfXi1SXo/77jLldGOLE6Ro447FMgrN94mRkaFUZbuLC5z2VciF9x1fdus\nIFfASIFnb4Zw24F2RDBbbGqXqRrA/1m1fWjHTb20+8rHeZW+FCJmxQrL27OG7n/n\nqDr8QmfNwTm8l72FBvUIz1xisuba5nXNAEc6rxTFw6WhPq5fgtBlVZCm55h87hHd\nQbzDGlkIXf+nypg9kwk3fDQ7VY9hrqc74wAefbIkvUSTk9rNaoncxI5Mod/imyan\ngCioUdMGd7M/dpEDDXKJNyI6lfscpG1D\n-----END CERTIFICATE-----\n" } ``` #### Example (HTTP signature) ##### Request header ```http Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew== Signature: sig1=:e8UJ5wMiRaonlth5ERtE8GIiEH7Akcr493nQ07VPNo6y3qvjdK\t0fo8VHO8xXDjmtYoatGYBGJVlMfIp06eVMEyNW2I4vN7XDAz7m5v1108vGzaDljr\d0H8+SJ28g7bzn6h2xeL/8q+qUwahWA/JmC8aOC9iVnwbOKCc0WSrLgWQwTY6VLp4\2Qt7jjhYT5W7/wCvfK9A1VmHH1lJXsV873Z6hpxesd50PSmO+xaNeYvDLvVdZlhtw\5PCtUYzKjHqwmaQ6DEuM8udRjYsoNqp2xZKcuCO1nKc0V3RjpqMZLuuyVbHDAbCzr\ 0pg2d2VM/OC33JAU7meEjjaNz+d7LWPg==: Signature-Input: sig1=("@method" "@authority" "@path" "@query" \"content-digest" "content-type" "content-length")\;created=1618884475;keyid="test-key-rsa-pss" ``` ##### Request body ```json { "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC/jCCAeYCAQAwITEfMB0GA1UEAwwWQ2lzY29Vc2VyTmV0d29ya0FjY2VzczCC\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJZtbxathh+RfK+Z613ar4E\nYSIem8yAvv2JZJtopjD3noy1yF+nGRyF/ocm+FhYvjR5u7teJXlcv24tAAHuWL4U\nuPIql0Slakjdsfl098salkj324lkjmtElWDi6XRjUIXEj1zyCnZTCxGmyHcYB/+f3fyv/\ngZ8SkPqocNOCpX6cSW8hxOlaF9aZUC+xMHRdjQgxQ79hleb5K/n2gCJjiW1sV0Es\nRg+MX0cbPCpahpzlvIAkzA7TTUTOd7ZN+V0GW0fH86uMstrqeW2QUuZmSDC9fNyj\nQhk6n5iURaHXdFjSmyrhW5AVvw1nIblHodhUtD6J+g9kjhBg1frss3ndQtnNrnMC\nAwEAAaCBlzCkldflkjc098dlkj2KoZIhvcNAQkOMYGGMIGDMIGABgNVHREEeTB3ggljaXNjby5j\nb22BEWthYW53YXJAY2lzY28uY29thjRJRDpGbGVldERNOkdVSUQ6Y2FkMTM4OTEt\nMzU3Ni00NzhmLTk1MzAtZmM1Y2VlZTEzZTkwoCEGCisGAQQBgjcUAgOgEwwRa2Fh\nbndhckBjaXNjby5jb20wDQYJKoZIhvcNAQELBQADggEBAH2U6Or14b4O22YjM22k\nXI9QDC5P+sDczcLjivv4MyXQL1ks8R6B1nXCrOmiLPPLaZ09f+UkeMnyuGAxW8Ce\n6LTKquwvlifZ+5TjyANz0I/d9ETLQF2MTphEZd4ySNLtq2RwYyDOBKaxMdW0sUsd\n6M3WyAuTBVgBkTVIqbMJBzFsgXSrr2a0LJEHszOO2BN3yT5muDQsKPJ1uXL7tNUv\n16pGaYpQZR8yGAmWyISHhAyLaJ1N1R8L77SLxdd/Sj7RunNNxqFqaEgIJMgsyu08\nGharLkQcIoW7qPHZuaLa54xMF/s/vfKH6rgGbbCAgw9kw8Klt+6H3OH1FSMeRfZ/\nDWs=\n-----END CERTIFICATE REQUEST-----", "idp_oauth_url": "https://idp.oauth.com/introspection", "idp_token": "88683de5858044aaacaf4046aeeef778044aaacaf4046", "idp_client_id": "1o2czkDnUVwTqSOc747", "return_pem_certificate": true } ``` #### Default response `Status: 200` ```json { "certificate": "-----BEGIN CERTIFICATE-----\nMIIC5DCCAcwCCQChs1cFRAzRCTANBgkqhkiG9w0BAQsFADA0MTIwMAYDVQQDDClD\ndXN0b21lclVzZXJOZXR3b3JrQWNjZXNzOmJvYkBleGFtcGxlLmNvbTAeFw0yNTA5\nMDgxODM0MzNaFw0yODA2MDUxODM0MzNaMDQxMjAwBgNVBAMMKUN1c3RvbWVyVXNl\nck5ldHdvcmtBY2Nlc3M6Ym9iQGV4YW1wbGUuY29tMIIBIjANBgkqhkiG9w0BAQEF\nAAOCAQ8AMIIBCgKCAQEAuojcu8UBxTjpz5krPX4KmWNAmWvJ4U7yh8pGXOp6kngz\n1iRmGkBYdr0CQXlkrASejqglbdDfaRt3hz8S4raIlKyiU59gFK6f2Lory54ndzJw\nhVeNGqpLrnW1T763zvjcSKaASfVzdnsa66v6pZQte2fZAk7+q5o9ezyirSQmTuks\ndxXAZ5OiDafFwzXlanGZIvCsHBTJtbi881/QU701aTdFFrxLd+jsiaFhKSoQQcL5\nt0zu96cPS2dJivxpaogZ1f8dispWeRiMbt3njaxfWazm4RqvwvDouTSstqUxTzC8\n28Kbh7bnxPcSiuajnf35q53juhTLmB2CKEf0m1eqEwIDAQABMA0GCSqGSIb3DQEB\nCwUAA4IBAQCp75tK8cxR6A0Sfu3vg7TMPD3MkGrpdgh2giAVoCa4hOxOdHl/nYgu\nfPHodsRUfXi1SXo/77jLldGOLE6Ro447FMgrN94mRkaFUZbuLC5z2VciF9x1fdus\nIFfASIFnb4Zw24F2RDBbbGqXqRrA/1m1fWjHTb20+8rHeZW+FCJmxQrL27OG7n/n\nqDr8QmfNwTm8l72FBvUIz1xisuba5nXNAEc6rxTFw6WhPq5fgtBlVZCm55h87hHd\nQbzDGlkIXf+nypg9kwk3fDQ7VY9hrqc74wAefbIkvUSTk9rNaoncxI5Mod/imyan\ngCioUdMGd7M/dpEDDXKJNyI6lfscpG1D\n-----END CERTIFICATE-----\n" } ``` ### Resend host's certificate Resends a certificate for the specified host. Currently, only Android certificates are supported. `POST /api/v1/fleet/hosts/:id/certificates/:certificate_template_id/resend` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | id | integer | path | **Required.** The host's ID. | | certificate_template_id | string | path | **Required.** The ID of the certificate to resend to the host. | #### Example `POST /api/v1/fleet/hosts/233/certificates/322/resend` ##### Default response `Status: 202` --- ## Charts - [Get chart data](#get-chart-data) ### Get chart data Returns time-series data for a dashboard chart, as a list of per-bucket distinct host counts over a recent window. The available metrics are: - `uptime`: the number of hosts online (checking in to Fleet) during each bucket. - `cve`: _Available in Fleet Premium_. The number of hosts with critical (CVSS >= 9.0) vulnerabilities in tracked software during each bucket. `GET /api/v1/fleet/charts/:metric` #### Parameters | Name | Type | In | Description | | --- | --- | --- | --- | | metric | string | path | **Required**. The chart metric. One of `uptime` or `cve`. The `cve` metric requires Fleet Premium. | | days | integer | query | Number of days of history to return. Must be between 1 and 31. Default is `7`. | | resolution | integer | query | Bucket size in hours. Must be `0` or a positive divisor of 24 (for example `1`, `2`, `3`, `4`, `6`, `8`, `12`, `24`). `0` (the default) uses the metric's default resolution. | | tz_offset | integer | query | The client's UTC offset in minutes, as returned by JavaScript's `Date.getTimezoneOffset()` (positive is west of UTC). Used to align bucket boundaries to the client's local time. | | fleet_id | integer | query | _Available in Fleet Premium_. Scopes results to the specified fleet. Use `0` to scope to "Unassigned" (no fleet) hosts. | | label_ids | string | query | Comma-separated list of label IDs. Limits the chart to hosts that belong to any of these labels. | | platforms | string | query | Comma-separated list of host platforms to include (for example `darwin,windows,linux,chrome`). | | include_host_ids | string | query | Comma-separated list of host IDs. Limits the chart to only these hosts. | | exclude_host_ids | string | query | Comma-separated list of host IDs to exclude from the chart. | | software_filters | string | query | `cve` metric only. Comma-separated list of software categories to include: `os`, `browsers`, `office`, `adobe`. Omit to include all categories. | | has_known_exploit | boolean | query | `cve` metric only. If `true`, only include CVEs with a known exploit (present in the CISA Known Exploited Vulnerabilities catalog). | | epss_min | number | query | `cve` metric only. Minimum EPSS probability, from `0.0` to `1.0`. | | epss_max | number | query | `cve` metric only. Maximum EPSS probability, from `0.0` to `1.0`. | | exclude_vulnerabilities | string | query | `cve` metric only. Comma-separated list of CVEs (for example `CVE-2024-1234`) to exclude from the chart. | #### Response fields | Name | Type | Description | | --- | --- | --- | | metric | string | The requested metric. | | visualization | string | The metric's default visualization (`line` or `checkerboard`). | | total_hosts | integer | The number of hosts matching the host filters, used as the denominator when the chart is displayed as a percentage. | | resolution | string | The bucket size of the returned data (for example `hourly`, `3-hour`, or `daily`). | | days | integer | The number of days of history returned. | | filters | object | The filters that were applied to the request. | | data | array | The time series. Each element has a `timestamp` (RFC3339, the start of the bucket) and a `value` (the host count). | ##### Default response `Status: 200` ```json { "metric": "cve", "visualization": "line", "total_hosts": 1164, "resolution": "3-hour", "days": 7, "filters": { "software_filters": ["browsers", "adobe"], "has_known_exploit": true }, "data": [ { "timestamp": "2026-06-08T00:00:00Z", "value": 488 }, { "timestamp": "2026-06-08T03:00:00Z", "value": 502 } ] } ``` --- ## Conditional access - [Get Okta certificate](#get-okta-certificate) - [Get Okta configuration profile](#get-okta-configuration-profile) - [Delete Microsoft Entra ID](#disconnect-microsoft-entra-id) ### Get Okta certificate Download the SAML IdP signing certificate for Okta conditional access. Okta uses this certificate to verify SAML assertions signed by Fleet. `GET /api/v1/fleet/conditional_access/idp/signing_cert` #### Parameters None. #### Example `GET /api/v1/fleet/conditional_access/idp/signing_cert` ##### Default response `Status: 200` Returns a PEM-encoded X.509 certificate file with `Content-Type: application/x-pem-file`. ### Get Okta configuration profile Download the macOS configuration profile (.mobileconfig) for Okta conditional access. This profile configures SCEP enrollment and client certificate authentication on macOS hosts. `GET /api/v1/fleet/conditional_access/idp/apple/profile` #### Parameters None. #### Example `GET /api/v1/fleet/conditional_access/idp/apple/profile` ##### Default response `Status: 200` Returns an Apple configuration profile file with `Content-Type: application/x-apple-aspen-config`. ### Delete Microsoft Entra ID Disconnects Fleet from Entra. This won't unblock end users failing policies. Learn how to [unblock end users](https://fleetdm.com/guides/entra-conditional-access-integration#disable). `DELETE /api/v1/fleet/conditional-access/microsoft` #### Parameters None. ##### Default response `Status: 200` --- ## File carving - [List carves](#list-carves) - [Get carve](#get-carve) - [Get carve block](#get-carve-block) File carving allows you to request files (and sets of files) and their full contents from hosts. To initiate a file carve using the Fleet API, use the [live report](#run-live-report) endpoint to run a query against the `carves` table. Any failure when uploading a file block (like a network error) will result in a failed carved file. Block uploads are retried up to three times before failing. To learn more about executing a file carve in Fleet, head to the [file carving guide](https://fleetdm.com/guides/file-carving). ### List carves Retrieves a list of the non expired carves. Carve contents remain available for 24 hours after the first data is provided from the osquery client. `GET /api/v1/fleet/carves` #### Parameters | Name | Type | In | Description | |-----------------|---------|-------|--------------------------------------------------------------------------------------------------------------------------------| | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be any field listed in the `results` array example below. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Valid options are `"asc"` or `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | expired | boolean | query | Include expired carves (default: false) | #### Example `GET /api/v1/fleet/carves` ##### Default response `Status: 200` ```json { "carves": [ { "id": 1, "created_at": "2021-02-23T22:52:01Z", "host_id": 7, "name": "macbook-pro.local-2021-02-23T22:52:01Z-fleet_distributed_query_30", "block_count": 1, "block_size": 2000000, "carve_size": 2048, "carve_id": "c6958b5f-4c10-4dc8-bc10-60aad5b20dc8", "request_id": "fleet_distributed_query_30", "session_id": "065a1dc3-40ad-441c-afff-80c2ad7dac28", "expired": false, "max_block": 0 }, { "id": 2, "created_at": "2021-02-23T22:53:03Z", "host_id": 7, "name": "macbook-pro.local-2021-02-23T22:53:03Z-fleet_distributed_query_31", "block_count": 2, "block_size": 2000000, "carve_size": 3400704, "carve_id": "2b9170b9-4e11-4569-a97c-2f18d18bec7a", "request_id": "fleet_distributed_query_31", "session_id": "f73922ed-40a4-4e98-a50a-ccda9d3eb755", "expired": false, "max_block": 1, "error": "S3 multipart carve upload: EntityTooSmall: Your proposed upload is smaller than the minimum allowed object size" } ] } ``` ### Get carve Retrieves the specified carve. `GET /api/v1/fleet/carves/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ------------------------------------- | | id | integer | path | **Required.** The desired carve's ID. | #### Example `GET /api/v1/fleet/carves/1` ##### Default response `Status: 200` ```json { "carve": { "id": 1, "created_at": "2021-02-23T22:52:01Z", "host_id": 7, "name": "macbook-pro.local-2021-02-23T22:52:01Z-fleet_distributed_query_30", "block_count": 1, "block_size": 2000000, "carve_size": 2048, "carve_id": "c6958b5f-4c10-4dc8-bc10-60aad5b20dc8", "request_id": "fleet_distributed_query_30", "session_id": "065a1dc3-40ad-441c-afff-80c2ad7dac28", "expired": false, "max_block": 0 } } ``` ### Get carve block Retrieves the specified carve block. This endpoint retrieves the data that was carved. `GET /api/v1/fleet/carves/:id/block/:block_id` #### Parameters | Name | Type | In | Description | | -------- | ------- | ---- | ------------------------------------------- | | id | integer | path | **Required.** The desired carve's ID. | | block_id | integer | path | **Required.** The desired carve block's ID. | #### Example `GET /api/v1/fleet/carves/1/block/0` ##### Default response `Status: 200` ```json { "data": "aG9zdHMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..." } ``` --- ## Fleet configuration - [Get Fleet certificate](#get-fleet-certificate) - [Get configuration](#get-configuration) - [Update configuration](#update-configuration) - [Update organization logo](#update-organization-logo) - [Delete organization logo](#delete-organization-logo) - [Get global enroll secrets](#get-global-enroll-secrets) - [Update global enroll secrets](#update-global-enroll-secrets) - [Get fleet-level enroll secrets](#get-fleet-level-enroll-secrets) - [Update fleet-level enroll secrets](#update-fleet-level-enroll-secrets) - [Get version](#get-version) The Fleet server exposes API endpoints that handle the configuration of Fleet as well as endpoints that manage enroll secret operations. These endpoints require prior authentication, you so you'll need to log in before calling any of the endpoints documented below. ### Get Fleet certificate Returns the Fleet certificate. `GET /api/v1/fleet/config/certificate` #### Parameters None. #### Example `GET /api/v1/fleet/config/certificate` ##### Default response `Status: 200` ```json { "certificate_chain": "" } ``` ### Get configuration Returns all information about the Fleet's configuration. The `agent_options`, `sso_settings` and `smtp_settings` fields are only returned for admin and GitOps users with global access (see the [Role-based access guide](https://fleetdm.com/guides/role-based-access)). `mdm.apple_settings.configuration_profiles`, `mdm.windows_settings.configuration_profiles`, `mdm.setup_experience`, `mdm.volume_purchasing_program`, and `scripts` only include the settings applied using [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To list the settings added in the UI or API, use the [List configuration profiles](https://fleetdm.com/docs/rest-api/rest-api#list-custom-os-settings-configuration-profiles), GET endpoints from [Setup experience](https://fleetdm.com/docs/rest-api/rest-api#setup-experience), [List Volume Purchasing Program (VPP) tokens](https://fleetdm.com/docs/rest-api/rest-api#list-volume-purchasing-program-vpp-tokens), or [List scripts](https://fleetdm.com/docs/rest-api/rest-api#list-scripts) instead. `GET /api/v1/fleet/config` #### Parameters None. #### Example `GET /api/v1/fleet/config` ##### Default response `Status: 200` ```json { "org_info": { "org_name": "fleet", "org_logo_url_dark_mode": "", "org_logo_url_light_mode": "", "org_logo_url": "", "org_logo_url_light_background": "", "contact_url": "https://fleetdm.com/company/contact" }, "server_settings": { "server_url": "https://instance.fleet.com", "enable_analytics": true, "live_query_disabled": false, "query_reports_disabled": false, "ai_features_disabled": false }, "smtp_settings": { "enable_smtp": false, "configured": false, "sender_address": "", "server": "", "port": 587, "authentication_type": "authtype_username_password", "user_name": "", "password": "********", "enable_ssl_tls": true, "authentication_method": "authmethod_plain", "domain": "", "verify_ssl_certs": true, "enable_start_tls": true }, "sso_settings": { "entity_id": "", "issuer_uri": "", "idp_image_url": "", "metadata": "", "metadata_url": "", "idp_name": "", "enable_sso": false, "enable_sso_idp_login": false, "enable_jit_provisioning": false, "sso_server_url": "" }, "conditional_access": { "microsoft_entra_tenant_id": "", "microsoft_entra_connection_configured": false, "okta_idp_id": "0ogmbinlfy9hvGs7cx492", "okta_assertion_consumer_service_url": "https://example.okta.com/sso/saml2/0ogmbinlfy9hvGs7cx492", "okta_audience_uri": "https://www.okta.com/saml2/service-provider/asdhjlksoewpoasn", "okta_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----", "bypass_disabled": false }, "host_expiry_settings": { "host_expiry_enabled": false, "host_expiry_window": 0 }, "activity_expiry_settings": { "activity_expiry_enabled": false, "activity_expiry_window": 0, "preserve_host_activity_on_reenrollment": false }, "features": { "enable_host_users": true, "enable_software_inventory": true, "additional_queries": null }, "mdm": { "android_enabled_and_configured": true, "windows_enabled_and_configured": true, "windows_entra_tenant_ids": [ "fec37e96-3615-4e37-8fac-445d5328af3c" ], "windows_entra_client_ids": [ "8c8e3fd4-9b2c-4d3e-8f10-2233445566aa" ], "enable_turn_on_windows_mdm_manually": false, "enable_disk_encryption": true, "windows_require_bitlocker_pin": false, "apple_require_hardware_attestation": false, "name_template": "", "macos_updates": { "minimum_version": "12.3.1", "deadline": "2022-01-01", "update_new_hosts": true }, "ios_updates": { "minimum_version": "17.0.1", "deadline": "2024-08-01" }, "ipados_updates": { "minimum_version": "17.0.1", "deadline": "2024-08-01" }, "windows_updates": { "deadline_days": 5, "grace_period_days": 1 }, "macos_settings": { "custom_settings": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] } ] }, "apple_settings": { "configuration_profiles": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] }, { "path": "path/to/declaration.json", "labels": ["Label 1", "Label 2"] } ], "assets": [ { "path": "path/to/assets/asset.json" } ], "managed_local_account_settings": { "enabled": true }, "end_user_local_account_type": "admin" }, "windows_settings": { "custom_settings": [ { "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } ], "configuration_profiles": [ { "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } ], "managed_local_account_settings": { "enabled": true } }, "scripts": ["path/to/script.sh"], "end_user_authentication": { "entity_id": "", "metadata": "", "metadata_url": "", "idp_name": "" }, "macos_migration": { "enable": false, "mode": "voluntary", "webhook_url": "https://webhook.example.com" }, "macos_setup": { "bootstrap_package": "", "enable_end_user_authentication": false, "macos_setup_assistant": "path/to/config.json", "enable_release_device_manually": false, "manual_agent_install": false, "enable_managed_local_account": false, "end_user_local_account_type": "admin" }, "setup_experience": { "bootstrap_package": "", "enable_end_user_authentication": false, "apple_setup_assistant": "path/to/config.json", "enable_release_device_manually": false, "manual_agent_install": false, "enable_managed_local_account": false, "end_user_local_account_type": "admin" }, "client_url": "https://instance.fleet.com", "apple_account_provisioning": { "oauth_idp_token_url": "https://fleet-example.okta.com/oauth2/v1/token", "oauth_idp_client_id": "Ooa12345abcdeFGHI678", "oauth_idp_client_secret": "********" } }, "agent_options": { "spec": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} } }, "license": { "tier": "premium", "organization": "fleet", "device_count": 500000, "expiration": "2031-10-16T00:00:00Z", "note": "" }, "logging": { "debug": false, "json": false, "result": { "plugin": "firehose", "config": { "region": "us-east-1", "status_stream": "", "result_stream": "result-topic" } }, "status": { "plugin": "filesystem", "config": { "status_log_file": "foo_status", "result_log_file": "", "enable_log_rotation": false, "enable_log_compression": false } } }, "vulnerability_settings": { "databases_path": "" }, "gitops": { "gitops_mode_enabled": false, "repository_url": "" }, "webhook_settings": { "host_status_webhook": { "enable_host_status_webhook": true, "destination_url": "https://server.com", "host_percentage": 5, "days_count": 7 }, "failing_policies_webhook":{ "enable_failing_policies_webhook":true, "destination_url": "https://server.com", "policy_ids": [1, 2, 3], "host_batch_size": 1000 }, "vulnerabilities_webhook":{ "enable_vulnerabilities_webhook":true, "destination_url": "https://server.com", "host_batch_size": 1000 }, "activities_webhook":{ "enable_activities_webhook":true, "destination_url": "https://server.com" } }, "integrations": { "google_calendar": [ { "domain": "example.com", "api_key_json": { "type": "service_account", "project_id": "fleet-in-your-calendar", "private_key_id": "", "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n", "client_email": "fleet-calendar-events@fleet-in-your-calendar.iam.gserviceaccount.com", "client_id": "", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/fleet-calendar-events%40fleet-in-your-calendar.iam.gserviceaccount.com", "universe_domain": "googleapis.com" } } ], "google_workspace": [ { "domain": "example.com", "impersonated_user_email": "admin@example.com", "api_key_json": { "type": "service_account", "project_id": "fleet-idp-sync", "private_key_id": "", "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n", "client_email": "fleet-idp-sync@fleet-idp-sync.iam.gserviceaccount.com", "client_id": "", "token_uri": "https://oauth2.googleapis.com/token", "universe_domain": "googleapis.com" } } ], "jira": [], "zendesk": [] }, "logging": { "debug": false, "json": false, "result": { "plugin": "filesystem", "config": { "status_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_status", "result_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_result", "enable_log_rotation": false, "enable_log_compression": false } }, "status": { "plugin": "filesystem", "config": { "status_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_status", "result_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_result", "enable_log_rotation": false, "enable_log_compression": false } } }, "update_interval": { "osquery_detail": 3600000000000, "osquery_policy": 3600000000000 }, "vulnerabilities": { "cpe_database_url": "", "disable_schedule": false, "cve_feed_prefix_url": "", "databases_path": "", "disable_data_sync": false, "periodicity": 3600000000000, "recent_vulnerability_max_age": 2592000000000000 } } ``` ### Update configuration Modifies the Fleet's configuration with the supplied information. `PATCH /api/v1/fleet/config` #### Parameters | Name | Type | In | Description | | ----------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ | | org_info | object | body | See [org_info](#org-info). | | server_settings | object | body | See [server_settings](#server-settings). | | smtp_settings | object | body | See [smtp_settings](#smtp-settings). | | sso_settings | object | body | See [sso_settings](#sso-settings). | | host_expiry_settings | object | body | See [host_expiry_settings](#host-expiry-settings). | | activity_expiry_settings | object | body | See [activity_expiry_settings](#activity-expiry-settings). | | agent_options | objects | body | The agent_options spec that is applied to all hosts. | | fleet_desktop | object | body | See [fleet_desktop](#fleet-desktop). | | webhook_settings | object | body | See [webhook_settings](#webhook-settings). | | integrations | object | body | See [integrations](#integrations). | | gitops | object | body | See [gitops](#gitops). | | mdm | object | body | See [mdm](#mdm). | | conditional_access | object | body | See [conditional_access](#conditional-access). | | features | object | body | See [features](#features). | | scripts | array | body | A list of script files to add so they can be executed at a later time. | | yara_rules | array | body | A list of YARA rule files to add. | | force | boolean | query | Whether to force-apply the agent options even if there are validation errors. | | dry_run | boolean | query | Whether to validate the configuration and return any validation errors **without** applying changes. | #### Example `PATCH /api/v1/fleet/config` ##### Request body ```json { "scripts": [] } ``` ##### Default response `Status: 200` ```json { "org_info": { "org_name": "Fleet Device Management", "org_logo_url_dark_mode": "https://fleetdm.com/logo.png", "org_logo_url_light_mode": "https://fleetdm.com/logo-light.png", "org_logo_url": "https://fleetdm.com/logo.png", "org_logo_url_light_background": "https://fleetdm.com/logo-light.png", "contact_url": "https://fleetdm.com/company/contact" }, "server_settings": { "server_url": "https://instance.fleet.com", "enable_analytics": true, "live_query_disabled": false, "query_reports_disabled": false, "ai_features_disabled": false }, "smtp_settings": { "enable_smtp": true, "configured": true, "sender_address": "", "server": "localhost", "port": 1025, "authentication_type": "authtype_username_none", "user_name": "", "password": "********", "enable_ssl_tls": true, "authentication_method": "authmethod_plain", "domain": "", "verify_ssl_certs": true, "enable_start_tls": true }, "sso_settings": { "entity_id": "", "issuer_uri": "", "idp_image_url": "", "metadata": "", "metadata_url": "", "idp_name": "", "enable_sso": false, "enable_sso_idp_login": false, "enable_jit_provisioning": false, "sso_server_url": "https://instance.fleet.com" }, "conditional_access": { "microsoft_entra_tenant_id": "", "microsoft_entra_connection_configured": true, "okta_idp_id": "0ogmbinlfy9hvGs7cx492", "okta_assertion_consumer_service_url": "https://example.okta.com/sso/saml2/0ogmbinlfy9hvGs7cx492", "okta_audience_uri": "https://www.okta.com/saml2/service-provider/asdhjlksoewpoasn", "okta_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----", "bypass_disabled": false }, "host_expiry_settings": { "host_expiry_enabled": false, "host_expiry_window": 0 }, "activity_expiry_settings": { "activity_expiry_enabled": false, "activity_expiry_window": 0, "preserve_host_activity_on_reenrollment": false }, "features": { "enable_host_users": true, "enable_software_inventory": true, "additional_queries": null }, "license": { "tier": "free", "expiration": "0001-01-01T00:00:00Z" }, "mdm": { "enabled_and_configured": false, "android_enabled_and_configured": false, "windows_enabled_and_configured": false, "windows_entra_tenant_ids": [ "26ac824d-0d5e-4f0c-a202-1c29d5a48e43" ], "windows_entra_client_ids": [ "8c8e3fd4-9b2c-4d3e-8f10-2233445566aa" ], "enable_turn_on_windows_mdm_manually": false, "enable_disk_encryption": true, "windows_require_bitlocker_pin": false, "apple_require_hardware_attestation": false, "enable_recovery_lock_password": true, "macos_updates": { "minimum_version": "12.3.1", "deadline": "2022-01-01", "update_new_hosts": true }, "ios_updates": { "minimum_version": "17.0.1", "deadline": "2024-08-01" }, "ipados_updates": { "minimum_version": "17.0.1", "deadline": "2024-08-01" }, "windows_updates": { "deadline_days": 5, "grace_period_days": 1 }, "macos_settings": { "custom_settings": [ { "path": "path/to/profile1.mobileconfig", "labels_exclude_any": ["Label 1", "Label 2"] }, { "path": "path/to/profile2.json", "labels_include_all": ["Label 3", "Label 4"] }, { "path": "path/to/profile3.json", "labels_include_any": ["Label 5", "Label 6"] } ] }, "apple_settings": { "configuration_profiles": [ { "path": "path/to/profile1.mobileconfig", "labels_exclude_any": ["Label 1", "Label 2"] }, { "path": "path/to/profile2.json", "labels_include_all": ["Label 3", "Label 4"] }, { "path": "path/to/profile3.json", "labels_include_any": ["Label 5", "Label 6"] } ], "assets": [ { "path": "path/to/assets/asset.json" } ], "managed_local_account_settings": { "enabled": true }, "end_user_local_account_type": "admin" }, "windows_settings": { "custom_settings": [ { "path": "path/to/profile3.xml", "labels_exclude_any": ["Label 1", "Label 2"] } ], "configuration_profiles": [ { "path": "path/to/profile3.xml", "labels_exclude_any": ["Label 1", "Label 2"] } ], "managed_local_account_settings": { "enabled": true } }, "end_user_authentication": { "entity_id": "", "metadata": "", "metadata_url": "", "idp_name": "" }, "macos_migration": { "enable": false, "mode": "voluntary", "webhook_url": "https://webhook.example.com" }, "macos_setup": { "bootstrap_package": "", "enable_end_user_authentication": false, "enable_managed_local_account": false, "end_user_local_account_type": "admin", "lock_end_user_info": true, "macos_setup_assistant": "path/to/config.json" }, "setup_experience": { "bootstrap_package": "", "enable_end_user_authentication": false, "enable_managed_local_account": false, "end_user_local_account_type": "admin", "lock_end_user_info": true, "apple_setup_assistant": "path/to/config.json" }, "apple_server_url": "https://instance.fleet.com" }, "agent_options": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "vulnerability_settings": { "databases_path": "" }, "fleet_desktop": { "transparency_url": "https://fleetdm.com/better", "alternative_browser_host": "fleet-desktop.example.com" }, "gitops": { "gitops_mode_enabled": false, "repository_url": "" }, "webhook_settings": { "host_status_webhook": { "enable_host_status_webhook": true, "destination_url": "https://server.com", "host_percentage": 5, "days_count": 7 }, "failing_policies_webhook":{ "enable_failing_policies_webhook":true, "destination_url": "https://server.com", "policy_ids": [1, 2, 3], "host_batch_size": 1000 }, "vulnerabilities_webhook":{ "enable_vulnerabilities_webhook":true, "destination_url": "https://server.com", "host_batch_size": 1000 }, "activities_webhook":{ "enable_activities_webhook":true, "destination_url": "https://server.com" } }, "integrations": { "google_calendar": [ { "domain": "", "api_key_json": null } ], "google_workspace": [ { "domain": "", "impersonated_user_email": "", "api_key_json": null } ], "jira": [ { "url": "https://jiraserver.com", "username": "some_user", "password": "sec4et!", "project_key": "jira_project", "enable_software_vulnerabilities": false } ], "zendesk": [] }, "logging": { "debug": false, "json": false, "result": { "plugin": "firehose", "config": { "region": "us-east-1", "status_stream": "", "result_stream": "result-topic" } }, "status": { "plugin": "filesystem", "config": { "status_log_file": "foo_status", "result_log_file": "", "enable_log_rotation": false, "enable_log_compression": false } } }, "scripts": [] } ``` #### org_info | Name | Type | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------- | | org_name | string | The organization name. | | org_logo_url_dark_mode | string | The URL for the organization logo displayed on top of dark backgrounds. | | org_logo_url_light_mode | string | The URL for the organization logo displayed in Fleet on top of light backgrounds. | | contact_url | string | A URL or [file URI](https://en.wikipedia.org/wiki/File_URI_scheme) that can be used by end users to contact the organization. | > `org_logo_url` and `org_logo_url_light_background` are deprecated. They are maintained for backwards compatibility. Please use `org_logo_url_dark_mode` and `org_logo_url_light_mode` instead.
##### Example request body ```json { "org_info": { "org_name": "Fleet Device Management", "org_logo_url_dark_mode": "https://fleetdm.com/logo.png", "org_logo_url_light_mode": "https://fleetdm.com/logo-light.png", "org_logo_url": "https://fleetdm.com/logo.png", "org_logo_url_light_background": "https://fleetdm.com/logo-light.png", "contact_url": "https://fleetdm.com/company/contact" } } ``` #### server_settings | Name | Type | Description | | --------------------- | ------- | ------------------------------------------------------------------------------------------- | | server_url | string | The Fleet server URL. | | enable_analytics | boolean | Whether to send anonymous usage statistics. Always enabled for Fleet Premium customers. | | live_reporting_disabled | boolean | Whether the live reporting capabilities are disabled. | | discard_reports_data | boolean | Whether storing report results are disabled. | | ai_features_disabled | boolean | Whether AI features are disabled. | | report_cap | integer | The maximum number of results to store per report before the report is clipped. If increasing this cap, we recommend enabling reports for one report at time and monitoring your infrastructure. (Default: `1000`) | > Note: If `server_url` changes, hosts that enrolled to the old URL will need to re-enroll, or they will no longer communicate with Fleet. Before re-enrolling Android hosts, you'll need to turn Android MDM off and back on to point Google to the new `server_url`.
##### Example request body ```json { "server_settings": { "server_url": "https://localhost:8080", "enable_analytics": true, "live_reporting_disabled": false, "discard_reports_data": false, "ai_features_disabled": false } } ``` #### smtp_settings | Name | Type | Description | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_smtp | boolean | Whether SMTP is enabled for the Fleet app. | | sender_address | string | The sender email address for the Fleet app. An invitation email is an example of the emails that may use this sender address | | server | string | The SMTP server for the Fleet app. | | port | integer | The SMTP port for the Fleet app. | | authentication_type | string | The authentication type used by the SMTP server. Options include `"authtype_username_password"` or `"none"` | | user_name | string | The username used to authenticate requests made to the SMTP server. | | password | string | The password used to authenticate requests made to the SMTP server. | | enable_ssl_tls | boolean | Whether or not SSL and TLS are enabled for the SMTP server. | | authentication_method | string | The authentication method used to make authenticate requests to SMTP server. Options include `"authmethod_plain"`, `"authmethod_cram_md5"`, and `"authmethod_login"`. | | domain | string | The domain for the SMTP server. | | verify_ssl_certs | boolean | Whether or not SSL certificates are verified by the SMTP server. Turn this off (not recommended) if you use a self-signed certificate. | | enable_start_tls | boolean | Detects if STARTTLS is enabled in your SMTP server and starts to use it. |
> The Fleet server relies on the host operating system's trust store to validate TLS certificates. If your email server uses a private or self-signed certificate, you’ll need to add the certificate to the OS trust store on the server running Fleet. Fleet doesn't currently support uploading custom CA certificates via the UI or API. ##### Example request body ```json { "smtp_settings": { "enable_smtp": true, "sender_address": "", "server": "localhost", "port": 1025, "authentication_type": "none", "user_name": "", "password": "", "enable_ssl_tls": true, "authentication_method": "authmethod_plain", "domain": "", "verify_ssl_certs": true, "enable_start_tls": true } } ``` #### sso_settings | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_sso | boolean | Whether or not SSO is enabled for the Fleet application. If this value is true, you must also include most of the SSO settings parameters below. | | entity_id | string | The required entity ID is a URI that you use to identify Fleet when configuring the identity provider. Must be 5 or more characters. | | issuer_uri | string | The URI you provide here must exactly match the Entity ID field used in the identity provider configuration. | | idp_image_url | string | An optional link to an image such as a logo for the identity provider. | | metadata_url | string | A URL that references the identity provider metadata. If available from the identity provider, this is the preferred means of providing metadata. Must be either https or http | | metadata | string | Metadata provided by the identity provider. Either `metadata` or a `metadata_url` must be provided. | | enable_sso_idp_login | boolean | Determines whether Identity Provider (IdP) initiated login for Single sign-on (SSO) is enabled for the Fleet application. | | enable_jit_provisioning | boolean | _Available in Fleet Premium._ When enabled, allows [just-in-time user provisioning](https://fleetdm.com/docs/deploy/single-sign-on-sso#just-in-time-jit-user-provisioning). | | sso_server_url | boolean | Update this URL if you want your Fleet users (admins, maintainers, observers) to login via SSO using a URL that's different than the base URL of your Fleet instance. If not configured, login via SSO will use the base URL of the Fleet instance. |
##### Example request body ```json { "sso_settings": { "enable_sso": false, "entity_id": "", "issuer_uri": "", "idp_image_url": "", "metadata_url": "", "metadata": "", "idp_name": "", "enable_sso_idp_login": false, "enable_jit_provisioning": false, "sso_server_url": "" } } ``` #### 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. | | host_expiry_window | integer | If a host has not communicated with Fleet in the specified number of days, it will be removed. Must be greater than 0 if host_expiry_enabled is set to true. |
##### Example request body ```json { "host_expiry_settings": { "host_expiry_enabled": true, "host_expiry_window": 7 } } ``` #### activity_expiry_settings | Name | Type | Description | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | activity_expiry_enabled | boolean | When enabled, allows automatic cleanup of activities (and associated live report data) older than the specified number of days. Activities linked to a host are preserved until the host is deleted. | | activity_expiry_window | integer | The number of days to retain activity records, if activity expiry is enabled. | | preserve_host_activity_on_reenrollment | boolean | When enabled, preserves host activities after a wipe and re-enrollment. Currently only supported for company-owned (AB) Apple hosts. **Delete activities > Max activity age** still applies. (Default: `false`) |
##### Example request body ```json { "activity_expiry_settings": { "activity_expiry_enabled": true, "activity_expiry_window": 90, "preserve_host_activity_on_reenrollment": true, } } ``` #### fleet_desktop _Available in Fleet Premium._ | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------- | | transparency_url | string | The URL used to display transparency information to users of Fleet Desktop. | | alternative_browser_host | string | The hostname used to navigate Fleet Desktop traffic through. |
##### Example request body ```json { "fleet_desktop": { "transparency_url": "https://fleetdm.com/better", "alternative_browser_host": "fleet-desktop.example.com" } } ``` #### gitops _Available in Fleet Premium._ | Name | Type | Description | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | gitops_mode_enabled | boolean | Whether to enable "GitOps mode", which restricts making changes via the UI that would be overridden by running `fleetctl-gitops`. (Default: `false`) | | repository_url | string | The URL for the repository where changes are managed, for Fleet instances using GitOps. Users will be sent here when GitOps mode is enabled. |
##### Example request body ```json { "gitops": { "gitops_mode_enabled": true, "repository_url": "https://github.com/exampleorg/it-and-security" } } ``` #### webhook_settings | Name | Type | Description | | --------------------- | ----- | ---------------------------------------------------------------------------------------------- | | interval | string | How often policy webhooks/tickets and host status webhooks are triggered, formatted as number + unit of measurement (e.g. `"90m"`). Can be specified in seconds (`"s"`), minutes (`"m"`), or hours (`"h"`). (Default: `"24h"`) | | host_status_webhook | array | See [`webhook_settings.host_status_webhook`](#webhook-settings-host-status-webhook). | | failing_policies_webhook | array | See [`webhook_settings.failing_policies_webhook`](#webhook-settings-failing-policies-webhook). | | vulnerabilities_webhook | array | See [`webhook_settings.vulnerabilities_webhook`](#webhook-settings-vulnerabilities-webhook). | | activities_webhook | array | See [`webhook_settings.activities_webhook`](#webhook-settings-activities-webhook). |
##### 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 | The minimum number of days that the configured `host_percentage` must fail to check in to Fleet in order to trigger the webhook request. |
##### 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). |
##### webhook_settings.vulnerabilities_webhook `webhook_settings.vulnerabilities_webhook` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_vulnerabilities_webhook | boolean | Whether or not the vulnerabilities webhook is enabled. | | destination_url | string | The URL to deliver the webhook requests to. | | host_batch_size | integer | Maximum number of hosts to batch on vulnerabilities webhook requests. The default, 0, means no batching (all vulnerable hosts are sent on one request). |
##### webhook_settings.activities_webhook `webhook_settings.activities_webhook` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | --------------------------------------------------------- | | enable_activities_webhook | boolean | Whether or not the activity feed webhook is enabled. | | destination_url | string | The URL to deliver the webhook requests to. |
##### Example request body ```json { "webhook_settings": { "host_status_webhook": { "enable_host_status_webhook": true, "destination_url": "https://server.com", "host_percentage": 5, "days_count": 7 }, "failing_policies_webhook":{ "enable_failing_policies_webhook": true, "destination_url": "https://server.com", "policy_ids": [1, 2, 3], "host_batch_size": 1000 }, "vulnerabilities_webhook":{ "enable_vulnerabilities_webhook":true, "destination_url": "https://server.com", "host_batch_size": 1000 }, "activities_webhook":{ "enable_activities_webhook":true, "destination_url": "https://server.com" } } } ``` #### integrations | Name | Type | Description | |-----------------|--------|----------------------------------------------------------------------| | jira | array | See [`integrations.jira`](#integrations-jira). | | zendesk | array | See [`integrations.zendesk`](#integrations-zendesk). | | google_calendar | array | See [`integrations.google_calendar`](#integrations-google-calendar). | | google_workspace | array | See [`integrations.google_workspace`](#integrations-google-workspace). |
##### integrations.jira `integrations.jira` is an array of objects with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_software_vulnerabilities | boolean | Whether or not Jira integration is enabled for software vulnerabilities. Only one vulnerability automation can be enabled at a given time (enable_vulnerabilities_webhook and enable_software_vulnerabilities). | | enable_failing_policies | boolean | Whether or not 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). | | url | string | The URL of the Jira server to integrate with. | | username | string | The Jira username to use for this Jira integration. | | api_token | string | The API token of the Jira username to use for this Jira integration. | | project_key | string | The Jira project key to use for this integration. Jira tickets will be created in this project. |
> Note that when making changes to the `integrations.jira` array, all integrations must be provided (not just the one being modified). This is because the endpoint will consider missing integrations as deleted. ##### integrations.zendesk `integrations.zendesk` is an array of objects with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_software_vulnerabilities | boolean | Whether or not Zendesk integration is enabled for software vulnerabilities. Only one vulnerability automation can be enabled at a given time (enable_vulnerabilities_webhook and enable_software_vulnerabilities). | | enable_failing_policies | boolean | Whether or not 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). | | url | string | The URL of the Zendesk server to integrate with. | | email | string | The Zendesk user email to use for this Zendesk integration. | | api_token | string | The Zendesk API token to use for this Zendesk integration. | | group_id | integer | The Zendesk group id to use for this integration. Zendesk tickets will be created in this group. |
> Note that when making changes to the `integrations.zendesk` array, all integrations must be provided (not just the one being modified). This is because the endpoint will consider missing integrations as deleted. ##### integrations.google_calendar `integrations.google_calendar` is an array of objects with the following structure: | Name | Type | Description | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | domain | string | The domain for the Google Workspace service account to be used for this calendar integration. | | api_key_json | object | The private key JSON downloaded when generating the service account API key to be used for this calendar integration. |
##### integrations.google_workspace _Available in Fleet Premium._ `integrations.google_workspace` is an array of objects with the following structure. When set, Fleet syncs identity provider (IdP) host vitals from your Google Workspace directory, and SCIM provisioning is ignored. | Name | Type | Description | | ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | | domain | string | Your Google Workspace primary domain whose directory is synced. | | impersonated_user_email | string | A Google Workspace admin the service account impersonates via domain-wide delegation. | | api_key_json | object | The service account JSON key (with domain-wide delegation enabled) used to authenticate to the Google Workspace directory. |
##### Example request body ```json { "integrations": { "jira": [ { "enable_software_vulnerabilities": false, "enable_failing_poilicies": true, "url": "https://jiraserver.com", "username": "some_user", "api_token": "", "project_key": "jira_project", } ], "zendesk": [], "google_calendar": [ { "domain": "https://domain.com", "api_key_json": "" } ], "google_workspace": [ { "domain": "example.com", "impersonated_user_email": "admin@example.com", "api_key_json": "" } ] } } ``` #### conditional_access _Available in Fleet Premium._ | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------- | | okta_idp_id | string | The IdP ID found in Okta after creating an IdP in **Security** > **Identity Providers** > **SAML 2.0 IdP** | | okta_assertion_consumer_service_url | string | The assertion consumer service URL found in Okta after creating an IdP in **Security** > **Identity Providers** > **SAML 2.0 IdP** | | okta_audience_uri | string | The audience URI found in Okta after creating an IdP in **Security** > **Identity Providers** > **SAML 2.0 IdP** | | okta_certificate | string | The certificate provided by Okta during the **Set Up Authenticator** workflow | | bypass_disabled | boolean | Disables the per-policy setting to allow bypassing Okta conditional access. (Default: `false`.) | When updating conditional access config, all `conditional_access` fields must either be empty or included in the request. ##### Example request body ```json { "conditional_access": { "okta_idp_id": "0ogmbinlfy9hvGs7cx492", "okta_assertion_consumer_service_url": "https://example.okta.com/sso/saml2/0ogmbinlfy9hvGs7cx492", "okta_audience_uri": "https://www.okta.com/saml2/service-provider/asdhjlksoewpoasn", "okta_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----", "bypass_disabled": false } } ``` #### mdm | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | windows_enabled_and_configured | boolean | Enables Windows MDM support. | | windows_entra_tenant_ids | array | _Available in Fleet Premium._ IDs of Microsoft Entra tenants to connect to Fleet, to enable automatic (Autopilot) and manual enrollment by end users (**Settings** > **Accounts** > **Access work or school** on Windows). Find your **Tenant ID**, on [**Microsoft Entra ID** > **Home**](https://entra.microsoft.com/#home). | | windows_entra_client_ids | array | _Available in Fleet Premium._ Microsoft Entra application (client) IDs for the applications used to enroll Windows hosts via Microsoft Entra. Set this when you set up Entra enrollment: Microsoft Entra issues v2 access tokens whose audience is the application's client ID, so Fleet needs the client ID to authorize enrollment. Find your **Application (client) ID** on [**Microsoft Entra ID** > **App registrations**](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) > your MDM application > **Overview**. | | enable_turn_on_windows_mdm_manually | boolean | _Available in Fleet Premium._ Specifies whether or not to require end users to manually turn on MDM in **Settings > Access work or school**. If `false`, MDM is automatically turned on for all Windows hosts that aren't connected to any MDM solution. | | enable_disk_encryption | boolean | _Available in Fleet Premium._ Hosts that are "Unassigned" will have disk encryption enabled if set to true. | | windows_require_bitlocker_pin | boolean | _Available in Fleet Premium._ End users on Windows hosts that are "Unassigned" will be required to set a BitLocker PIN if set to true. `enable_disk_encryption` must be set to true. When the PIN is set, it's required to unlock Windows host during startup. | | apple_require_hardware_attestation | boolean | _Available in Fleet Premium._ Specifies whether or not to require Apple Silicon macOS hosts to complete a device attestation challenge verifying that the hardware serial matches a known host record from ABM as part of DEP enrollment. | | enable_recovery_lock_password | boolean | _Available in Fleet Premium._ Unassigned hosts will have Recovery Lock password enabled if set to true. | | name_template | string | _Available in Fleet Premium._ Naming convention applied to "Unassigned" macOS, iOS, and iPadOS hosts. Supports the built-in host identity and IdP end-user variables and custom (`$FLEET_SECRET_*`) variables; certificate authority variables aren't supported. See the [Update host name template](#update-host-name-template) endpoint for the full list. An empty string clears the template. To set the template for a fleet, use that endpoint. | | macos_updates | object | See [`mdm.macos_updates`](#mdm-macos-updates). | | ios_updates | object | See [`mdm.ios_updates`](#mdm-ios-updates). | | ipados_updates | object | See [`mdm.ipados_updates`](#mdm-ipados-updates). | | windows_updates | object | See [`mdm.window_updates`](#mdm-windows-updates). | | macos_migration | object | See [`mdm.macos_migration`](#mdm-macos-migration). | | setup_experience | object | See [`mdm.setup_experience`](#mdm-setup-experience). | | macos_settings | object | See [`mdm.macos_settings`](#mdm-macos-settings). | | apple_settings | object | See [`mdm.apple_settings`](#mdm-macos-settings). | | windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings). | | apple_server_url | string | Update this URL if you're self-hosting Fleet and you want your hosts to talk to this URL for MDM features. (If not configured, hosts will use the base URL of the Fleet instance.) | > Note: If `apple_server_url` changes and Apple (macOS, iOS, iPadOS) hosts already have MDM turned on, the end users will have to turn MDM off and back on to use MDM features. > Note: If `apple_require_hardware_attestation` is enabled and Apple attestation servers are down, macOS Apple Silicon hosts will not be able to enroll.
##### mdm.macos_updates _Available in Fleet Premium._ `mdm.macos_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that are "Unassigned" and have MDM turned on will be prompted to update when their OS is below this version. | | deadline | string | Hosts that are "Unassigned" and have MDM turned on will be forced to update their OS after this deadline (7PM local time for hosts already on macOS 14 or above, 20:00 UTC for hosts on earlier macOS versions). | | update_new_hosts | string | macOS hosts that automatically enroll (ADE) are updated to [Apple's latest version](https://fleetdm.com/guides/enforce-os-updates) during macOS Setup Assistant. For backwards compatibility, if not specified, and `deadline` and `minimum_version` are set, `update_new_hosts` is set to `true`. Otherwise, `update_new_hosts` defaults to `false`. |
##### mdm.ios_updates _Available in Fleet Premium._ `mdm.ios_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that are "Unassigned" will be prompted to update when their OS is below this version. | | deadline | string | Hosts that are "Unassigned" will be forced to update their OS after this deadline (7PM local time). |
##### mdm.ipados_updates _Available in Fleet Premium._ `mdm.ipados_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that are "Unassigned" will be prompted to update when their OS is below this version. | | deadline | string | Hosts that are "Unassigned" will be forced to update their OS after this deadline (7PM local time). |
##### mdm.windows_updates _Available in Fleet Premium._ `mdm.windows_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | deadline_days | integer | Hosts that are "Unassigned" and have MDM turned on will have this number of days before updates are installed on Windows. | | grace_period_days | integer | Hosts that are "Unassigned" and have MDM turned on will have this number of days before Windows restarts to install updates. |
##### mdm.macos_migration _Available in Fleet Premium._ `mdm.macos_migration` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable | boolean | Whether to enable the end user migration workflow for devices migrating from your old MDM solution. | | mode | string | The end user migration workflow mode for devices migrating from your old MDM solution. Options are `"voluntary"` or `"forced"`. | | webhook_url | string | The webhook url configured to receive requests to unenroll devices migrating from your old MDM solution. |
##### mdm.setup_experience _Available in Fleet Premium._ `mdm.setup_experience` 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 devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#end-user-authentication). | | enable_managed_local_account | boolean | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on eligible hosts if set to true. | | end_user_local_account_type | string | _Available in Fleet Premium._ Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | | lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) |
##### mdm.macos_settings `mdm.macos_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 macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. |
##### mdm.apple_settings `mdm.apple_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 macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | | managed_local_account_settings | object | Settings for the managed local account. | | managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). | | end_user_local_account_type | string | The end user account type. Requires `managed_local_account_settings.enabled` to be `true`. Options: `"admin"`, `"standard"`, `"none"` (default: `"admin"`). |
##### 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 [Create configuration profile](#create-configuration-profile) endpoint instead. | | managed_local_account_settings | object | Settings for the managed local account. | | managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). |
##### mdm.end_user_authentication `mdm.end_user_authentication` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | entity_id | string | **Required**. The entity ID is a URI that you use to identify Fleet when configuring the identity provider. Must be 5 or more characters. | | idp_name | string | **Required.** A human friendly name for the identity provider that will provide single sign-on authentication. | | metadata_url | string | A URL that references the identity provider metadata. If available from the identity provider, this is the preferred means of providing metadata. Must be either https or http. | | metadata | string | Metadata provided by the identity provider. Either `metadata` or a `metadata_url` must be provided. |
##### Example request body ```json { "mdm": { "windows_enabled_and_configured": false, "enable_turn_on_windows_mdm_manually": false, "enable_disk_encryption": true, "windows_require_bitlocker_pin": false, "apple_require_hardware_attestation": false, "enable_recovery_lock_password": true, "macos_updates": { "minimum_version": "12.3.1", "deadline": "2022-01-01", "update_new_hosts": true }, "windows_updates": { "deadline_days": 5, "grace_period_days": 1 }, "apple_settings": { "configuration_profiles": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] }, { "path": "path/to/profile2.json", "labels": ["Label 3", "Label 4"] } ], "assets": [ { "path": "path/to/assets/asset.json" } ], "managed_local_account_settings": { "enabled": true } }, "windows_settings": { "configuration_profiles": [ { "path": "path/to/profile3.xml", "labels": ["Label 1", "Label 2"] } ], "managed_local_account_settings": { "enabled": true } }, "end_user_authentication": { "entity_id": "", "metadata": "", "metadata_url": "", "idp_name": "" }, "macos_migration": { "enable": false, "mode": "voluntary", "webhook_url": "https://webhook.example.com" }, "setup_experience": { "bootstrap_package": "", "enable_end_user_authentication": false, "lock_end_user_info": true, "apple_setup_assistant": "path/to/config.json" } } } ``` #### features | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_host_users | boolean | Whether to enable the users feature in Fleet. (Default: `true`) | | enable_software_inventory | boolean | Whether to enable the software inventory feature in Fleet. (Default: `true`) | | additional_queries | object | `additional_queries` adds extra host details. This information will be updated at the same time as other host details and is returned by the API when host objects are returned. (Default: `null`) | | historical_data | object | Per-dataset toggles for historical data collection used by the dashboard charts. See [Historical data](#historical-data) below. | ##### features.historical_data `features.historical_data` controls whether each dashboard chart's historical data is collected. Both sub-keys default to `true`. A dataset is collected for a given host only when both the global sub-key AND the host's fleet sub-key are `true`. | Name | Type | Description | | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------- | | uptime | boolean | Whether to collect host activity samples. (Default: `true`) | | vulnerabilities | boolean | Whether to collect per-host software vulnerability data. (Default: `true`) |
##### Example request body ```json { "features": { "enable_host_users": true, "enable_software_inventory": true, "additional_queries": { "time": "SELECT * FROM time", "macs": "SELECT mac FROM interface_details" }, "historical_data": { "uptime": true, "vulnerabilities": false } } } ``` ### Get global enroll secrets Returns the valid global enroll secrets. `GET /api/v1/fleet/spec/enroll_secret` #### Parameters None. #### Example `GET /api/v1/fleet/spec/enroll_secret` ##### Default response `Status: 200` ```json { "spec": { "secrets": [ { "secret": "vhPzPOnCMOMoqSrLxKxzSADyqncayacB", "created_at": "2021-11-12T20:24:57Z" }, { "secret": "jZpexWGiXmXaFAKdrdttFHdJBqEnqlVF", "created_at": "2021-11-12T20:24:57Z" } ] } } ``` ### Update organization logo Upload a custom logo to display in the top navigation, setup experience window, and MDM migration dialog. > You need to send a request of type `multipart/form-data`. `PUT /api/v1/fleet/logo` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | logo | file | body | The logo image to upload. For best results, use a square logo at least 150px x 150px. | | mode | string | query | Either `"light"` for the logo displayed in light mode, `"dark" for the logo displayed in dark mode`, or "all" to replace both light and dark mode logos. (Default: `"all"`.)| #### Example `PUT /api/v1/fleet/logo?mode=light` ##### Request body ```http icon="fleet-logo-150x150.png" ``` ##### Default response `Status: 204` ### Delete organization logo Delete a custom logo added via [Update organization logo](#update-organization-logo). This will revert to using the Fleet logo. `DELETE /api/v1/fleet/logo` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | logo | file | body | The logo image to upload. For best results, use a square logo at least 150px x 150px. | | mode | string | query | Either `"light"` for the logo displayed in light mode, `"dark" for the logo displayed in dark mode`, or "all" to replace both light and dark mode logos. (Default: `"all"`.)| #### Example `DELETE /api/v1/fleet/logo?mode=light` ##### Default response `Status: 204` ### Update global enroll secrets Replaces all existing global enroll secrets. `POST /api/v1/fleet/spec/enroll_secret` #### Parameters | Name | Type | In | Description | | --------- | ------- | ---- | ------------------------------------------------------------------ | | spec | object | body | **Required**. Attribute "secrets" must be a list of enroll secrets | #### Example Replace all global enroll secrets with a new enroll secret. `POST /api/v1/fleet/spec/enroll_secret` ##### Request body ```json { "spec": { "secrets": [ { "secret": "KuSkYFsHBQVlaFtqOLwoUIWniHhpvEhP" } ] } } ``` ##### Default response `Status: 200` ```json {} ``` #### Example Delete all global enroll secrets. `POST /api/v1/fleet/spec/enroll_secret` ##### Request body ```json { "spec": { "secrets": [] } } ``` ##### Default response `Status: 200` ```json {} ``` ### Get fleet-level enroll secrets Returns the fleet's enroll secrets. `GET /api/v1/fleet/fleets/:id/secrets` #### Parameters None. #### Example `GET /api/v1/fleet/fleets/1/secrets` ##### Default response `Status: 200` ```json { "secrets": [ { "created_at": "2021-06-16T22:05:49Z", "secret": "aFtH2Nq09hrvi73ErlWNQfa7M53D3rPR", "team_id": 1, "fleet_id": 1 } ] } ``` ### Update fleet-level enroll secrets Replaces all existing enroll secrets for a fleet. `PATCH /api/v1/fleet/fleets/:id/secrets` #### Parameters | Name | Type | In | Description | | --------- | ------- | ---- | -------------------------------------- | | id | integer | path | **Required**. The fleet's id. | | secrets | array | body | **Required**. A list of enroll secrets | #### Example Replace all of a fleet's existing enroll secrets with a new enroll secret `PATCH /api/v1/fleet/fleets/2/secrets` ##### Request body ```json { "secrets": [ { "secret": "n07v32y53c237734m3n201153c237" } ] } ``` ##### Default response `Status: 200` ```json { "secrets": [ { "secret": "n07v32y53c237734m3n201153c237", "created_at": "0001-01-01T00:00:00Z" } ] } ``` #### Example Delete all of a fleet's existing enroll secrets `PATCH /api/v1/fleet/fleets/2/secrets` ##### Request body ```json { "secrets": [] } ``` ##### Default response `Status: 200` ```json { "secrets": null } ``` ### Get version Get version and build information from the Fleet server. `GET /api/v1/fleet/version` #### Parameters None. #### Example `GET /api/v1/fleet/version` ##### Default response `Status: 200` ```json { "version": "3.9.0-93-g1b67826f-dirty", "branch": "version", "revision": "1b67826fe4bf40b2f45ec53e01db9bf467752e74", "go_version": "go1.15.7", "build_date": "2021-03-27", "build_user": "zwass" } ``` --- ## Hosts - [List hosts](#list-hosts) - [Count hosts](#count-hosts) - [Get hosts summary](#get-hosts-summary) - [Get host](#get-host) - [Get host by identifier](#get-host-by-identifier) - [Get host by Fleet Desktop token](#get-host-by-fleet-desktop-token) - [Delete host](#delete-host) - [Refetch host](#refetch-host) - [Refetch host by Fleet Desktop token](#refetch-host-by-fleet-desktop-token) - [Update hosts' fleet](#update-hosts-fleet) - [Update hosts' fleet by filter](#update-hosts-fleet-by-filter) - [Turn off host's MDM](#turn-off-hosts-mdm) - [Batch-delete hosts](#batch-delete-hosts) - [Update human-device mapping](#update-human-device-mapping) - [Get host's device health report](#get-hosts-device-health-report) - [Get host's mobile device management (MDM) information](#get-hosts-mobile-device-management-mdm-information) - [Get mobile device management (MDM) status](#get-mobile-device-management-mdm-status) - [Get host's mobile device management (MDM) and Munki information](#get-hosts-mobile-device-management-mdm-and-munki-information) - [Get hosts' aggregate mobile device management (MDM) and Munki information](#get-hosts-aggregate-mobile-device-management-mdm-and-munki-information) - [Get host's software](#get-hosts-software) - [Get hosts report in CSV](#get-hosts-report-in-csv) - [Get host's disk encryption key](#get-hosts-disk-encryption-key) - [Get host's Recovery Lock password](#get-hosts-recovery-lock-password) - [Get host's certificates](#get-hosts-certificates) - [Lock host](#lock-host) - [Unlock host](#unlock-host) - [Wipe host](#wipe-host) - [Get host's past activity](#get-hosts-past-activity) - [Get host's upcoming activity](#get-hosts-upcoming-activity) - [Cancel host's upcoming activity](#cancel-hosts-upcoming-activity) - [Add labels to host](#add-labels-to-host) - [Remove labels from host](#remove-labels-from-host) - [Run live report on host (ad hoc)](#run-live-report-on-host-ad-hoc) - [Run live report on host by identifier (ad hoc)](#run-live-report-on-host-by-identifier-ad-hoc) - [Bypass host's conditional access](#bypass-hosts-conditional-access) - [Get host's managed account password](#get-hosts-managed-account-password) #### About host timestamps Hosts have a set of timestamps usually named with an "_at" suffix, such as created_at, enrolled_at, etc. Before we go through each of them and what they mean, we need to understand a bit more about how the host data structure is represented in the database. The table `hosts` is the main one. It holds the core data for a host. A host doesn't exist if there is no row for it in this table. This table also holds most of the timestamps, but it doesn't hold all of the host data. This is an important detail as we'll see below. There's adjacent tables to this one that usually follow the name convention `host_`. Examples of this are: `host_additional` that holds additional query results, `host_software` that links a host with many rows from the `software` table. - `created_at`: the time the row in the database was created, which usually corresponds to the first enrollment of the host. - `updated_at`: the last time the row in the database for the `hosts` table was updated. - `detail_updated_at`: the last time Fleet updated host data (this includes updates to host associated tables, e.g. `host_users`). - `label_updated_at`: the last time Fleet updated the label membership for the host - `last_enrolled_at`: the last time the host enrolled to Fleet. - `policy_updated_at`: the last time we updated the policy results for the host - `seen_time`: the last time the host contacted the fleet server, regardless of what operation it was for. - `software_updated_at`: the last time software changed for the host in any way. - `last_restarted_at`: the last time that the host was restarted. ### List hosts `GET /api/v1/fleet/hosts` #### Parameters | Name | Type | In | Description | | ----------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be any column in the hosts table. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. **Note:** Use `page` instead of `after` | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. | | query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4`, and end user email addresses. | | additional_info_filters | string | query | A comma-delimited list of fields to include in each host's `additional` object. This query is populated by the `additional_queries` in the `features` section of the configuration YAML. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters to only include hosts in the specified fleet. Use `0` to filter by "Unassigned" hosts. | | policy_id | integer | query | The ID of the policy to filter hosts by. | | policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. | | software_version_id | integer | query | The ID of the software version to filter hosts by. | | software_title_id | integer | query | The ID of the software title to filter hosts by. | | software_status | string | query | The status of the software install to filter hosts by. One of: `pending_install`, `failed_install`, `installed`, `pending_uninstall`, `failed_uninstall`, `pending`, or `failed`. Mutually exclusive with `software_version_id`, and must be supplied if `software_title_id` is set. | | os_version_id | integer | query | The ID of the operating system version to filter hosts by. | | os_name | string | query | The name of the operating system to filter hosts by. `os_version` must also be specified with `os_name`. See note below for filtering Windows hosts. | | os_version | string | query | The version of the operating system to filter hosts by. `os_name` must also be specified with `os_version`. See note below for filtering Windows hosts. | | vulnerability | string | query | The cve to filter hosts by (including "cve-" prefix, case-insensitive). | | device_mapping | boolean | query | Indicates whether `device_mapping` should be included for each host. | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | | mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'manual-personal', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | connected_to_fleet | boolean | query | Filter hosts that are talking to this Fleet server for MDM features. In rare cases, hosts can be enrolled to one Fleet server but talk to a different Fleet server for MDM features. In this case, the value would be `false`. Always `false` for Linux hosts. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | | low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | | disable_failing_policies| boolean | query | If `true`, hosts will return failing policies as 0 regardless of whether there are any that failed for the host. This is meant to be used when increased performance is needed in exchange for the extra information. | | macos_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. | | bootstrap_package | string | query | _Available in Fleet Premium_. Filters the hosts by the status of the MDM bootstrap package on the host. Valid options are 'installed', 'pending', or 'failed'. | | os_settings | string | query | Filters the hosts by the status of the operating system settings applied to the hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | os_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | populate_software | string | query | If `false` (or omitted), omits installed software details for each host. If `"without_vulnerability_details"`, include a list of installed software for each host, including which CVEs apply to the installed software versions. `true` adds vulnerability description, CVSS score, and other details when using Fleet Premium. See notes below on performance. | | populate_policies | boolean | query | If `true`, the response will include policy data for each host, including Fleet-maintained policies. | | populate_users | boolean | query | If `true`, the response will include user data for each host. | | populate_labels | boolean | query | If `true`, the response will include labels for each host. | | include_device_status | boolean | query | If `true`, the response will include lock and wipe status (`mdm.device_status`) and `mdm.pending_action` information for each host. | | profile_uuid | string | query | **Requires `profile_status`**. The UUID of the profile to download. | | profile_status | string | query | **Requires `profile_uuid`**. Valid options are 'verified', 'verifying', 'pending', or 'failed'. | | dep_profile_error | boolean | query | If `true`, the response will only include Apple MDM hosts with DEP profile assignment errors(`mdm.dep_profile_error: true`). | | dep_assign_profile_response | string | query | Filters the hosts by DEP profile assignment status. Valid options are 'SUCCESS', 'FAILED', 'THROTTLED' or 'NOT_ACCESSIBLE'. Only Apple hosts which are, or were assigned to Fleet in ABM will be returned. | > `software_id` is deprecated as of Fleet 4.42. It is maintained for backwards compatibility. Please use the `software_version_id` instead. > `populate_software` returns a lot of data per host when set, and drastically more data when set to `true` on Fleet Premium. If you need vulnerability details for a large number of hosts, consider setting `populate_software` to `without_vulnerability_details` and pulling vulnerability details from the [Get vulnerability](#get-vulnerability) endpoint, as this returns details once per vulnerability rather than once per vulnerability per host. If `software_title_id` is specified, an additional top-level key `"software_title"` is returned with the software title object corresponding to the `software_title_id`. See [List software](#list-software) response payload for details about this object. If `software_version_id` is specified, an additional top-level key `"software"` is returned with the software object corresponding to the `software_version_id`. See [List software versions](#list-software-versions) response payload for details about this object. If `additional_info_filters` is not specified, no `additional` information will be returned. If `mdm_id` is specified, an additional top-level key `"mobile_device_management_solution"` is returned with the information corresponding to the `mdm_id`. If `mdm_id`, `mdm_name`, `mdm_enrollment_status`, `os_settings`, or `os_settings_disk_encryption` is specified, then Windows Servers are excluded from the results. If `munki_issue_id` is specified, an additional top-level key `munki_issue` is returned with the information corresponding to the `munki_issue_id`. If `after` is being used with `created_at` or `updated_at`, the table must be specified in `order_key`. Those columns become `h.created_at` and `h.updated_at`. If `include_device_status` is set to `true`, `device_status` and `pending_action` are included in the MDM information for each host. `device_status` indicates the current lock/wipe state of the device with possible values: `unlocked`, `locked`, `locking`, `unlocking`, `wiped`, `wiping`. `pending_action` indicates if a lock, unlock, or wipe command is pending with possible values: `lock`, `unlock`, `wipe`, or an empty string (no pending action). To filter hosts by platform (macOS, Windows, Linux), use the ["List label's hosts" API endpoint](https://fleetdm.com/docs/rest-api/rest-api#list-labels-hosts). Find the label ID by filtering in the **Hosts** page of the Fleet UI and copying the ID from the URL (for example: `7` for `/hosts/manage/labels/7`). To filter Windows hosts using `os_name` and `os_version`, set `os_name` to the full operating system name without the build number, and set `os_version` to the build number. For example, if the **Operating system** field in host details shows `Windows 11 Home Single Language 23H2 10.0.22631.5335`, query with `os_name=Microsoft Windows 11 Home Single Language 23H2` and `os_version=10.0.22631.5335`. For macOS and Linux hosts, `os_name` is the OS name (for example, `macOS` or `Ubuntu`) and `os_version` is the version number (for example, `15.2` or `20.04.3 LTS`). #### Example `GET /api/v1/fleet/hosts?page=0&per_page=100&order_key=hostname&query=2ce&populate_software=true&populate_policies=true&populate_users=true&populate_labels=true&include_device_status=true` ##### Request query parameters ```json { "page": 0, "per_page": 100, "order_key": "hostname" } ``` ##### Default response `Status: 200` ```json { "hosts": [ { "created_at": "2020-11-05T05:09:44Z", "updated_at": "2020-11-05T06:03:39Z", "id": 1, "detail_updated_at": "2020-11-05T05:09:45Z", "last_restarted_at": "2020-11-01T03:01:45Z", "software_updated_at": "2020-11-05T05:09:44Z", "label_updated_at": "2020-11-05T05:14:51Z", "policy_updated_at": "2023-06-26T18:33:15Z", "last_enrolled_at": "2023-02-26T22:33:12Z", "seen_time": "2020-11-05T06:03:39Z", "hostname": "Annas-MacBook-Pro.local", "uuid": "392547dc-0000-0000-a87a-d701ff75bc65", "platform": "darwin", "osquery_version": "5.15.0", "os_version": "macOS 15.2", "build": "24C101", "platform_like": "darwin", "code_name": "", "uptime": 8305000000000, "memory": 2084032512, "cpu_type": "arm64e", "cpu_subtype": "ARM64E", "cpu_brand": "Apple M1", "cpu_physical_cores": 8, "cpu_logical_cores": 8, "hardware_vendor": "Apple Inc.", "hardware_model": "MacBookPro17,1", "hardware_version": "", "hardware_serial": "C0124FXASD6G", "computer_name": "Anna's MacBook Pro", "timezone": null, "display_name": "Anna's MacBook Pro", "public_ip": "123.45.678.910", "primary_ip": "192.12.345.678", "primary_mac": "36:34:a5:6b:7b:5c", "distributed_interval": 10, "config_tls_refresh": 10, "logger_tls_period": 8, "status": "offline", "display_text": "Annas-MacBook-Pro.local", "team_id": null, "fleet_id": null, "team_name": null, "fleet_name": null, "gigs_disk_space_available": 174.98, "percent_disk_space_available": 71, "gigs_total_disk_space": 246, "additional": {}, "pack_stats": [ { "pack_id": 0, "pack_name": "Global", "type": "global", "query_stats": [ { "scheduled_query_name": "Get recently added or removed USB drives", "scheduled_query_id": 5535, "query_name": "Get recently added or removed USB drives", "discard_data": false, "last_fetched": null, "automations_enabled": false, "description": "Returns a record every time a USB device is plugged in or removed", "pack_name": "Global", "average_memory": 434176, "denylisted": false, "executions": 2, "interval": 86400, "last_executed": "2023-11-28T00:02:07Z", "output_size": 891, "system_time": 10, "user_time": 6, "wall_time": 0 } ] } ], "issues": { "failing_policies_count": 1, "critical_vulnerabilities_count": 2, // Fleet Premium only "total_issues_count": 3 }, "geolocation": { "country_iso": "US", "city_name": "New York", "geometry": { "type": "point", "coordinates": [40.6799, -74.0028] } }, "mdm": { "encryption_key_available": false, "enrollment_status": "Pending", "dep_profile_error": true, "name": "Fleet", "server_url": "https://example.fleetdm.com/mdm/apple/mdm", "device_status": "unlocked", "pending_action": "" }, "software": [ { "id": 1, "name": "glibc", "version": "2.12", "source": "rpm_packages", "generated_cpe": "cpe:2.3:a:gnu:glibc:2.12:*:*:*:*:*:*:*", "last_opened_at": "2021-08-18T21:14:00Z", "vulnerabilities": [ { "cve": "CVE-2009-5155", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2009-5155", "cvss_score": 7.5, // Fleet Premium only "epss_probability": 0.01537, // Fleet Premium only "cisa_known_exploit": false, // Fleet Premium only "cve_published": "2022-01-01T12:32:00Z", // Fleet Premium only "cve_description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.", // Fleet Premium only "resolved_in_version": "2.28" // Fleet Premium only } ], "installed_paths": ["/usr/lib/some-path-1"] } ], "policies": [ { "id": 1, "name": "Gatekeeper enabled", "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;", "description": "Checks if gatekeeper is enabled on macOS devices", "resolution": "Fix with these steps...", "platform": "darwin", "response": "fail", "fleet_maintained": true, "critical": false } ], "users": [ { "uid": 0, "username": "root", "type": "", "groupname": "root", "shell": "/bin/bash" }, { "uid": 1, "username": "bin", "type": "", "groupname": "bin", "shell": "/sbin/nologin" } ], "labels": [ { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 6, "name": "All Hosts", "description": "All hosts which have enrolled in Fleet", "query": "SELECT 1;", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" }, { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 9, "name": "CentOS Linux", "description": "All CentOS hosts", "query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" }, { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 12, "name": "All Linux", "description": "All Linux distributions", "query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" } ] } ] } ``` > Note: the response above assumes a [GeoIP database is configured](https://fleetdm.com/docs/deploying/configuration#geoip), otherwise the `geolocation` object won't be included. Response payload with the `mdm_id` filter provided: ```json { "hosts": [...], "mobile_device_management_solution": { "server_url": "http://some.url/mdm", "name": "MDM Vendor Name", "id": 999 } } ``` Response payload with the `munki_issue_id` filter provided: ```json { "hosts": [...], "munki_issue": { "id": 1, "name": "Could not retrieve managed install primary manifest", "type": "error" } } ``` ### Count hosts `GET /api/v1/fleet/hosts/count` #### Parameters | Name | Type | In | Description | | ----------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | order_key | string | query | What to order results by. Can be any column in the hosts table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. | | query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4`, and end user email addresses. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts in the specified fleet. | | policy_id | integer | query | The ID of the policy to filter hosts by. | | policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. | | software_version_id | integer | query | The ID of the software version to filter hosts by. | | software_title_id | integer | query | The ID of the software title to filter hosts by. | | os_version_id | integer | query | The ID of the operating system version to filter hosts by. | | os_name | string | query | The name of the operating system to filter hosts by. `os_version` must also be specified with `os_name` | | os_version | string | query | The version of the operating system to filter hosts by. `os_name` must also be specified with `os_version` | | vulnerability | string | query | The cve to filter hosts by (including "cve-" prefix, case-insensitive). | | label_id | integer | query | A valid label ID. Can only be used in combination with `order_key`, `order_direction`, `after`, `status`, `query` and `fleet_id`. | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | | mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'manual-personal', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | | low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | | macos_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. | | bootstrap_package | string | query | _Available in Fleet Premium_. Filters the hosts by the status of the MDM bootstrap package on the host. Valid options are 'installed', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | os_settings | string | query | Filters the hosts by the status of the operating system settings applied to the hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | os_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | If `additional_info_filters` is not specified, no `additional` information will be returned. If `mdm_id`, `mdm_name` or `mdm_enrollment_status` is specified, then Windows Servers are excluded from the results. #### Example `GET /api/v1/fleet/hosts/count?page=0&per_page=100&order_key=hostname&query=2ce` ##### Request query parameters ```json { "page": 0, "per_page": 100, "order_key": "hostname" } ``` ##### Default response `Status: 200` ```json { "count": 123 } ``` ### Get hosts summary Returns the count of all hosts organized by status. `online_count` includes all hosts currently enrolled in Fleet. `offline_count` includes all hosts that haven't checked into Fleet recently. `mia_count` includes all hosts that haven't been seen by Fleet in more than 30 days. `new_count` includes the hosts that have been enrolled to Fleet in the last 24 hours. `GET /api/v1/fleet/host_summary` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ---- | ------------------------------------------------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. The ID of the fleet whose host counts should be included. Defaults to all fleets. | | platform | string | query | Platform to filter by when counting. Defaults to all platforms. | | low_disk_space | integer | query | _Available in Fleet Premium_. Returns the count of hosts with less GB of disk space available than this value. Must be a number between 1-100. | #### Example `GET /api/v1/fleet/host_summary?fleet_id=1&low_disk_space=32` ##### Default response `Status: 200` ```json { "team_id": 1, "fleet_id": 1, "totals_hosts_count": 2408, "online_count": 2267, "offline_count": 141, "mia_count": 0, "missing_30_days_count": 0, "new_count": 0, "all_linux_count": 1204, "low_disk_space_count": 12, "dep_assign_error_count": 7, "builtin_labels": [ { "id": 6, "name": "All Hosts", "description": "All hosts which have enrolled in Fleet", "label_type": "builtin" }, { "id": 7, "name": "macOS", "description": "All macOS hosts", "label_type": "builtin" }, { "id": 8, "name": "Ubuntu Linux", "description": "All Ubuntu hosts", "label_type": "builtin" }, { "id": 9, "name": "CentOS Linux", "description": "All CentOS hosts", "label_type": "builtin" }, { "id": 10, "name": "MS Windows", "description": "All Windows hosts", "label_type": "builtin" }, { "id": 11, "name": "Red Hat Linux", "description": "All Red Hat Enterprise Linux hosts", "label_type": "builtin" }, { "id": 12, "name": "All Linux", "description": "All Linux distributions", "label_type": "builtin" }, { "id": 13, "name": "iOS", "description": "All iOS hosts", "label_type": "builtin" }, { "id": 14, "name": "iPadOS", "description": "All iPadOS hosts", "label_type": "builtin" }, { "id": 15, "name": "Fedora Linux", "description": "All Fedora hosts", "label_type": "builtin" }, { "id": 16, "name": "Android", "description": "All Android hosts", "label_type": "builtin" } ], "platforms": [ { "platform": "chrome", "hosts_count": 1234 }, { "platform": "darwin", "hosts_count": 1234 }, { "platform": "ios", "hosts_count": 1234 }, { "platform": "ipados", "hosts_count": 1234 }, { "platform": "rhel", "hosts_count": 1234 }, { "platform": "ubuntu", "hosts_count": 12044 }, { "platform": "windows", "hosts_count": 12044 }, { "platform": "Android", "hosts_count": 200 } ] } ``` ### Get host Returns the information of the specified host. `GET /api/v1/fleet/hosts/:id` #### Parameters | Name | Type | In | Description | |------------------|---------|-------|-----------------------------------------------------------------------------------------| | id | integer | path | **Required**. The host's id. | | exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. | | exclude_fleet_maintained_policies | boolean | query | If `true`, will omit Fleet-maintained policies from the policies list. | #### Example `GET /api/v1/fleet/hosts/121` ##### Default response `Status: 200` ```json { "host": { "created_at": "2021-08-19T02:02:22Z", "updated_at": "2021-08-19T21:14:58Z", "id": 1, "detail_updated_at": "2021-08-19T21:07:53Z", "last_restarted_at": "2020-11-01T03:01:45Z", "software_updated_at": "2020-11-05T05:09:44Z", "label_updated_at": "2021-08-19T21:07:53Z", "policy_updated_at": "2023-06-26T18:33:15Z", "last_enrolled_at": "2021-08-19T02:02:22Z", "last_mdm_checked_in_at": "2023-02-26T22:33:12Z", "last_mdm_enrolled_at": "2023-02-26T22:33:12Z", "mdm_enrollment_hardware_attested": false, "seen_time": "2021-08-19T21:14:58Z", "refetch_requested": false, "hostname": "Annas-MacBook-Pro.local", "uuid": "309a4b7d-0000-0000-8e7f-26ae0815ede8", "platform": "darwin", "osquery_version": "5.15.0", "orbit_version": "1.22.0", "fleet_desktop_version": "1.22.0", "scripts_enabled": true, "os_version": "macOS 15.2", "build": "24C101", "platform_like": "darwin", "code_name": "", "uptime": 210671000000000, "memory": 16788398080, "cpu_type": "arm64e", "cpu_subtype": "ARM64E", "cpu_brand": "Apple M1", "cpu_physical_cores": 8, "cpu_logical_cores": 8, "hardware_vendor": "Apple Inc.", "hardware_model": "MacBookPro17,1", "hardware_version": "", "hardware_serial": "C0124FXASD6G", "computer_name": "Anna's MacBook Pro", "timezone": null, "display_name": "Anna's MacBook Pro", "public_ip": "123.45.678.910", "primary_ip": "172.27.0.6", "primary_mac": "02:42:ac:1b:00:06", "distributed_interval": 10, "config_tls_refresh": 10, "logger_tls_period": 10, "team_id": null, "fleet_id": null, "pack_stats": null, "team_name": null, "fleet_name": null, "gigs_disk_space_available": 174.98, "percent_disk_space_available": 71, "gigs_total_disk_space": 246, "disk_encryption_enabled": true, "status": "online", "display_text": "Annas-MacBook-Pro.local", "additional": {}, "issues": { "failing_policies_count": 1, "critical_vulnerabilities_count": 2, // Available in Fleet Premium "total_issues_count": 3 }, "batteries": [ { "cycle_count": 999, "health": "Normal" } ], "geolocation": { "country_iso": "US", "city_name": "New York", "geometry": { "type": "point", "coordinates": [40.6799, -74.0028] } }, "maintenance_window": { "starts_at": "2024-06-18T13:27:18-04:00", "timezone": "America/New_York" }, "users": [ { "uid": 0, "username": "root", "type": "", "groupname": "root", "shell": "/bin/sh" }, { "uid": 1, "username": "annachao", "type": "", "groupname": "staff", "shell": "/bin/zsh" } ], "end_users": [ { "idp_info_updated_at": "2025-03-20T02:02:17Z", "idp_id": "f26f8649-1e25-42c5-be71-1b1e6de56d3d", "idp_username": "anna@acme.com", "idp_full_name": "Anna Chao", "idp_department": "Product", "idp_groups": [ "Product", "Designers" ], "other_emails": [ { "email": "anna@example.com", "source": "google_chrome_profiles" }, { "email": "anna@example.com", "source": "custom" } ] } ], "labels": [ { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 6, "name": "All Hosts", "description": "All hosts which have enrolled in Fleet", "query": "SELECT 1;", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" }, { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 9, "name": "macOS", "description": "All macOS hosts", "query": "select 1 from os_version where platform = 'darwin';", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" }, { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 12, "name": "Hosts with Chrome installed", "description": "", "query": "SELECT * FROM apps WHERE name LIKE \"%Chrome%\"", "platform": "", "label_type": "regular", "label_membership_type": "dynamic" } ], "packs": [], "policies": [ { "id": 2, "name": "SomeQuery2", "query": "SELECT * FROM bar;", "description": "this is another query", "resolution": "fix with these other steps...", "platform": "darwin", "response": "fail", "critical": false }, { "id": 3, "name": "SomeQuery3", "query": "SELECT * FROM baz;", "description": "", "resolution": "", "platform": "", "response": "", "critical": false }, { "id": 1, "name": "SomeQuery", "query": "SELECT * FROM foo;", "description": "this is a query", "resolution": "fix with these steps...", "platform": "windows,linux", "response": "pass", "critical": false } ], "software": [ { "id": 321, "name": "macOSApp", "version": "1.0", "source": "apps", "bundle_identifier": "com.some.app", "last_opened_at": "2021-08-18T21:14:00Z", "generated_cpe": "", "vulnerabilities": null, "installed_paths": ["/usr/lib/some-path-2"] }, { "id": 322, "name": "Windows", "version": "1.0", "source": "programs", "upgrade_code": "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", "last_opened_at": "2021-08-18T21:14:00Z", "generated_cpe": "", "vulnerabilities": null, "installed_paths": ["/usr/lib/some-path-2"] } ], "mdm": { "encryption_key_available": true, "enrollment_status": "On (manual)", "name": "Fleet", "connected_to_fleet": true, "server_url": "https://acme.com/mdm/apple/mdm", "device_status": "unlocked", "pending_action": "", "macos_settings": { "disk_encryption": "verified", "action_required": null }, "apple_settings": { "disk_encryption": "verified", "action_required": null }, "macos_setup": { "bootstrap_package_status": "installed", "detail": "", "bootstrap_package_name": "test.pkg" }, "setup_experience": { "bootstrap_package_status": "installed", "detail": "", "bootstrap_package_name": "test.pkg" }, "os_settings": { "disk_encryption": { "status": "verified", "detail": "" }, "host_name": { "status": "verified", "detail": "" } }, "profiles": [ { "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24", "name": "profile1", "status": "verifying", "operation_type": "install", "scope": "device", "managed_local_account": "", "detail": "" } ] } } } ``` `mdm.os_settings.host_name` reports the host name template enforcement status for a macOS, iOS, or iPadOS host. Its `status` is one of `pending`, `verifying`, `verified`, or `failed`, and `detail` carries the error message when the status is `failed`. The object is omitted entirely for hosts that aren't enforced (no template set on the host's fleet or on "Unassigned", non-MDM hosts, and personal (BYOD) enrollments). `browser` and `extension_for` fields are included when set and when empty. `extension_for` shows the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. > Note: the response above assumes a [GeoIP database is configured](https://fleetdm.com/docs/deploying/configuration#geoip), otherwise the `geolocation` object won't be included. > Note: `installed_paths` may be blank depending on installer package. For example, on Linux, RPM-installed packages do not provide installed path information. > Note: `signature_information` is only set for macOS (.app) applications. > Note: > - `orbit_version: null` means this agent is not a fleetd agent > - `fleet_desktop_version: null` means this agent is not a fleetd agent, or this agent is version <=1.23.0 which is not collecting the desktop version > - `fleet_desktop_version: ""` means this agent is a fleetd agent but does not have fleet desktop > - `scripts_enabled: null` means this agent is not a fleetd agent, or this agent is version <=1.23.0 which is not collecting the scripts enabled info > Note: [Get human-device mapping](https://github.com/fleetdm/fleet/blob/62dc32454f6a40e81fe229abdfc370d3bf7a56c6/docs/REST%20API/rest-api.md?plain=1#L3518) is deprecated as of Fleet 4.67.0. It is maintained for backwards compatibility. Please use the [Get host](#get-host) endpoint to get human-device mapping. > Note: For iOS, iPadOS, and Android hosts with ⁠`mdm.enrollment_status` set to "On (personal)", ⁠`hardware_serial` and ⁠`uuid` represent a temporary enrollment ID. For Android work profile, this is what Google calls an [enterprise-specific ID](https://developer.android.com/work/versions/android-12#:~:text=An%20enrollment%2Dspecific%20ID%20provides%20a%20unique%20ID%20that%20identifies%20the%20work%20profile%20enrollment%20in%20a%20particular%20organization%2C%20and%20will%20remain%20stable%20across%20factory%20resets). ### Get host by identifier Returns the information of the host specified using the `hostname`, `uuid`, or `hardware_serial` as an identifier. If `hostname` is specified when there is more than one host with the same hostname, the endpoint returns the first matching host. > In Fleet, hostnames are fully qualified domain names (FQDNs). `hostname` (e.g. johns-macbook-air.local) is **not** the same as `display_name` (e.g. John's MacBook Air). `GET /api/v1/fleet/hosts/identifier/:identifier` #### Parameters | Name | Type | In | Description | | ---------- | ----------------- | ---- | ------------------------------------------------------------------ | | identifier | string | path | **Required**. The host's `hostname`, `uuid`, or `hardware_serial`. | | exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. | | exclude_fleet_maintained_policies | boolean | query | If `true`, will omit Fleet-maintained policies from the policies list. | #### Example `GET /api/v1/fleet/hosts/identifier/392547dc-0000-0000-a87a-d701ff75bc65` ##### Default response `Status: 200` ```json { "host": { "created_at": "2022-02-10T02:29:13Z", "updated_at": "2022-10-14T17:07:11Z", "id": 33, "detail_updated_at": "2022-10-14T17:07:12Z", "label_updated_at": "2022-10-14T17:07:12Z", "policy_updated_at": "2022-10-14T17:07:12Z", "last_enrolled_at": "2022-02-10T02:29:13Z", "last_mdm_checked_in_at": "2023-02-26T22:33:12Z", "last_mdm_enrolled_at": "2023-02-26T22:33:12Z", "mdm_enrollment_hardware_attested": false, "software_updated_at": "2020-11-05T05:09:44Z", "seen_time": "2022-10-14T17:45:41Z", "refetch_requested": false, "hostname": "23cfc9caacf0", "uuid": "392547dc-0000-0000-a87a-d701ff75bc65", "platform": "ubuntu", "osquery_version": "5.5.1", "os_version": "Ubuntu 20.04.3 LTS", "build": "", "platform_like": "debian", "code_name": "focal", "uptime": 20807520000000000, "memory": 1024360448, "cpu_type": "x86_64", "cpu_subtype": "63", "cpu_brand": "DO-Regular", "cpu_physical_cores": 1, "cpu_logical_cores": 1, "hardware_vendor": "", "hardware_model": "", "hardware_version": "", "hardware_serial": "", "computer_name": "23cfc9caacf0", "timezone": null, "public_ip": "", "primary_ip": "172.27.0.6", "primary_mac": "02:42:ac:1b:00:06", "distributed_interval": 10, "config_tls_refresh": 60, "logger_tls_period": 10, "team_id": 2, "fleet_id": 2, "team_name": null, "fleet_name": null, "gigs_disk_space_available": 19.29, "percent_disk_space_available": 74, "gigs_total_disk_space": 192, "issues": { "failing_policies_count": 1, "critical_vulnerabilities_count": 2, // Fleet Premium only "total_issues_count": 3 }, "batteries": [ { "cycle_count": 999, "health": "Normal" } ], "geolocation": { "country_iso": "US", "city_name": "New York", "geometry": { "type": "point", "coordinates": [40.6799, -74.0028] } }, "pack_stats": [ { "pack_id": 1, "pack_name": "Global", "type": "global", "query_stats": [ { "scheduled_query_name": "Get running processes (with user_name)", "scheduled_query_id": 49, "query_name": "Get running processes (with user_name)", "pack_name": "Global", "pack_id": 1, "average_memory": 260000, "denylisted": false, "executions": 1, "interval": 86400, "last_executed": "2022-10-14T10:00:01Z", "output_size": 198, "system_time": 20, "user_time": 80, "wall_time": 0 } ] } ], "labels": [ { "created_at": "2021-09-14T05:11:02Z", "updated_at": "2021-09-14T05:11:02Z", "id": 12, "name": "All Linux", "description": "All Linux distributions", "query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" } ], "packs": [ { "created_at": "2021-09-17T05:28:54Z", "updated_at": "2021-09-17T05:28:54Z", "id": 1, "name": "Global", "description": "Global pack", "disabled": false, "type": "global", "labels": null, "label_ids": null, "hosts": null, "host_ids": null, "teams": null, "fleet": null, "team_ids": null, "fleet_ids": null } ], "policies": [ { "id": 142, "name": "Full disk encryption enabled (macOS)", "query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT '' AND filevault_status = 'on' LIMIT 1;", "description": "Checks to make sure that full disk encryption (FileVault) is enabled on macOS devices.", "author_id": 31, "author_name": "", "author_email": "", "team_id": null, "fleet_id": null, "resolution": "To enable full disk encryption, on the failing device, select System Preferences > Security & Privacy > FileVault > Turn On FileVault.", "platform": "darwin,linux", "created_at": "2022-09-02T18:52:19Z", "updated_at": "2022-09-02T18:52:19Z", "response": "fail", "critical": false } ], "software": [ { "id": 16923, "name": "Automat", "version": "0.8.0", "source": "python_packages", "browser": "", "extension_for": "", "generated_cpe": "", "vulnerabilities": null, "installed_paths": ["/usr/lib/some_path/"] } ], "mdm": { "encryption_key_available": false, "enrollment_status": null, "name": "", "server_url": null, "device_status": "unlocked", "pending_action": "lock", "macos_settings": { "disk_encryption": null, "action_required": null }, "apple_settings": { "disk_encryption": null, "action_required": null }, "macos_setup": { "bootstrap_package_status": "installed", "detail": "" }, "setup_experience": { "bootstrap_package_status": "installed", "detail": "" }, "os_settings": { "disk_encryption": { "status": null, "detail": "" } }, "profiles": [ { "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24", "name": "profile1", "status": "verifying", "operation_type": "install", "scope": "device", "managed_local_account": "", "detail": "" } ] } } } ``` > Note: the response above assumes a [GeoIP database is configured](https://fleetdm.com/docs/deploying/configuration#geoip), otherwise the `geolocation` object won't be included. > Note: `installed_paths` may be blank depending on installer package. For example, on Linux, RPM-installed packages do not provide installed path information. `browser` and `extension_for` fields are included when set and when empty. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. ### Get host by Fleet Desktop token > If you're hitting this endpoint often (e.g. every hour) for a large number of hosts (e.g. 1k+) the best practice is to set the `exclude_software` to `true` to prevent overloading the Fleet server. Returns a subset of information about the host specified by `token`. To get all information about a host, use the ["Get host"](#get-host) endpoint. This is the API route used by the **My device** page in Fleet Desktop to display information about the host to the end user. This endpoint doesn't require API token authentication. Authentication on macOS, Windows, and Linux is enforced by generating a [random UUID that rotates hourly](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). For iOS and iPadOS, this is the host's hardware UUID. `GET /api/v1/fleet/device/:token` ##### Parameters | Name | Type | In | Description | | ----- | ------ | ---- | ---------------------------------- | | token | string | path | The host's [Fleet Desktop token](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). For macOS, Windows, and Linux, this is a random UUID that rotates hourly. For iOS and iPadOS, this is the host's hardware UUID. | | exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. | #### Request headers This endpoint accepts the `X-Client-Cert-Serial` header for authentication in addition to token authentication. The `Authorization` header must be formatted as follows: ``` X-Client-Cert-Serial: ``` ##### Example `GET /api/v1/fleet/device/abcdef012456789` ##### Default response `Status: 200` ```json { "host": { "created_at": "2021-08-19T02:02:22Z", "updated_at": "2021-08-19T21:14:58Z", "id": 1, "detail_updated_at": "2021-08-19T21:07:53Z", "label_updated_at": "2021-08-19T21:07:53Z", "last_enrolled_at": "2021-08-19T02:02:22Z", "last_mdm_checked_in_at": "2023-02-26T22:33:12Z", "last_mdm_enrolled_at": "2023-02-26T22:33:12Z", "mdm_enrollment_hardware_attested": false, "seen_time": "2021-08-19T21:14:58Z", "refetch_requested": false, "hostname": "Annas-MacBook-Pro.local", "uuid": "309a4b7d-0000-0000-8e7f-26ae0815ede8", "platform": "darwin", "osquery_version": "5.15.0", "os_version": "macOS 15.2", "build": "24C101", "platform_like": "darwin", "code_name": "", "uptime": 210671000000000, "memory": 16788398080, "cpu_type": "arm64e", "cpu_subtype": "ARM64E", "cpu_brand": "Apple M1", "cpu_physical_cores": 8, "cpu_logical_cores": 8, "hardware_vendor": "Apple Inc.", "hardware_model": "MacBookPro17,1", "hardware_version": "", "hardware_serial": "", "computer_name": "Anna's MacBook Pro", "timezone": null, "display_name": "Anna's MacBook Pro", "public_ip": "123.45.678.910", "primary_ip": "192.12.345.678", "primary_mac": "36:34:a5:6b:7b:5c", "distributed_interval": 10, "config_tls_refresh": 10, "logger_tls_period": 10, "team_id": null, "fleet_id": null, "pack_stats": null, "team_name": null, "fleet_name": null, "additional": {}, "gigs_disk_space_available": 174.98, "percent_disk_space_available": 71, "gigs_total_disk_space": 246, "disk_encryption_enabled": true, "dep_assigned_to_fleet": false, "status": "online", "display_text": "Annas-MacBook-Pro.local", "self_service": true, "org_logo_url_dark_mode": "https://example.com/logo.png", "org_logo_url_light_mode": "https://example.com/logo-light.png", "org_logo_url": "https://example.com/logo.png", "org_logo_url_light_background": "https://example.com/logo-light.png", "conditional_access_bypassed": false, "license": { "tier": "free", "expiration": "2031-01-01T00:00:00Z" }, "global_config": { "mdm": { "enabled_and_configured": false } }, "batteries": [ { "cycle_count": 999, "health": "Good" } ], "users": [ { "uid": 0, "username": "root", "type": "", "groupname": "root", "shell": "/bin/sh" }, { "uid": 1, "username": "annachao", "type": "", "groupname": "staff", "shell": "/bin/zsh" } ], "labels": [ { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 6, "name": "All Hosts", "description": "All hosts which have enrolled in Fleet", "query": "SELECT 1;", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" }, { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 9, "name": "macOS", "description": "All macOS hosts", "query": "select 1 from os_version where platform = 'darwin';", "platform": "", "label_type": "builtin", "label_membership_type": "dynamic" }, { "created_at": "2021-08-19T02:02:17Z", "updated_at": "2021-08-19T02:02:17Z", "id": 12, "name": "Hosts with Chrome installed", "description": "", "query": "SELECT * FROM apps WHERE name LIKE \"%Chrome%\"", "platform": "", "label_type": "regular", "label_membership_type": "dynamic" } ], "software": [ { "id": 321, "name": "SomeApp.app", "version": "1.0", "source": "apps", "browser": "", "extension_for": "", "bundle_identifier": "com.some.app", "last_opened_at": "2021-08-18T21:14:00Z", "generated_cpe": "", "vulnerabilities": null } ], "packs": [], "mdm": { "encryption_key_available": true, "enrollment_status": "On (manual)", "name": "Fleet", "connected_to_fleet": true, "server_url": "https://acme.com/mdm/apple/mdm", "macos_settings": { "disk_encryption": "verified", "action_required": null }, "apple_settings": { "disk_encryption": "verified", "action_required": null }, "macos_setup": { "bootstrap_package_status": "installed", "detail": "", "bootstrap_package_name": "test.pkg" }, "setup_experience": { "bootstrap_package_status": "installed", "detail": "", "bootstrap_package_name": "test.pkg" }, "os_settings": { "disk_encryption": { "status": "verified", "detail": "" } }, "profiles": [ { "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24", "name": "profile1", "status": "verifying", "operation_type": "install", "scope": "device", "managed_local_account": "", "detail": "" } ] } } } ``` `browser` and `extension_for` fields are included when set and when empty. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. ### Delete host Deletes the specified host from Fleet. Note that a deleted host will fail authentication with the previous node key, and in most osquery configurations will attempt to re-enroll automatically. If the host still has a valid enroll secret, it will re-enroll successfully. `DELETE /api/v1/fleet/hosts/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's id. | #### Example `DELETE /api/v1/fleet/hosts/121` ##### Default response `Status: 200` ### Refetch host Flags the host details, labels and policies to be refetched the next time the host checks in. Note that we cannot be certain when the host will actually check in. Further requests to the host APIs will indicate that the refetch has been requested through the `refetch_requested` field on the host object. `POST /api/v1/fleet/hosts/:id/refetch` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's id. | #### Example `POST /api/v1/fleet/hosts/121/refetch` ##### Default response `Status: 200` ### Refetch host by Fleet Desktop token Same as [Refetch host](#refetch-host) except with the Fleet Desktop token instead the host ID. `POST /api/v1/fleet/device/:token/refetch` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | token | string | path | **Required**. The host's [Fleet Desktop token](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). | #### Example `POST /api/v1/fleet/device/6d3e95ca-6783-4d0d-93b8-a5ffdb207867/refetch` ##### Default response `Status: 200` ### Update hosts' fleet _Available in Fleet Premium_ `POST /api/v1/fleet/hosts/transfer` #### Parameters | Name | Type | In | Description | | ------- | ------- | ---- | ----------------------------------------------------------------------- | | fleet_id | integer | body | **Required**. The ID of the fleet you'd like to assign the host(s) to. | | hosts | array | body | **Required**. A list of host IDs. | #### Example `POST /api/v1/fleet/hosts/transfer` ##### Request body ```json { "team_id": 1, "fleet_id": 1, "hosts": [3, 2, 4, 6, 1, 5, 7] } ``` ##### Default response `Status: 200` ### Update hosts' fleet by filter _Available in Fleet Premium_ `POST /api/v1/fleet/hosts/transfer/filter` #### Parameters | Name | Type | In | Description | | ------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fleet_id | integer | body | **Required**. The ID of the fleet you'd like to assign the host(s) to. | | filters | object | body | **Required**. See [filters](#filters) | ##### Filters | Name | Type | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------- | | query | string | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, and `ipv4`. | | status | string | Host status. Can either be `new`, `online`, `offline`, `mia` or `missing`. | | label_id | number | ID of a label to filter by. | | fleet_id | number | ID of the fleet to filter by. | > Note: `label_id` and `status` filters cannot be used at the same time. #### Example `POST /api/v1/fleet/hosts/transfer/filter` ##### Request body ```json { "team_id": 1, "fleet_id": 1, "filters": { "status": "online", "team_id": 2, "fleet_id": 2, } } ``` ##### Default response `Status: 200` ### Turn off host's MDM Turns off MDM for the specified macOS, iOS, iPadOS, or Android host. > On BYOD Android (work profile), Fleet sends a wipe command via the Android Management API. Unlike the [delete device command](https://developers.google.com/android/management/deprovision-device) in the Android Management API, the wipe command does not expire after 30 days. That way, Fleet makes sure that the work profile is wiped even if the host is offline for more than 30 days. `DELETE /api/v1/fleet/hosts/:id/mdm` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ------------------------------------- | | id | integer | path | **Required.** The host's ID in Fleet. | #### Example `DELETE /api/v1/fleet/hosts/42/mdm` ##### Default response `Status: 204` ### Batch-delete hosts Delete hosts selected by filter or ids. `POST /api/v1/fleet/hosts/delete` #### Parameters | Name | Type | In | Description | | ------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ids | array | body | A list of the host IDs you'd like to delete. Required if `filters` not specified. Only one of `ids` or `filters` may be included in the request. | | filters | object | body | **Required**. See [filters](#filters2). Required if `ids` not specified. Only one of `ids` or `filters` may be included in the request. | ##### Filters | Name | Type | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------- | | query | string | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, and `ipv4`. | | status | string | Host status. Can either be `new`, `online`, `offline`, `mia` or `missing`. | | label_id | number | ID of a label to filter by. | | fleet_id | number | ID of the fleet to filter by. | > Notes: `label_id` and `status` filters cannot be used at the same time. Request (using `ids`): ```json { "ids": [1] } ``` Request (using `filters`): ```json { "filters": { "status": "online", "label_id": 1, "team_id": 1, "fleet_id": 1, "query": "abc" } } ``` Request (`filters` is specified and empty, to delete all hosts): ```json { "filters": {} } ``` #### Example `POST /api/v1/fleet/hosts/delete` ##### Request body ```json { "filters": { "status": "online", "team_id": 1, "fleet_id": 1 } } ``` ##### Default response `Status: 200` ### Update human-device mapping `PUT /api/v1/fleet/hosts/:id/device_mapping` Updates the email for the data source in the human-device mapping. This source can only have one email. #### Parameters | Name | Type | In | Description | | ---------- | ----------------- | ---- | ----------------------------------------------------------------------------- | | id | integer | path | **Required**. The host's `id`. | | email | string | body | **Required**. The custom email. | | source | string | body | The data source to override. Either `"custom"` or `"idp"`. If `"idp"`, this will update the end user's `"idp_username"`. (Defaults to `"custom"`.) #### Example `PUT /api/v1/fleet/hosts/1/device_mapping` ##### Request body ```json { "email": "user@example.com" } ``` ##### Default response `Status: 200` ```json { "host_id": 1, "device_mapping": [ { "email": "user@example.com", "source": "mdm_idp_accounts" }, { "email": "user@example.com", "source": "google_chrome_profiles" }, { "email": "user@example.com", "source": "custom" } ] } ``` ### Get host's device health report Retrieves information about a single host's device health. This report includes a subset of host vitals, and simplified policy and vulnerable software information. Data is cached to preserve performance. To get all up-to-date information about a host, use the ["Get host"](#get-host) endpoint. `GET /api/v1/fleet/hosts/:id/health` #### Parameters | Name | Type | In | Description | | ---------- | ----------------- | ---- | ----------------------------------------------------------------------------- | | id | integer | path | **Required**. The host's `id`. | #### Example `GET /api/v1/fleet/hosts/1/health` ##### Default response `Status: 200` ```json { "host_id": 1, "health": { "updated_at": "2023-09-16T18:52:19Z", "os_version": "CentOS Linux 8.3.2011", "disk_encryption_enabled": true, "failing_policies_count": 1, "failing_critical_policies_count": 1, // Fleet Premium only "failing_policies": [ { "id": 123, "name": "Google Chrome is up to date", "critical": true, // Fleet Premium only "resolution": "Follow the Update Google Chrome instructions here: https://support.google.com/chrome/answer/95414?sjid=6534253818042437614-NA" } ], "vulnerable_software": [ { "id": 321, "name": "Firefox.app", "version": "116.0.3" } ] } } ``` ### Get host's device page URL Retrieves the end user url for the host's **My device** page. `GET /api/v1/fleet/hosts/:id/device_url` #### Parameters | Name | Type | In | Description | | ---------- | ----------------- | ---- | ----------------------------------------------------------------------------- | | id | integer | path | **Required**. The host's `id`. | #### Example `GET /api/v1/fleet/hosts/1/device_url` ##### Default response `Status: 200` ```json { "host_id": 1, "device_url": "example.com/device/device_id" } ``` --- ### Get host's mobile device management (MDM) information Currently supports Windows and macOS. Retrieves a host's MDM enrollment status and MDM server URL. If the host exists but is not enrolled to an MDM server, then this API returns `null`. `GET /api/v1/fleet/hosts/:id/mdm` #### Parameters | Name | Type | In | Description | | ------- | ------- | ---- | -------------------------------------------------------------------------------- | | id | integer | path | **Required** The id of the host to get the details for | #### Example `GET /api/v1/fleet/hosts/32/mdm` ##### Default response `Status: 200` ```json { "enrollment_status": "On (automatic)", "server_url": "some.mdm.com", "name": "Some MDM", "id": 3 } ``` --- ### Get mobile device management (MDM) status Currently supports Windows and macOS. Retrieves MDM enrollment summary. Windows servers are excluded from the aggregated data. `GET /api/v1/fleet/hosts/summary/mdm` #### Parameters | Name | Type | In | Description | | -------- | ------- | ----- | -------------------------------------------------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. Filter by fleet. | | platform | string | query | Filter by platform ("windows" or "darwin") | A `fleet_id` of `0` returns the statistics for hosts that are "Unassigned". A `null` or missing `fleet_id` returns statistics for all hosts on all fleets. #### Example `GET /api/v1/fleet/hosts/summary/mdm?fleet_id=1&platform=windows` ##### Default response `Status: 200` ```json { "counts_updated_at": "2021-03-21T12:32:44Z", "mobile_device_management_enrollment_status": { "enrolled_manual_hosts_count": 10, "enrolled_automated_hosts_count": 200, "enrolled_personal_hosts_count": 30, "unenrolled_hosts_count": 0, "hosts_count": 240 }, "mobile_device_management_solution": [ { "id": 2, "name": "Solution1", "server_url": "solution1.com", "hosts_count": 1 }, { "id": 3, "name": "Solution2", "server_url": "solution2.com", "hosts_count": 1 } ] } ``` --- ### Get host's mobile device management (MDM) and Munki information Retrieves a host's MDM enrollment status, MDM server URL, and Munki version. `GET /api/v1/fleet/hosts/:id/macadmins` #### Parameters | Name | Type | In | Description | | ------- | ------- | ---- | -------------------------------------------------------------------------------- | | id | integer | path | **Required** The id of the host to get the details for | #### Example `GET /api/v1/fleet/hosts/32/macadmins` ##### Default response `Status: 200` ```json { "macadmins": { "munki": { "version": "1.2.3" }, "munki_issues": [ { "id": 1, "name": "Could not retrieve managed install primary manifest", "type": "error", "created_at": "2022-08-01T05:09:44Z" }, { "id": 2, "name": "Could not process item Figma for optional install. No pkginfo found in catalogs: release", "type": "warning", "created_at": "2022-08-01T05:09:44Z" } ], "mobile_device_management": { "enrollment_status": "On (automatic)", "server_url": "http://some.url/mdm", "name": "MDM Vendor Name", "id": 999 } } } ``` --- ### Get hosts' aggregate mobile device management (MDM) and Munki information Currently supported only on macOS. Retrieves MDM enrollment status and Munki versions, aggregated across all hosts. `GET /api/v1/fleet/macadmins` #### Parameters | Name | Type | In | Description | | ------- | ------- | ----- | ---------------------------------------------------------------------------------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. Filters the aggregate host information to only include hosts in the specified fleet. | A `fleet_id` of `0` returns the statistics for hosts that are "Unassigned". A `null` or missing `fleet_id` returns statistics for all hosts on all fleets. #### Example `GET /api/v1/fleet/macadmins` ##### Default response `Status: 200` ```json { "macadmins": { "counts_updated_at": "2021-03-21T12:32:44Z", "munki_versions": [ { "version": "5.5", "hosts_count": 8360 }, { "version": "5.4", "hosts_count": 1700 }, { "version": "5.3", "hosts_count": 400 }, { "version": "5.2.3", "hosts_count": 112 }, { "version": "5.2.2", "hosts_count": 50 } ], "munki_issues": [ { "id": 1, "name": "Could not retrieve managed install primary manifest", "type": "error", "hosts_count": 2851 }, { "id": 2, "name": "Could not process item Figma for optional install. No pkginfo found in catalogs: release", "type": "warning", "hosts_count": 1983 } ], "mobile_device_management_enrollment_status": { "enrolled_manual_hosts_count": 124, "enrolled_automated_hosts_count": 124, "unenrolled_hosts_count": 112 }, "mobile_device_management_solution": [ { "id": 1, "name": "SimpleMDM", "hosts_count": 8360, "server_url": "https://a.simplemdm.com/mdm" }, { "id": 2, "name": "Intune", "hosts_count": 1700, "server_url": "https://enrollment.manage.microsoft.com" } ] } } ``` ### Get host's software `GET /api/v1/fleet/hosts/:id/software` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's ID. | | query | string | query | Search query keywords. Searchable fields include `name`. | | available_for_install | boolean | query | If `true` or `1`, only list software that is available for install (added by the user). Default is `false`. | | self_service | boolean | query | If `true` or `1`, only lists self-service software. Default is `false`. | | vulnerable | boolean | query | If `true` or `1`, only list software that have vulnerabilities. Default is `false`. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page.| | order_key | string | query | What to order results by. Options include `"name"`. Default is `"name"`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | min_cvss_score | integer | query | _Available in Fleet Premium_. Filters to include only software with vulnerabilities that have a CVSS version 3.x base score higher than the specified value. | | max_cvss_score | integer | query | _Available in Fleet Premium_. Filters to only include software with vulnerabilities that have a CVSS version 3.x base score lower than what's specified. | | exploit | boolean | query | _Available in Fleet Premium_. If `true`, filters to only include software with vulnerabilities that have been actively exploited in the wild (`cisa_known_exploit: true`). Default is `false`. | | macos_applications | boolean | query | If `true`, filters to only include software at the top level of the `/Applications` folder. This parameter applies only to macOS hosts, and is ignored for hosts on other platforms. Default is `false`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | On macOS hosts, `last_opened_at` is supported for software from the `apps` source and is the last open time of the most recently installed version of the software. After an update, it may be empty until the software is opened again. On Windows hosts, `last_opened_at` is supported for software from the `programs` source. On Linux hosts, `last_opened_at` is supported for software from the `deb_packages` and `rpm_packages` sources. On Windows and Linux hosts, it represents the last open time of any version. Currently, `hash_sha256`, `executable_sha256`, and `executable_path` are only supported for macOS software from the `apps` source. `hash_sha256` is the [`cdhash_sha256`](https://fleetdm.com/tables/codesign). #### Example `GET /api/v1/fleet/hosts/123/software` ##### Default response `Status: 200` ```json { "count": 1, "software": [ { "id": 936, "name": "Google Chrome", "icon_url": null, "source": "apps", "extension_for": "", "status": null, "installed_versions": [ { "version": "149.0.7827.54", "bundle_identifier": "com.google.Chrome", "vulnerabilities": null, "installed_paths": [ "/Applications/Google Chrome.app" ], "signature_information": [ { "installed_path": "/Applications/Google Chrome.app", "team_identifier": "EQHXZ8M8AV", "hash_sha256": "ce484e67c58b18313382e9fe2e225df52fb20b5f", "executable_sha256": null, "executable_path": null } ], "last_opened_at": "2026-06-04T15:22:36Z" } ], "display_name": "", "software_package": { "name": "GoogleChrome.pkg", "automatic_install_policies": null, "version": "149.0.7827.54", "platform": "darwin", "self_service": true, "last_install": null, "last_uninstall": null, "package_url": null, "categories": [ "Browsers" ] }, "app_store_app": null } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Get host's software by Fleet Desktop token `GET /api/v1/fleet/device/:token/software` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | token | string | path | **Required.** The host's [Fleet Desktop token](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). | | query | string | query | Search query keywords. Searchable fields include `name`. | | available_for_install | boolean | query | If `true` or `1`, only list software that is available for install (added by the user). Default is `false`. | | self_service | boolean | query | If `true` or `1`, only lists self-service software. Default is `false`. | | vulnerable | boolean | query | If `true` or `1`, only list software that have vulnerabilities. Default is `false`. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page.| | order_key | string | query | What to order results by. Options include `"name"`. Default is `"name"`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | min_cvss_score | integer | query | _Available in Fleet Premium_. Filters to include only software with vulnerabilities that have a CVSS version 3.x base score higher than the specified value. | | max_cvss_score | integer | query | _Available in Fleet Premium_. Filters to only include software with vulnerabilities that have a CVSS version 3.x base score lower than what's specified. | | exploit | boolean | query | _Available in Fleet Premium_. If `true`, filters to only include software with vulnerabilities that have been actively exploited in the wild (`cisa_known_exploit: true`). Default is `false`. | On macOS hosts, `last_opened_at` is supported for software from the `apps` source and is the last open time of the most recently installed version of the software. After an update, it may be empty until the software is opened again. On Windows hosts, `last_opened_at` is supported for software from the `programs` source. On Linux hosts, `last_opened_at` is supported for software from the `deb_packages` and `rpm_packages` sources. On Windows and Linux hosts, it represents the last open time of any version. Currently, `hash_sha256`, `executable_sha256`, and `executable_path` are only supported for macOS software from the `apps` source. `hash_sha256` is the [`cdhash_sha256`](https://fleetdm.com/tables/codesign). #### Example `GET /api/v1/fleet/device/:token/software` ##### Default response `Status: 200` ```json { "count": 1, "software": [ { "id": 936, "name": "Google Chrome", "icon_url": null, "source": "apps", "extension_for": "", "status": null, "installed_versions": [ { "version": "149.0.7827.54", "bundle_identifier": "com.google.Chrome", "vulnerabilities": null, "installed_paths": [ "/Applications/Google Chrome.app" ], "signature_information": [ { "installed_path": "/Applications/Google Chrome.app", "team_identifier": "EQHXZ8M8AV", "hash_sha256": "ce484e67c58b18313382e9fe2e225df52fb20b5f", "executable_sha256": null, "executable_path": null } ], "last_opened_at": "2026-06-04T15:22:36Z" } ], "display_name": "", "software_package": { "name": "GoogleChrome.pkg", "automatic_install_policies": null, "version": "149.0.7827.54", "platform": "darwin", "self_service": true, "last_install": null, "last_uninstall": null, "package_url": null, "categories": [ "Browsers" ] }, "app_store_app": null } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Get hosts report in CSV Returns the list of hosts corresponding to the search criteria in CSV format, ready for download when requested by a web browser. `GET /api/v1/fleet/hosts/report` #### Parameters | Name | Type | In | Description | | ----------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | format | string | query | **Required**, must be "csv" (only supported format for now). | | columns | string | query | Comma-delimited list of columns to include in the report (returns all columns if none is specified). | | order_key | string | query | What to order results by. Can be any column in the hosts table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. | | query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4`, and end user email addresses. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts in the specified fleet. | | policy_id | integer | query | The ID of the policy to filter hosts by. | | policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. **Note: If `policy_id` is specified _without_ including `policy_response`, this will also return hosts where the policy is not configured to run or failed to run.** | | software_version_id | integer | query | The ID of the software version to filter hosts by. | | software_title_id | integer | query | The ID of the software title to filter hosts by. | | os_version_id | integer | query | The ID of the operating system version to filter hosts by. | | os_name | string | query | The name of the operating system to filter hosts by. `os_version` must also be specified with `os_name` | | os_version | string | query | The version of the operating system to filter hosts by. `os_name` must also be specified with `os_version` | | vulnerability | string | query | The cve to filter hosts by (including "cve-" prefix, case-insensitive). | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | | mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'manual-personal', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only hosts that are "Unassigned".** | | munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | | low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | | label_id | integer | query | A valid label ID. Can only be used in combination with `order_key`, `order_direction`, `status`, `query` and `fleet_id`. | | bootstrap_package | string | query | _Available in Fleet Premium_. Filters the hosts by the status of the MDM bootstrap package on the host. Valid options are 'installed', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only hosts that are "Unassigned".** | | disable_failing_policies | boolean | query | If `true`, hosts will return failing policies as 0 (returned as the `issues` column) regardless of whether there are any that failed for the host. This is meant to be used when increased performance is needed in exchange for the extra information. | If `mdm_id`, `mdm_name` or `mdm_enrollment_status` is specified, then Windows Servers are excluded from the results. #### Example `GET /api/v1/fleet/hosts/report?software_id=123&format=csv&columns=hostname,primary_ip,platform` ##### Default response `Status: 200` ```csv created_at,updated_at,id,detail_updated_at,label_updated_at,policy_updated_at,last_enrolled_at,seen_time,refetch_requested,hostname,uuid,platform,osquery_version,os_version,build,platform_like,code_name,uptime,memory,cpu_type,cpu_subtype,cpu_brand,cpu_physical_cores,cpu_logical_cores,hardware_vendor,hardware_model,hardware_version,hardware_serial,computer_name,primary_ip_id,primary_ip,primary_mac,distributed_interval,config_tls_refresh,logger_tls_period,team_name,fleet_name,gigs_disk_space_available,percent_disk_space_available,gigs_total_disk_space,issues,device_mapping,status,display_text 2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,1,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,false,foo.local0,a4fc55a1-b5de-409c-a2f4-441f564680d3,debian,,,,,,0s,0,,,,0,0,,,,,,,,,0,0,0,,,0,0,0,0,,,, 2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:22:56Z,false,foo.local1,689539e5-72f0-4bf7-9cc5-1530d3814660,rhel,,,,,,0s,0,,,,0,0,,,,,,,,,0,0,0,,,0,0,0,0,,,, 2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,3,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:21:56Z,false,foo.local2,48ebe4b0-39c3-4a74-a67f-308f7b5dd171,linux,,,,,,0s,0,,,,0,0,,,,,,,,,0,0,0,,,0,0,0,0,,,, ``` ### Get host's disk encryption key Retrieves the disk encryption key for a host. The host will only return a key if its disk encryption status is "Verified." Get hosts' disk encryption statuses using the [List hosts endpoint](#list-hosts) and `os_settings_disk_encryption` parameter. `GET /api/v1/fleet/hosts/:id/encryption_key` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ------------------------------------------------------------------ | | id | integer | path | **Required** The id of the host to get the disk encryption key for. | #### Example `GET /api/v1/fleet/hosts/8/encryption_key` ##### Default response `Status: 200` ```json { "host_id": 8, "encryption_key": { "key": "5ADZ-HTZ8-LJJ4-B2F8-JWH3-YPBT", "updated_at": "2022-12-01T05:31:43Z" } } ``` ### Get host's Recovery Lock password Retrieves the Recovery Lock password for a host. The host will only return a password if its Recovery Lock password status is "Verified." `GET /api/v1/fleet/hosts/:id/recovery_lock_password` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------------------------------------------------- | | id | integer | path | **Required** The id of the host to get the Recovery Lock password for. | #### Example `GET /api/v1/fleet/hosts/8/recovery_lock_password` ##### Default response `Status: 200` ```json { "host_id": 8, "recovery_lock_password": { "password": "test-123", "updated_at": "2026-02-01T05:31:43Z" } } ``` ### Rotate host's Recovery Lock password _Available in Fleet Premium_ Rotates the Recovery Lock password for a host. `POST /api/v1/fleet/hosts/:id/recovery_lock_password/rotate` #### Parameters | Name | Type | In | Description | | ----------------------------- | ------ | ---- | -------------------------------------------------------------------------------------- | | id | integer | path | The host ID to rotate Recovery Lock password for. | #### Example `POST /api/v1/fleet/hosts/123/recovery_lock_password/rotate` ##### Default response `Status: 200` ### Get host's certificates Available for macOS, iOS, iPadOS, and Windows hosts only. Requires Fleet's MDM to be [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup). Retrieves the certificates installed on a host. For macOS hosts, certificates from MDM-delivered profiles containing an ACME payload are retrieved via the MDM `CertificateList` command on each profile install and re-install (not on a recurring cadence). Hardware-bound ACME certificates that aren't visible to osquery first appear in the response after the host installs or re-installs the delivering profile. `GET /api/v1/fleet/hosts/:id/certificates` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's id. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page.| | order_key | string | query | What to order results by. Options include `common_name` and `not_valid_after`. Default is `common_name` | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/hosts/8/certificates` ##### Default response `Status: 200` ```json { "certificates": [ { "id": 3, "not_valid_after": "2021-08-19T02:02:17Z", "not_valid_before": "2021-08-19T02:02:17Z", "certificate_authority": true, "common_name": "FleetDM", "key_algorithm": "rsaEncryption", "key_strength": 2048, "key_usage": "CRL Sign, Key Cert Sign", "serial": 1, "signing_algorithm": "sha256WithRSAEncryption", "subject": { "country": "US", "organization": "Fleet Device Management Inc.", "organizational_unit": "Fleet Device Management Inc.", "common_name": "FleetDM" }, "issuer": { "country": "US", "organization": "Fleet Device Management Inc.", "organizational_unit": "Fleet Device Management Inc.", "common_name": "FleetDM" }, "source": "system", "username": "" } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Get host's OS settings (configuration profile) Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup). Retrieves a list of the configuration profiles assigned to a host. `GET /api/v1/fleet/hosts/:id/configuration_profiles` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------- | | id | integer | path | **Required**. The ID of the host | #### Example `GET /api/v1/fleet/hosts/8/configuration_profiles` ##### Default response `Status: 200` ```json { "host_id": 8, "profiles": [ { "profile_uuid": "bc84dae7-396c-4e10-9d45-5768bce8b8bd", "team_id": 0, "fleet_id": 0, "name": "Example profile", "identifier": "com.example.profile", "created_at": "2023-03-31T00:00:00Z", "updated_at": "2023-03-31T00:00:00Z", "checksum": "dGVzdAo=" } ] } ``` ### Lock host _Available in Fleet Premium_ Sends a command to lock the specified macOS, iOS, iPadOS, Linux, Windows, or Android host. The host is locked once it comes online. To lock a macOS, iOS, or iPadOS host, the host must have MDM turned on. To lock a Windows or Linux host, the host must have [scripts enabled](https://fleetdm.com/docs/using-fleet/scripts). For iOS and iPadOS, this enables [Lost Mode](https://developer.apple.com/documentation/devicemanagement/enable-lost-mode-command) and sends a [Device Location](https://developer.apple.com/documentation/devicemanagement/device-location-command) MDM command. To see location, use the [Get host](https://fleetdm.com/docs/rest-api/rest-api#get-host) endpoint. `POST /api/v1/fleet/hosts/:id/lock` #### Parameters | Name | Type | In | Description | | ---------- | ----------------- | ---- | ----------------------------------------------------------------------------- | | id | integer | path | **Required**. ID of the host to be locked. | | view_pin | boolean | query | For macOS hosts, whether to return the unlock PIN. | #### Example with macOS unlock PIN `POST /api/v1/fleet/hosts/123/lock?view_pin=true` ##### Default response `Status: 200` ```json { "unlock_pin": "123456", "device_status": "unlocked", "pending_action": "lock" } ``` > To verify the host successfully locked, you can use the [Get host](https://fleetdm.com/docs/rest-api/rest-api#get-host) endpoint to retrieve the host's `mdm.device_status`. ### Unlock host _Available in Fleet Premium_ Sends a command to unlock the specified iOS, iPadOS, Windows, or Linux host, or retrieves the unlock PIN for a macOS host. To unlock an iOS or iPadOS host, the host must have MDM turned on. To unlock a Windows or Linux host, the host must have [scripts enabled](https://fleetdm.com/docs/using-fleet/scripts). For iOS and iPadOS, this disables Lost Mode. `POST /api/v1/fleet/hosts/:id/unlock` #### Parameters | Name | Type | In | Description | | ---------- | ----------------- | ---- | ----------------------------------------------------------------------------- | | id | integer | path | **Required**. ID of the host to be unlocked. | #### Example `POST /api/v1/fleet/hosts/:id/unlock` ##### Default response `Status: 200` ```json { "host_id": 8, "device_status": "locked", "pending_action": "unlock" } ``` > To verify the host successfully unlocked, you can use the [Get host](https://fleetdm.com/docs/rest-api/rest-api#get-host) endpoint to retrieve the host's `mdm.device_status`. macOS hosts require entering `unlock_pin` to unlock. ### Wipe host Sends a command to wipe the specified macOS, iOS, iPadOS, Linux, Windows, or Android host. The host is wiped once it comes online. Wiping an Android host is available in Fleet Free and Fleet Premium. Wiping a macOS, iOS, iPadOS, Linux, or Windows host is available in Fleet Premium. To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on. To wipe a Linux host, the host must have [scripts enabled](https://fleetdm.com/docs/using-fleet/scripts). To wipe an Android host, the host must be enrolled as a fully managed device. `POST /api/v1/fleet/hosts/:id/wipe` #### Parameters | Name | Type | In | Description | |----------| ----------------- | ---- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id | integer | path | **Required**. ID of the host to be wiped. | | windows | object | body | Optional metadata used when wiping Windows hosts. The object includes a `wipe_type` property that can be used for specifying what type of remote wipe to perform. Allowed values are `"doWipe"` and `"doWipeProtected"`. | #### Example `POST /api/v1/fleet/hosts/123/wipe` ##### Optional request body ```json { "windows": { "wipe_type": "doWipe" } } ``` ##### Default response `Status: 200` ```json { "device_status": "unlocked", "pending_action": "wipe" } ``` > To verify the host was successfully wiped, you can use the [Get host](https://fleetdm.com/docs/rest-api/rest-api#get-host) endpoint to retrieve the host's `mdm.device_status`. ### Get host's past activity `GET /api/v1/fleet/hosts/:id/activities` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's ID. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page. Maximum is 10,000 records. If no pagination parameters are specified, defaults to 10,000.| | order_key | string | query | What to order results by. Allowed fields are `id`, `created_at`, and `activity_type`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/hosts/12/activities` ##### Default response `Status: 200` ```json { "activities": [ { "created_at": "2025-02-20T10:09:48.551757Z", "id": 123, "actor_full_name": "Anna Chao", "actor_id": 12, "actor_gravatar": "", "actor_email": "anna@example.com", "type": "installed_software", "fleet_initiated": false, "details": { "status": "installed", "host_id": 934, "policy_id": null, "policy_name": null, "install_uuid": "2fddb3d3-d553-4334-89a3-235da50d0ee7", "self_service": false, "software_title": "Notion.app", "software_package": "Notion-4.5.0-arm64.dmg", "host_display_name": "Marko's MacBook Pro" } }, { "created_at": "2023-07-27T14:35:08Z", "id": 2, "actor_full_name": "Anna Chao", "actor_id": 12, "actor_gravatar": "", "actor_email": "anna@example.com", "type": "ran_script", "fleet_initiated": true, "details": { "host_id": 1, "host_display_name": "Steve's MacBook Pro", "script_name": "set-timezones.sh", "script_execution_id": "d6cffa75-b5b5-41ef-9230-15073c8a88cf", "async": true } } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Get host's upcoming activity `GET /api/v1/fleet/hosts/:id/activities/upcoming` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's id. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page.| #### Example `GET /api/v1/fleet/hosts/12/activities/upcoming` ##### Default response `Status: 200` ```json { "count": 3, "activities": [ { "created_at": "2025-02-20T10:05:43.013218Z", "uuid": "ce8ed8b1-8e77-413f-936c-4ef2f9b665f8", "actor_full_name": "Anna Chao", "actor_id": 12, "actor_gravatar": "", "actor_email": "anna@example.com", "type": "installed_software", "fleet_initiated": false, "details": { "status": "pending_install", "host_id": 934, "policy_id": null, "policy_name": null, "install_uuid": "2fddb3d3-d553-4334-89a3-235da50d0ee7", "self_service": false, "software_title": "Notion.app", "software_package": "Notion-4.5.0-arm64.dmg", "host_display_name": "Marko's MacBook Pro" } }, { "created_at": "2023-07-27T14:35:08Z", "uuid": "d6cffa75-b5b5-41ef-9230-15073c8a88cf", "actor_full_name": "Marko", "actor_id": 1, "actor_gravatar": "", "actor_email": "marko@example.com", "type": "ran_script", "fleet_initiated": false, "details": { "host_id": 1, "host_display_name": "Steve's MacBook Pro", "script_name": "set-timezones.sh", "script_execution_id": "d6cffa75-b5b5-41ef-9230-15073c8a88cf", "async": true } }, { "created_at": "2021-07-27T13:25:21Z", "uuid": "y3cffa75-b5b5-41ef-9230-15073c8a88cf", "actor_full_name": "Rachael", "actor_id": 1, "actor_gravatar": "", "actor_email": "rachael@example.com", "type": "ran_script", "fleet_initiated": false, "details": { "host_id": 1, "host_display_name": "Steve's MacBook Pro", "script_name": "", "script_execution_id": "y3cffa75-b5b5-41ef-9230-15073c8a88cf", "async": false } } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Cancel host's upcoming activity `DELETE /api/v1/fleet/hosts/:id/activities/upcoming/:activity_id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's ID. | | activity_id | string | path | **Required**. The ID of the host's upcoming activity. | #### Example `DELETE /api/v1/fleet/hosts/12/activities/upcoming/81e10a70-730b-4c45-9b40-b14373e04757` ##### Default response `Status: 204` ### Add labels to host Adds manual labels to a host. `POST /api/v1/fleet/hosts/:id/labels` #### Parameters | Name | Type | In | Description | | ------ | ------- | ---- | ---------------------------- | | labels | array | body | The list of label names to add to the host. | #### Example `POST /api/v1/fleet/hosts/12/labels` ##### Request body ```json { "labels": ["label1", "label2"] } ``` ##### Default response `Status: 200` ### Remove labels from host Removes manual labels from a host. `DELETE /api/v1/fleet/hosts/:id/labels` #### Parameters | Name | Type | In | Description | | ------ | ------- | ---- | ---------------------------- | | labels | array | body | The list of label names to delete from the host. | #### Example `DELETE /api/v1/fleet/hosts/12/labels` ##### Request body ```json { "labels": ["label3", "label4"] } ``` ##### Default response `Status: 200` ### Run live report on host (ad hoc) Runs an ad hoc live report against the specified host and responds with the results. The live report will stop if the targeted host is offline, or if the query times out. Timeouts happen if the host hasn't responded after the configured `FLEET_LIVE_QUERY_REST_PERIOD` (default 25 seconds) or if the `distributed_interval` agent option (default 10 seconds) is higher than the `FLEET_LIVE_QUERY_REST_PERIOD`. `POST /api/v1/fleet/hosts/:id/query` #### Parameters | Name | Type | In | Description | |-----------|-------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id | integer | path | **Required**. The target host ID. | | query | string | body | **Required**. The query SQL. | #### Example `POST /api/v1/fleet/hosts/123/query` ##### Request body ```json { "query": "SELECT model, vendor FROM usb_devices;" } ``` ##### Default response `Status: 200` ```json { "host_id": 123, "query": "SELECT model, vendor FROM usb_devices;", "status": "online", // "online" or "offline" "error": null, "rows": [ { "model": "USB2.0 Hub", "vendor": "VIA Labs, Inc." } ] } ``` Note that if the host is online and the query times out, this endpoint will return an error and `rows` will be `null`. If the host is offline, no error will be returned, and `rows` will be`null`. ### Run live report on host by identifier (ad hoc) Runs an ad hoc live report against a host, specified using the `hostname`, `uuid`, or `hardware_serial` as an identifier, and responds with the results. The live report will stop if the targeted host is offline, or if the query times out. Timeouts happen if the host hasn't responded after the configured `FLEET_LIVE_QUERY_REST_PERIOD` (default 25 seconds) or if the `distributed_interval` agent option (default 10 seconds) is higher than the `FLEET_LIVE_QUERY_REST_PERIOD`. `POST /api/v1/fleet/hosts/identifier/:identifier/query` #### Parameters | Name | Type | In | Description | |-----------|-------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | identifier | integer or string | path | **Required**. The host's `hardware_serial`, `uuid`, `osquery_host_id`, `hostname`, or `node_key`. | | query | string | body | **Required**. The query SQL. | #### Example `POST /api/v1/fleet/hosts/identifier/392547dc-0000-0000-a87a-d701ff75bc65/query` ##### Request body ```json { "query": "SELECT model, vendor FROM usb_devices;" } ``` ##### Default response `Status: 200` ```json { "host_id": 123, "query": "SELECT model, vendor FROM usb_devices;", "status": "online", // "online" or "offline" "error": null, "rows": [ { "model": "USB2.0 Hub", "vendor": "VIA Labs, Inc." } ] } ``` Note that if the host is online and the query times out, this endpoint will return an error and `rows` will be `null`. If the host is offline, no error will be returned, and `rows` will be `null`. ### Bypass host's conditional access Grant a blocked host access for a single login. Requires Okta conditional access configured with bypass enabled. `POST /api/v1/fleet/device/:token/bypass_conditional_access` #### Parameters | Name | Type | In | Description | | ----------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | token | string | path | **Required.** The host's [Fleet Desktop token](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). | #### Example `POST /api/v1/fleet/device/abcdef012456789/bypass_conditional_access` ##### Default response `Status: 200` ### Clear host passcode _Available in Fleet Premium._ Remotely clear the passcode on a host. Requires iOS/iPadOS host to have sent its unlock token during MDM check-in. `POST /api/v1/fleet/hosts/:id/clear_passcode` #### Parameters | Name | Type | In | Description | | ----------- | ------ | ---- | ----------------------------------------------------------------------------------- | | id | number | path | **Required.** The Fleet host ID of the ADE-enrolled host to clear the passcode for. | #### Example `POST /api/v1/fleet/hosts/123/clear_passcode` ##### Default response `Status: 200` ```json { "command_uuid": "84F7F777-803E-40BB-8B47-2C0DC8B0118A", "request_type": "ClearPasscode", "platform": "ios" } ``` ### Rotate host's managed local account password _Available in Fleet Premium_ Rotates the managed local account password for a host. `POST /api/v1/fleet/hosts/:id/managed_account_password/rotate` #### Parameters | Name | Type | In | Description | | ----------------------------- | ------ | ---- | -------------------------------------------------------------------------------------- | | id | integer | path | The host ID to rotate the managed local account password for. | #### Example `POST /api/v1/fleet/hosts/123/managed_account_password/rotate` ##### Default response `Status: 204` ### Get host's managed account password Retrieves the managed account password for a macOS host. The host will only return a password if its managed account password status is "Verified". `GET /api/v1/fleet/hosts/:id/managed_account_password` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ------------------------------------------------------------------------ | | id | integer | path | **Required** The ID of the host to get the managed account password for. | #### Example `GET /api/v1/fleet/hosts/8/managed_account_password` ##### Default response `Status: 200` ```json { "host_id": 8, "managed_account_password": { "password": "test-123", "updated_at": "2026-02-01T05:31:43Z" } } ``` --- ## Labels - [Add label](#add-label) - [Update label](#update-label) - [Get label](#get-label) - [Get labels summary](#get-labels-summary) - [List labels](#list-labels) - [List label's hosts](#list-labels-hosts) - [Delete label by name](#delete-label-by-name) - [Delete label by ID](#delete-label-by-id) ### Add label Add a dynamic or manual label. `POST /api/v1/fleet/labels` #### Parameters | Name | Type | In | Description | | ----------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | body | **Required**. The label's name. | | description | string | body | The label's description. | | query | string | body | The query in SQL syntax used to filter the hosts. Only one of either `query` (to create a dynamic label) or `hosts` (to create a manual label) can be included in the request. | | criteria | object | body | Criteria for adding hosts to a host vitals label. See [`criteria`](#criteria) for details. | | hosts | array | body | The list of host identifiers (`hardware_serial` or `uuid`). The label will apply to any host with a matching identifier. Only one of either `query` (to create a dynamic label), `hosts` (to create a manual label), or `host_ids` (to create a manual label) can be included in the request. | | host_ids | array | body | The list of Fleet host IDs the label will apply to. Only one of either `query` (to create a dynamic label) or `hosts`/`host_ids` (to create a manual label) can be included in the request. | | platform | string | body | The specific platform for the label to target. Provides an additional filter. Choices for platform are `darwin`, `windows`, `ubuntu`, and `centos`. All platforms are included by default and this option is represented by an empty string. | If `query`, `criteria`, and `hosts` aren't specified, a manual label with no hosts will be created. The `hostname` host identifier is deprecated. Please use `host_ids`, `hardware_serial`, or `uuid` instead. #### criteria | Name | Type | Description | | --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | vital | string | The type of host vital to use when creating a host vital label. Can be `"end_user_idp_group"`, `"end_user_idp_department"`, or `"custom_host_vital"`. | | custom_host_vital_id | integer | The ID of the [custom host vital](https://fleetdm.com/guides/custom-host-vitals) to match on. Required when `vital` is `"custom_host_vital"`. | | value | string | Hosts with vital data matching this value will be added to the label. | #### Example `POST /api/v1/fleet/labels` ##### Request body ```json { "name": "macOS hosts (x86_64)", "description": "Filters macOS hosts with x86_64 architecture", "query": "SELECT 1 FROM os_version WHERE platform = 'darwin' AND instr(arch, 'x86_64')", "platform": "darwin" } ``` ##### Default response `Status: 200` ```json { "label": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 42, "name": "macOS hosts (x86_64)", "description": "Filters macOS hosts with x86_64 architecture", "query": "SELECT 1 FROM os_version WHERE platform = 'darwin' AND instr(arch, 'x86_64')", "label_type": "regular", "label_membership_type": "dynamic", "display_text": "macOS hosts (x86_64)", "count": 0, "host_ids": null, "author_id": 1, "team_id": null, "fleet_id": null } } ``` ### Update label Updates the specified label. Note: Label queries, platforms, and fleets are immutable. To change these, you must delete the label and create a new label. `PATCH /api/v1/fleet/labels/:id` #### Parameters | Name | Type | In | Description | | ----------- | ------- | ---- | ----------------------------- | | id | integer | path | **Required**. The label's id. | | name | string | body | The label's name. | | description | string | body | The label's description. | | hosts | array | body | If updating a manual label: the list of host identifiers (`hardware_serial` or `uuid`). The label will apply to any host with a matching identifier. The provided list fully replaces the previous list. Only one of either `hosts` or `host_ids` can be included in the request. | | host_ids | array | body | If updating a manual label: the list of Fleet host IDs the label will apply to. The provided list fully replaces the previous list. Only one of either `hosts` or `host_ids` can be included in the request. The `hostname` host identifier is deprecated. Please use `host_ids`, `hardware_serial`, or `uuid` instead. #### Example `PATCH /api/v1/fleet/labels/21` ##### Request body ```json { "hosts": ["ABC1234", "XYZ5678"] } ``` ##### Default response `Status: 200` ```json { "label": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 21, "name": "My label", "description": "Some hosts that I want to manually group together", "query": "", "platform": "", "label_type": "regular", "label_membership_type": "manual", "display_text": "My label", "count": 2, "host_ids": [42, 43], "author_id": 1, "team_id": null, "fleet_id": null, "team_name": null, "fleet_name": null } } ``` ### Get label Returns the specified label. `GET /api/v1/fleet/labels/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ----------------------------- | | id | integer | path | **Required**. The label's id. | #### Example `GET /api/v1/fleet/labels/1` ##### Default response `Status: 200` ```json { "label": { "created_at": "2021-02-09T22:09:43Z", "updated_at": "2021-02-09T22:15:58Z", "id": 12, "name": "Ubuntu", "description": "Filters ubuntu hosts", "query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';", "label_type": "regular", "label_membership_type": "dynamic", "display_text": "Ubuntu", "count": 0, "host_ids": null, "author_id": 1, "team_id": null, "fleet_id": null, "team_name": null, "fleet_name": null } } ``` ### Get labels summary Returns a list of labels in Fleet, including basic information on each label. `GET /api/v1/fleet/labels/summary` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ----- |------------------------------------- | | fleet_id | string | query | _Available in Fleet Premium._ Filters to labels belonging to the specified fleet, plus global labels. Specify `"global"` to show only globally-available labels. If omitted, Fleet returns all global labels, plus all labels for fleets to which the requestor has access. | #### Example `GET /api/v1/fleet/labels/summary` ##### Default response `Status: 200` ```json { "labels": [ { "id": 6, "name": "All Hosts", "description": "All hosts which have enrolled in Fleet", "label_type": "builtin", "team_id": null, "fleet_id": null }, { "id": 7, "name": "macOS", "description": "All macOS hosts", "label_type": "builtin", "team_id": null, "fleet_id": null }, { "id": 8, "name": "Ubuntu Linux", "description": "All Ubuntu hosts", "label_type": "builtin", "team_id": null, "fleet_id": null }, { "id": 9, "name": "CentOS Linux", "description": "All CentOS hosts", "label_type": "builtin", "team_id": null, "fleet_id": null }, { "id": 10, "name": "MS Windows", "description": "All Windows hosts", "label_type": "builtin", "team_id": null, "fleet_id": null }, { "id": 11, "name": "My fleet-specific label", "description": "This one goes to eleven, but only on one fleet", "label_type": "regular", "team_id": 1, "fleet_id": 1 } ] } ``` ### List labels Returns a list of labels. `GET /api/v1/fleet/labels` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ----- |------------------------------------- | | include_host_counts | boolean | query | Whether or not to calculate host counts for each label. Default is `true`. See "additional notes" for more information. | | order_key | string | query | What to order results by. Can be any column in the labels table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | fleet_id | string | query | _Available in Fleet Premium._ Filters to labels belonging to the specified fleet, plus global labels. Specify `"global"` to show only globally-available labels. If omitted, Fleet returns all global labels, plus all labels for fleets to which the requestor has access. | When `include_host_counts` is `true` (or omitted), `host_count` will only be included for `labels` that are in use by one or more hosts, but `count` will always be included, even if it is `0`. When `include_host_counts` is `false`, `host_count` will always be omitted, and `count` will be returned as `0` for each label. Setting `include_host_counts=false` will improve API performance, especially on deployments with large numbers of hosts and labels. #### Example `GET /api/v1/fleet/labels` ##### Default response `Status: 200` ```json { "labels": [ { "created_at": "2021-02-02T23:55:25Z", "updated_at": "2021-02-02T23:55:25Z", "id": 6, "name": "All Hosts", "description": "All hosts which have enrolled in Fleet", "query": "SELECT 1;", "label_type": "builtin", "label_membership_type": "dynamic", "host_count": 7, "display_text": "All Hosts", "count": 7, "host_ids": null, "author_id": 1, "team_id": null, "fleet_id": null }, { "created_at": "2021-02-02T23:55:25Z", "updated_at": "2021-02-02T23:55:25Z", "id": 7, "name": "macOS", "description": "All macOS hosts", "query": "SELECT 1 FROM os_version WHERE platform = 'darwin';", "platform": "darwin", "label_type": "builtin", "label_membership_type": "dynamic", "host_count": 1, "display_text": "macOS", "count": 1, "host_ids": null, "author_id": 1, "team_id": null, "fleet_id": null }, { "created_at": "2021-02-02T23:55:25Z", "updated_at": "2021-02-02T23:55:25Z", "id": 8, "name": "Ubuntu Linux", "description": "All Ubuntu hosts", "query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';", "platform": "ubuntu", "label_type": "builtin", "label_membership_type": "dynamic", "host_count": 3, "display_text": "Ubuntu Linux", "count": 3, "host_ids": null, "author_id": 1, "team_id": null, "fleet_id": null }, { "created_at": "2021-02-02T23:55:25Z", "updated_at": "2021-02-02T23:55:25Z", "id": 9, "name": "CentOS Linux", "description": "All CentOS hosts", "query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'", "label_type": "builtin", "label_membership_type": "dynamic", "host_count": 3, "display_text": "CentOS Linux", "count": 3, "host_ids": null, "author_id": 1, "team_id": null, "fleet_id": null }, { "created_at": "2021-02-02T23:55:25Z", "updated_at": "2021-02-02T23:55:25Z", "id": 10, "name": "MS Windows", "description": "All Windows hosts", "query": "SELECT 1 FROM os_version WHERE platform = 'windows';", "platform": "windows", "label_type": "builtin", "label_membership_type": "dynamic", "display_text": "MS Windows", "count": 0, "host_ids": null, "author_id": 1, "team_id": null, "fleet_id": null }, { "created_at": "2025-11-13T06:14:20Z", "updated_at": "2025-11-13T06:14:20Z", "id": 4663, "name": "Team: g-software", "description": "Workstations used by g-software", "query": "", "platform": "", "label_type": "regular", "label_membership_type": "manual", "display_text": "Team: g-software", "count": 0, "host_ids": null, "author_id": 1, "team_id": 2, "fleet_id": null } ] } ``` ### List label's hosts Returns a list of the hosts that belong to the specified label. `GET /api/v1/fleet/labels/:id/hosts` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | id | integer | path | **Required**. The label's id. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be any column in the hosts table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. | | query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, and `ipv4`. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts in the specified fleet. | | disable_failing_policies | boolean | query | If "true", hosts will return failing policies as 0 regardless of whether there are any that failed for the host. This is meant to be used when increased performance is needed in exchange for the extra information. | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | | mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'manual-personal', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | | macos_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. | | bootstrap_package | string | query | _Available in Fleet Premium_. Filters the hosts by the status of the MDM bootstrap package on the host. Valid options are 'installed', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | os_settings | string | query | Filters the hosts by the status of the operating system settings applied to the hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | os_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | If `mdm_id`, `mdm_name`, `mdm_enrollment_status`, `os_settings`, or `os_settings_disk_encryption` is specified, then Windows Servers are excluded from the results. #### Example `GET /api/v1/fleet/labels/6/hosts&query=floobar` ##### Default response `Status: 200` ```json { "hosts": [ { "created_at": "2021-02-03T16:11:43Z", "updated_at": "2021-02-03T21:58:19Z", "id": 2, "detail_updated_at": "2021-02-03T21:58:10Z", "label_updated_at": "2021-02-03T21:58:10Z", "policy_updated_at": "2023-06-26T18:33:15Z", "last_enrolled_at": "2021-02-03T16:11:43Z", "software_updated_at": "2020-11-05T05:09:44Z", "seen_time": "2021-02-03T21:58:20Z", "refetch_requested": false, "hostname": "floobar42", "uuid": "a2064cef-0000-0000-afb9-283e3c1d487e", "platform": "ubuntu", "osquery_version": "4.5.1", "os_version": "Ubuntu 20.4.0", "build": "", "platform_like": "debian", "code_name": "", "uptime": 32688000000000, "memory": 2086899712, "cpu_type": "x86_64", "cpu_subtype": "142", "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz", "cpu_physical_cores": 4, "cpu_logical_cores": 4, "hardware_vendor": "", "hardware_model": "", "hardware_version": "", "hardware_serial": "", "computer_name": "e2e7f8d8983d", "timezone": null, "display_name": "e2e7f8d8983d", "primary_ip": "172.20.0.2", "primary_mac": "02:42:ac:14:00:02", "distributed_interval": 10, "config_tls_refresh": 10, "logger_tls_period": 10, "team_id": null, "fleet_id": null, "pack_stats": null, "team_name": null, "fleet_name": null, "status": "offline", "display_text": "e2e7f8d8983d", "mdm": { "encryption_key_available": false, "enrollment_status": null, "name": "", "server_url": null } } ] } ``` ### Delete label by name Deletes the label specified by name. `DELETE /api/v1/fleet/labels/:name` #### Parameters | Name | Type | In | Description | | ---- | ------ | ---- | ------------------------------- | | name | string | path | **Required**. The label's name. | #### Example `DELETE /api/v1/fleet/labels/ubuntu_label` ##### Default response `Status: 200` ### Delete label by ID Deletes the label specified by ID. `DELETE /api/v1/fleet/labels/id/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ----------------------------- | | id | integer | path | **Required**. The label's id. | #### Example `DELETE /api/v1/fleet/labels/id/13` ##### Default response `Status: 200` --- ## OS settings - [Create configuration profile](#create-configuration-profile) - [List configuration profiles](#list-configuration-profiles) - [Get or download configuration profile](#get-or-download-configuration-profile) - [Update configuration profile](#update-configuration-profile) - [Delete configuration profile](#delete-configuration-profile) - [Batch-update configuration profiles](#batch-update-configuration-profiles) - [Create Apple asset declaration](#create-apple-asset-declaration) - [List Apple asset declarations](#list-apple-asset-declarations) - [Get or download Apple asset declaration](#get-or-download-apple-asset-declaration) - [Delete Apple asset declaration](#delete-apple-asset-declaration) - [Update disk encryption](#update-disk-encryption) - [Get disk encryption status](#get-disk-encryption-status) - [Update host name template](#update-host-name-template) - [Resend host name template](#resend-host-name-template) - [Update Recovery Lock](#update-recovery-lock) - [Get OS settings (configuration profiles) status](#get-os-settings-configuration-profiles-status) - [Get OS setting (configuration profile) status](#get-os-setting-configuration-profile-status) - [Resend configuration profile](#resend-configuration-profile) - [Batch-resend configuration profile](#batch-resend-configuration-profile) - [Resend configuration profile by Fleet Desktop token](#resend-configuration-profile-by-fleet-desktop-token) ### Create configuration profile > [Add custom macOS setting](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#add-custom-macos-setting-configuration-profile) (`POST /api/v1/fleet/mdm/apple/profiles`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead. Add a configuration profile to enforce custom settings on macOS and Windows hosts. > You need to send a request of type `multipart/form-data`. > This endpoint accepts a maximum request body size of 1.5MiB. `POST /api/v1/fleet/configuration_profiles` #### Parameters | Name | Type | In | Description | | ------------------------- | -------- | ---- | ------------------------------------------------------------------------------------------------------------- | | profile | file | body | **Required.** The .mobileconfig and JSON for macOS or XML for Windows file containing the profile. | | fleet_id | string | body | _Available in Fleet Premium_. The fleet ID for the profile. If specified, the profile is applied to only hosts that are assigned to the specified fleet. If not specified, the profile is applied to only hosts that are "Unassigned". | | labels_include_all | array | body | _Available in Fleet Premium_. Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | body | _Available in Fleet Premium_. Target hosts that that don't have any label, specified by label name, in the array. | `labels_exclude_any` can be combined with either `labels_include_all` or `labels_include_any`, but `labels_include_all` and `labels_include_any` cannot be combined with each other. If none are specified, all hosts are targeted. If the response is `Status: 409 Conflict`, the body may include additional error details in the case of duplicate payload display name or duplicate payload identifier (macOS profiles). #### Example Add a new configuration profile to be applied to macOS hosts assigned to a fleet. Note that in this example the form data specifies `fleet_id` in addition to `profile`. `POST /api/v1/fleet/configuration_profiles` ##### Request body ```http profile="Foo.mobileconfig" fleet_id="1" labels_include_all="Label name 1" ``` ##### Default response `Status: 200` ```json { "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24" } ``` ### List configuration profiles > [List custom macOS settings](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#list-custom-macos-settings-configuration-profiles) (`GET /api/v1/fleet/mdm/apple/profiles`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead. Get a list of the configuration profiles in Fleet. For Fleet Premium, the list can optionally be filtered by fleet ID. If no fleet ID is specified, fleet profiles are excluded from the results (i.e., only profiles that are associated with "Unassigned" are listed). `GET /api/v1/fleet/configuration_profiles` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | string | query | _Available in Fleet Premium_. The fleet id to filter profiles. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be ordered by `name`, `created_at`, or `uploaded_at`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example List all configuration profiles for macOS and Windows hosts enrolled to Fleet's MDM that are "Unassigned". `GET /api/v1/fleet/configuration_profiles` ##### Default response `Status: 200` ```json { "profiles": [ { "profile_uuid": "39f6cbbc-fe7b-4adc-b7a9-542d1af89c63", "team_id": 0, "name": "Example macOS profile", "platform": "darwin", "identifier": "com.example.profile", "created_at": "2023-03-31T00:00:00Z", "updated_at": "2023-03-31T00:00:00Z", "checksum": "dGVzdAo=", "labels_exclude_any": [ { "name": "Label name 1", "id": 1 } ] }, { "profile_uuid": "f5ad01cc-f416-4b5f-88f3-a26da3b56a19", "team_id": 0, "name": "Example Windows profile", "platform": "windows", "created_at": "2023-04-31T00:00:00Z", "updated_at": "2023-04-31T00:00:00Z", "checksum": "aCLemVr)", "labels_include_all": [ { "name": "Label name 2", "broken": true }, { "name": "Label name 3", "id": 3 } ] } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` If one or more assigned labels are deleted the profile is considered broken (`broken: true`). It won’t be applied to new hosts. ### Get or download configuration profile > [Download custom macOS setting](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#download-custom-macos-setting-configuration-profile) (`GET /api/v1/fleet/mdm/apple/profiles/:profile_id`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the API endpoint below instead. `GET /api/v1/fleet/configuration_profiles/:profile_uuid` #### Parameters | Name | Type | In | Description | | ------------------------- | ------- | ----- | ------------------------------------------------------- | | profile_uuid | string | url | **Required** The UUID of the profile to download. | | alt | string | query | If specified and set to "media", downloads the profile. | #### Example (get a profile metadata) `GET /api/v1/fleet/configuration_profiles/f663713f-04ee-40f0-a95a-7af428c351a9` ##### Default response `Status: 200` ```json { "profile_uuid": "f663713f-04ee-40f0-a95a-7af428c351a9", "team_id": 0, "name": "Example profile", "platform": "darwin", "identifier": "com.example.profile", "created_at": "2023-03-31T00:00:00Z", "updated_at": "2023-03-31T00:00:00Z", "checksum": "dGVzdAo=", "labels_include_all": [ { "name": "Label name 1", "id": 1, "broken": true }, { "name": "Label name 2", "id": 2 } ] } ``` #### Example (download a profile) `GET /api/v1/fleet/configuration_profiles/f663713f-04ee-40f0-a95a-7af428c351a9?alt=media` ##### Default response `Status: 200` **Note** To confirm success, it is important for clients to match content length with the response header (this is done automatically by most clients, including the browser) rather than relying solely on the response status code returned by this endpoint. ##### Example response headers ```http Content-Length: 542 Content-Type: application/octet-stream Content-Disposition: attachment;filename="2023-03-31 Example profile.mobileconfig" ``` ###### Example response body ```xml PayloadContent PayloadDisplayName Example profile PayloadIdentifier com.example.profile PayloadType Configuration PayloadUUID 0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69 PayloadVersion 1 ``` ### Update configuration profile _Available in Fleet Premium._ Update an existing configuration profile. Use this endpoint to change which hosts a profile is applied to (labels/custom targets) and/or to upload a new profile file. `PATCH /api/v1/fleet/configuration_profiles/:profile_uuid` #### Parameters | Name | Type | In | Description | | ------------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------- | | profile_uuid | string | url | **Required.** The UUID of the configuration profile to update. | | profile | file | form | A replacement profile file (`.mobileconfig`, `.json`, or `.xml`). See requirements below. | | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | body | Target hosts that don't have any label, specified by label name, in the array. | Only one of `labels_include_all`, `labels_include_any`, or `labels_exclude_any` can be specified. If none are specified, the profile targets all hosts. ##### Uploading a new profile file You can upload a new profile file to replace the contents of the existing profile. The new profile must match the identity of the existing profile: - **DDM (declarative management) profiles** (`.json`): The new profile must have the same **Identifier** as the existing profile. - **.mobileconfig profiles**: The new profile must have the same **PayloadIdentifier** as the existing profile. If the new profile does not match the required identifiers, the request will be rejected. #### Example Update a configuration profile to target hosts with specific labels. `PATCH /api/v1/fleet/configuration_profiles/f663713f-04ee-40f0-a95a-7af428c351a9` ##### Request body ```json { "labels_include_all": ["Label name 1", "Label name 2"] } ``` ##### Default response `Status: 200` ```json { "profile_uuid": "f663713f-04ee-40f0-a95a-7af428c351a9" } ``` ### Delete configuration profile > [Delete custom macOS setting](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#delete-custom-macos-setting-configuration-profile) (`DELETE /api/v1/fleet/mdm/apple/profiles/:profile_id`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead. `DELETE /api/v1/fleet/configuration_profiles/:profile_uuid` #### Parameters | Name | Type | In | Description | | ------------------------- | ------- | ----- | ------------------------------------------------------------------------- | | profile_uuid | string | url | **Required** The UUID of the profile to delete. | #### Example `DELETE /api/v1/fleet/configuration_profiles/f663713f-04ee-40f0-a95a-7af428c351a9` ##### Default response `Status: 200` ### Resend configuration profile Resends a configuration profile for the specified host. Currently, macOS, iOS, iPadOS configuration profiles (.mobileconfig) are supported, as well as Windows (.xml) configuration profiles. `POST /api/v1/fleet/hosts/:id/configuration_profiles/:profile_uuid/resend` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | id | integer | path | **Required.** The host's ID. | | profile_uuid | string | path | **Required.** The UUID of the configuration profile to resend to the host. | #### Example `POST /api/v1/fleet/hosts/233/configuration_profiles/fc14a20-84a2-42d8-9257-a425f62bb54d/resend` ##### Default response `Status: 202` ### Batch-update configuration profiles Modify configuration profiles for a fleet. The provided list of profiles will be the active profiles for the specified fleet. If no fleet (`fleet_id` or `fleet_name`) is provided, the profiles are applied for all hosts (Fleet Free) or for hosts that are "Unassigned" (Fleet Premium). For Apple (macOS, iOS, iPadOS) profiles, Fleet will send only an `InstallProfile` command (edit) for all existing profiles with the same `PayloadIdentifier` (specified in the .mobileconfig file). Fleet will send a `RemoveProfile` command to hosts for all existing profiles that are not part of the list. For Windows profiles, Fleet applies new profiles or updates when content changes, and deletes profiles no longer in the list. It does not send commands to remove configuration profiles from Windows hosts. For declaration (DDM) profiles, hosts with new, updated, or removed profiles are marked "Pending," and Fleet sends a [DeclarativeManagement command](https://developer.apple.com/documentation/devicemanagement/declarativemanagementcommand) to tell Apple (macOS, iOS, iPadOS) hosts to sync profiles. If declarations are current, no command is sent and the host is not marked "Pending." For requests with 100+ profiles, requests will take 5+ seconds. > This endpoint accepts a maximum request body size of 25MiB. `POST /api/v1/fleet/configuration_profiles/batch` #### Parameters | Name | Type | In | Description | | --------- | ------ | ----- | --------------------------------------------------------------------------------------------------------------------------------- | | fleet_id | number | query | _Available in Fleet Premium_ The fleet ID to apply the configuration profiles to. Only one of `fleet_name` or `fleet_id` may be included in the request. | | fleet_name | string | query | _Available in Fleet Premium_ The name of the fleet to apply the custom settings to. Only one of `fleet_name` or `fleet_id` may be included in the request. | | dry_run | bool | query | Validate the provided profiles and return any validation errors, but do not apply the changes. | | configuration_profiles | object | body | **Required**. See [configuration_profiles](#configuration-profiles) | ##### Configuration profiles | Name | Type | Description | | -----------------------| ------- | ----------------------------------------------------------------------------------- | | profile | string | Base64 encoded configuration profile (.mobileconfig) or declaration (DDM) profile for Apple (macOS, iOS, iPadOS) hosts, JSON profile for Android hosts, or XML profile for Windows hosts. | | labels_include_all | array | _Available in Fleet Premium_. Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | _Available in Fleet Premium_. Target hosts that that don't have any label, specified by label name, in the array. | | display_name | string | Required for Windows and declaration (DDM) profiles. It's not supported for .mobileconfig profiles. Instead, the profiles `PayloadDisplayName` is used. | For each `profile`, `labels_exclude_any` can be combined with either `labels_include_all` or `labels_include_any`, but `labels_include_all` and `labels_include_any` cannot be combined with each other. If neither is set, all hosts on the specified platform are targeted. #### Example `POST /api/v1/fleet/configuration_profiles/batch?fleet_id=1` ##### Request body ```json { "configuration_profiles": [ { "profile": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPCFET0NUWVBFIHBsaXN0IFBVQkxJQyAiLS8vQXBwbGUvL0RURCBQTElTVCAxLjAvL0VOIiAiaHR0cDovL3d3dy5hcHBsZS5jb20vRFREcy9Qcm9wZXJ0eUxpc3QtMS4wLmR0ZCI+CjxwbGlzdCB2ZXJzaW9uPSIxLjAiPgo8ZGljdD4KCTxrZXk+UGF5bG9hZENvbnRlbnQ8L2tleT4KCTxhcnJheT4KCQk8ZGljdD4KCQkJPGtleT5BbGxvd1ByZVJlbGVhc2VJbnN0YWxsYXRpb248L2tleT4KCQkJPHRydWUvPgoJCQk8a2V5PkF1dG9tYXRpY0NoZWNrRW5hYmxlZDwva2V5PgoJCQk8dHJ1ZS8+CgkJCTxrZXk+QXV0b21hdGljRG93bmxvYWQ8L2tleT4KCQkJPHRydWUvPgoJCQk8a2V5PkF1dG9tYXRpY2FsbHlJbnN0YWxsQXBwVXBkYXRlczwva2V5PgoJCQk8dHJ1ZS8+CgkJCTxrZXk+QXV0b21hdGljYWxseUluc3RhbGxNYWNPU1VwZGF0ZXM8L2tleT4KCQkJPHRydWUvPgoJCQk8a2V5PkNvbmZpZ0RhdGFJbnN0YWxsPC9rZXk+CgkJCTx0cnVlLz4KCQkJPGtleT5Dcml0aWNhbFVwZGF0ZUluc3RhbGw8L2tleT4KCQkJPHRydWUvPgoJCQk8a2V5PlBheWxvYWREZXNjcmlwdGlvbjwva2V5PgoJCQk8c3RyaW5nPkNvbmZpZ3VyZXMgU29mdHdhcmUgVXBkYXRlIHNldHRpbmdzPC9zdHJpbmc+CgkJCTxrZXk+UGF5bG9hZERpc3BsYXlOYW1lPC9rZXk+CgkJCTxzdHJpbmc+U29mdHdhcmUgVXBkYXRlPC9zdHJpbmc+CgkJCTxrZXk+UGF5bG9hZElkZW50aWZpZXI8L2tleT4KCQkJPHN0cmluZz5jb20uZ2l0aHViLmVyaWtiZXJnbHVuZC5Qcm9maWxlQ3JlYXRvci5CRUJBMDc0MC00RERCLTRBQzQtODVEQy1CQTQ4Qjk2QzBEQzguY29tLmFwcGxlLlNvZnR3YXJlVXBkYXRlLkE4Qjk3MDMyLTc2NDUtNDA2OC1CNDU3LTAxREU1QzZCMzNGNzwvc3RyaW5nPgoJCQk8a2V5PlBheWxvYWRPcmdhbml6YXRpb248L2tleT4KCQkJPHN0cmluZz48L3N0cmluZz4KCQkJPGtleT5QYXlsb2FkVHlwZTwva2V5PgoJCQk8c3RyaW5nPmNvbS5hcHBsZS5Tb2Z0d2FyZVVwZGF0ZTwvc3RyaW5nPgoJCQk8a2V5PlBheWxvYWRVVUlEPC9rZXk+CgkJCTxzdHJpbmc+QThCOTcwMzItNzY0NS00MDY4LUI0NTctMDFERTVDNkIzM0Y3PC9zdHJpbmc+CgkJCTxrZXk+UGF5bG9hZFZlcnNpb248L2tleT4KCQkJPGludGVnZXI+MTwvaW50ZWdlcj4KCQk8L2RpY3Q+Cgk8L2FycmF5PgoJPGtleT5QYXlsb2FkRGVzY3JpcHRpb248L2tleT4KCTxzdHJpbmc+RW5hYmxlcyBhdXRvbWF0aWMgdXBkYXRlczwvc3RyaW5nPgoJPGtleT5QYXlsb2FkRGlzcGxheU5hbWU8L2tleT4KCTxzdHJpbmc+VHVybiBvbiBhdXRvbWF0aWMgdXBkYXRlczwvc3RyaW5nPgoJPGtleT5QYXlsb2FkSWRlbnRpZmllcjwva2V5PgoJPHN0cmluZz5jb20uZ2l0aHViLmVyaWtiZXJnbHVuZC5Qcm9maWxlQ3JlYXRvci5CRUJBMDc0MC00RERCLTRBQzQtODVEQy1CQTQ4Qjk2QzBEQzg8L3N0cmluZz4KCTxrZXk+UGF5bG9hZE9yZ2FuaXphdGlvbjwva2V5PgoJPHN0cmluZz5GbGVldERNPC9zdHJpbmc+Cgk8a2V5PlBheWxvYWRSZW1vdmFsRGlzYWxsb3dlZDwva2V5PgoJPHRydWUvPgoJPGtleT5QYXlsb2FkU2NvcGU8L2tleT4KCTxzdHJpbmc+U3lzdGVtPC9zdHJpbmc+Cgk8a2V5PlBheWxvYWRUeXBlPC9rZXk+Cgk8c3RyaW5nPkNvbmZpZ3VyYXRpb248L3N0cmluZz4KCTxrZXk+UGF5bG9hZFVVSUQ8L2tleT4KCTxzdHJpbmc+QkVCQTA3NDAtNEREQi00QUM0LTg1REMtQkE0OEI5NkMwREM4PC9zdHJpbmc+Cgk8a2V5PlBheWxvYWRWZXJzaW9uPC9rZXk+Cgk8aW50ZWdlcj4xPC9pbnRlZ2VyPgo8L2RpY3Q+CjwvcGxpc3Q+", "labels_include_any": [ "Apple Silicon macOS hosts" ] } ] } ``` ##### Default response `Status: 204` ### Create Apple asset declaration Add an Apple asset declaration to reference in a configuration profile. > You need to send a request of type `multipart/form-data`. > This endpoint accepts a maximum request body size of 1.5MiB. `POST /api/v1/fleet/assets` #### Parameters | Name | Type | In | Description | | ------------------------- | -------- | ---- | ------------------------------------------------------------------------------------------------------------- | | asset | file | body | **Required.** The JSON asset declaration. The "Type" must be a valid Apple asset declaration type (e.g., "com.apple.asset.data"), and an "Identifier" must be defined. See [Apple's documentation](https://developer.apple.com/documentation/devicemanagement) for type-specific payload requirements. | | fleet_id | string | body | _Available in Fleet Premium_. The fleet ID for the asset. If specified, the asset is available to only the configuration profile(s) that are assigned to the specified fleet. If not specified, the profile is applied to only hosts that are "Unassigned". | #### Example `POST /api/v1/fleet/assets` ##### Request body ``` fleet_id="1" asset="my-asset.json" ``` ##### Example asset file (my-asset.json) ``` { "Type": "com.apple.asset.data", "Identifier": "EB13EE2B-5D63-4EBA-810F-5B81D07F5017", "ServerToken": "E180CA9A-F089-4FA3-BBDF-94CC159C4AE8", "Payload": { "Reference": { "DataURL": "https://example.com/asset-data/data/test.txt", "ContentType": "text/plain" }, "Authentication": { "Type": "MDM" } } } ``` ##### Default response `Status: 200` ```json { "asset_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24" } ``` ### List Apple asset declarations Get a list of the Apple asset declarations in Fleet. For Fleet Premium, the list can optionally be filtered by fleet ID. If no fleet ID is specified, fleet assets are excluded from the results (i.e., only assets that are associated with "Unassigned" are listed). `GET /api/v1/fleet/assets` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | string | query | _Available in Fleet Premium_. The fleet id to filter profiles. | #### Example List all assets available for the "Unassigned" fleet. `GET /api/v1/fleet/assets` ##### Default response `Status: 200` ```json { "assets": [ { "asset_uuid": "39f6cbbc-fe7b-4adc-b7a9-542d1af89c63", "asset": "my-asset.json", "identifier": "com.example.asset1", "created_at": "2023-03-31T00:00:00Z", "updated_at": "2023-03-31T00:00:00Z", "checksum": "dGVzdAo=", }, { "asset_uuid": "39f6cbbc-fe7b-4adc-b7a9-542d1af89c63", "asset": "my-asset2.json", "identifier": "com.example.asset2", "created_at": "2023-03-31T00:00:00Z", "updated_at": "2023-03-31T00:00:00Z", "checksum": "dGVzdAo=", }, ], } ``` ### Get or download Apple asset declaration Get or download the original Apple asset declaration file that was uploaded to Fleet. `GET /api/v1/fleet/assets/:asset_uuid` #### Parameters | Name | Type | In | Description | | ------------------------- | ------- | ----- | ------------------------------------------------------- | | asset_uuid | string | url | **Required** The UUID of the asset to get. | | alt | string | query | If specified and set to "media", downloads the asset. | #### Example (get asset metadata) `GET /api/v1/fleet/assets/954ec5ea-a334-4825-87b3-937e7e381f24` ##### Default response `Status: 200` ```json { "asset_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24", "fleet_id": 0, "asset": "my-asset.json", "identifier": "com.example.asset1", "created_at": "2023-03-31T00:00:00Z", "updated_at": "2023-03-31T00:00:00Z", "checksum": "dGVzdAo=" } ``` #### Example (download an asset) `GET /api/v1/fleet/assets/954ec5ea-a334-4825-87b3-937e7e381f24?alt=media` ##### Default response `Status: 200` **Note** To confirm success, it is important for clients to match content length with the response header (this is done automatically by most clients, including the browser) rather than relying solely on the response status code returned by this endpoint. ##### Example response headers ```http Content-Length: 542 Content-Type: application/octet-stream Content-Disposition: attachment;filename="2023-03-31 my-asset.json" ``` ###### Example response body ```json { "Type": "com.apple.asset.data", "Identifier": "com.example.asset1", "ServerURL": "https://example.com/assets/my-asset.json" } ``` ### Delete Apple asset declaration Deletes an Apple asset declaration. > If an asset is referenced in a configuration profile, you must delete the configuration profile first before being able to remove the asset. `DELETE /api/v1/fleet/assets/:asset_uuid` #### Parameters | Name | Type | In | Description | | ------------------------- | ------- | ----- | ------------------------------------------------- | | asset_uuid | string | url | **Required** The UUID of the asset to delete. | #### Example `DELETE /api/v1/fleet/assets/954ec5ea-a334-4825-87b3-937e7e381f24` ##### Default response `Status: 204` ### Resend configuration profile by Fleet Desktop token Resends a configuration profile for the specified host. Currently, macOS, iOS, iPadOS configuration profiles (.mobileconfig) are supported, as well as Windows (.xml) configuration profiles. `POST /api/v1/fleet/device/:token/configuration_profiles/:profile_uuid/resend` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | token | string | path | **Required.** The host's [Fleet Desktop token](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). | | profile_uuid | string | path | **Required.** The UUID of the configuration profile to resend to the host. | #### Example `POST /api/v1/fleet/device/abcdef012456789/configuration_profiles/fc14a20-84a2-42d8-9257-a425f62bb54d/resend` ##### Default response `Status: 202` ### Batch-resend configuration profile `POST /api/v1/fleet/configuration_profiles/resend/batch` #### Parameters | Name | Type | In | Description | | ------------- | ------- | ---- | -------------------------------------------------------------------------------------- | | profile_uuid | integer | body | **Required**. The UUID of the existing configuration profile you'd like to resend. | | filters | object | body | **Required**. See [filters](#filters) | ##### Filters | Name | Type | Description | | -----------------------| ------- | ----------------------------------------------------------------------------------- | | profile_status | string | Profile status. Currently, `"failed"` is supported. | #### Example `POST /api/v1/fleet/configuration_profiles/batch/resend` ##### Request body ```json { "profile_uuid": "f663713f-04ee-40f0-a95a-7af428c351a9", "filters": { "profile_status": "failed" } } ``` ##### Default response `Status: 202` ### Update disk encryption > The `PATCH /api/v1/fleet/mdm/apple/settings` API endpoint is deprecated as of Fleet 4.45. It is maintained for backward compatibility. Please use the new API endpoint below. You can view [archived documentation for the deprecated endpoint](https://github.com/iansltx/fleet/blob/d1791518a43c9d290192dbf992bcea290c8158a3/docs/REST%20API/rest-api.md#update-disk-encryption-enforcement). _Available in Fleet Premium_ `POST /api/v1/fleet/disk_encryption` #### Parameters | Name | Type | In | Description | | ------------- | ------ | ---- | -------------------------------------------------------------------------------------- | | fleet_id | integer | body | The fleet ID to apply the settings to. Settings are applied to "Unassigned" hosts if absent. | | enable_disk_encryption | boolean | body | Whether disk encryption should be enforced on devices that belong to the fleet (or "Unassigned"). | | windows_require_bitlocker_pin | boolean | body | End users on Windows hosts will be required to set a BitLocker PIN if set to true. `enable_disk_encryption` must be set to true. When the PIN is set, it's required to unlock Windows host during startup. | #### Example `POST /api/v1/fleet/disk_encryption` ##### Default response `Status: 204` ### Get disk encryption status _Available in Fleet Premium_ Get aggregate status counts of disk encryption enforced on macOS and Windows hosts. The summary can optionally be filtered by fleet ID. `GET /api/v1/fleet/disk_encryption` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | string | query | _Available in Fleet Premium_. The fleet ID to filter the summary. | #### Example `GET /api/v1/fleet/disk_encryption` ##### Default response `Status: 200` ```json { "verified": {"macos": 123, "windows": 123, "linux": 13}, "verifying": {"macos": 123, "windows": 0, "linux": 0}, "action_required": {"macos": 123, "windows": 0, "linux": 37}, "enforcing": {"macos": 123, "windows": 123, "linux": 0}, "failed": {"macos": 123, "windows": 123, "linux": 0}, "removing_enforcement": {"macos": 123, "windows": 0, "linux": 0} } ``` ### Update host name template _Available in Fleet Premium_ Sets a naming convention for all macOS, iOS, and iPadOS hosts in a fleet (or "Unassigned"). Fleet resolves the template per host, renames the host on the device via an Apple MDM command, and updates the host's name in Fleet. Sending an empty `name_template` clears the template. Clearing the template stops enforcement but doesn't rename any host. `POST /api/v1/fleet/host_name_template` #### Parameters | Name | Type | In | Description | | ------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | | fleet_id | integer | body | The fleet ID to apply the host name template to. The template is applied to "Unassigned" hosts if the value is absent or `0`. | | name_template | string | body | The host name template. Send an empty string to clear the template. | The template supports the built-in host identity variables (`$FLEET_VAR_HOST_HARDWARE_SERIAL`, `$FLEET_VAR_HOST_UUID`, `$FLEET_VAR_HOST_PLATFORM`), the IdP end-user variables (`$FLEET_VAR_HOST_END_USER_IDP_USERNAME`, `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART`, `$FLEET_VAR_HOST_END_USER_IDP_GROUPS`, `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT`, `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME`), and custom (`$FLEET_SECRET_*`) variables; each also works in its `${...}` form. Certificate authority variables (SCEP challenges and proxy URLs, DigiCert data, certificate renewal IDs, the Platform SSO device registration token) and the deprecated `$FLEET_VAR_HOST_END_USER_EMAIL_IDP` variable aren't supported and return a `422` — they resolve to secrets or certificate data that are meaningless and unsafe as a host name. If a host is missing the IdP data a variable needs, that host's rename fails. A referenced custom variable must already exist (an undefined one returns a `422`); custom variables are global, and a custom variable's value becomes the host's (publicly visible) name, so it isn't kept hidden as it is in scripts and configuration profiles. #### Example `POST /api/v1/fleet/host_name_template` ##### Request body ```json { "fleet_id": 5, "name_template": "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL" } ``` ##### Default response `204` ### Resend host name template _Available in Fleet Premium_ Resends the host name template MDM command to a host whose host name status is "failed" or "verified". The host's status returns to "pending" (shown as "Enforcing" in the UI) until the device applies the name again. `POST /api/v1/fleet/hosts/:id/name_template/resend` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ------------------------------------------------------ | | id | integer | path | **Required.** The ID of the host to resend to. | #### Example `POST /api/v1/fleet/hosts/42/name_template/resend` ##### Default response `Status: 202` If the host has no host name template enforced, the response is `404`. If the host name status is "pending" or "verifying", the response is `409`. ### Get OS settings (configuration profiles) status > [Get macOS settings statistics](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#get-macos-settings-statistics) (`GET /api/v1/fleet/mdm/apple/profiles/summary`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead. Get aggregate status counts of all OS settings (configuration profiles, Recovery Lock passwords, and disk encryption) enforced on hosts. For Fleet Premium users, the counts can optionally be filtered by `fleet_id`. If no `fleet_id` is specified, fleet profiles are excluded from the results (i.e., only profiles that are associated with "Unassigned" are listed). `GET /api/v1/fleet/configuration_profiles/summary` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | string | query | _Available in Fleet Premium_. The fleet ID to filter profiles. | #### Example Get aggregate status counts of profiles for macOS and Windows hosts that are "Unassigned". `GET /api/v1/fleet/configuration_profiles/summary` ##### Default response `Status: 200` ```json { "verified": 123, "verifying": 123, "failed": 123, "pending": 123 } ``` ### Get OS setting (configuration profile) status Get status counts of a single OS settings (configuration profile) enforced on hosts. `GET /api/v1/fleet/configuration_profiles/:profile_uuid/status` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | profile_uuid | string | query | **Required**. The UUID of configuration profile. | #### Example `GET /api/v1/fleet/configuration_profiles/f663713f-04ee-40f0-a95a-7af428c351a9/status` ##### Default response `Status: 200` ```json { "verified": 123, "verifying": 123, "failed": 123, "pending": 123 } ``` --- ## Setup experience - [Update custom MDM setup enrollment profile](#update-custom-mdm-setup-enrollment-profile) - [Get custom MDM setup enrollment profile](#get-custom-mdm-setup-enrollment-profile) - [Get Fleet default MDM setup enrollment profile](#get-fleet-default-mdm-setup-enrollment-profile) - [Delete custom MDM setup enrollment profile](#delete-custom-mdm-setup-enrollment-profile) - [Get Over-the-Air (OTA) enrollment profile](#get-over-the-air-ota-enrollment-profile) - [Get manual enrollment profile](#get-manual-enrollment-profile) - [Create bootstrap package](#create-bootstrap-package) - [Get bootstrap package metadata](#get-bootstrap-package-metadata) - [Delete bootstrap package](#delete-bootstrap-package) - [Download bootstrap package](#download-bootstrap-package) - [Get bootstrap package status](#get-bootstrap-package-status) - [Update setup experience](#update-setup-experience) - [Create EULA](#create-eula) - [Get EULA metadata](#get-eula-metadata) - [Delete EULA](#delete-eula) - [Download EULA](#download-eula) - [List setup experience software](#list-setup-experience-software) - [Update setup experience software (setup experience)](#update-setup-experience-software) - [Create setup experience script](#create-setup-experience-script) - [Get or download setup experience script](#get-or-download-setup-experience-script) - [Delete setup experience script](#delete-setup-experience-script) - [Update managed local account](#update-managed-local-account) ### Update custom MDM setup enrollment profile _Available in Fleet Premium_ Sets the custom MDM setup enrollment profile for a fleet or "Unassigned". `POST /api/v1/fleet/enrollment_profiles/automatic` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | integer | json | The fleet ID this custom enrollment profile applies to, or "Unassigned" if omitted. | | name | string | json | The filename of the uploaded custom enrollment profile. | | enrollment_profile | object | json | The custom enrollment profile's json, as documented in https://developer.apple.com/documentation/devicemanagement/profile. | #### Example `POST /api/v1/fleet/enrollment_profiles/automatic` ##### Default response `Status: 200` ```json { "team_id": 123, "fleet_id": 123, "name": "dep_profile.json", "uploaded_at": "2023-04-04:00:00Z", "enrollment_profile": { "is_mandatory": true, "is_mdm_removable": false } } ``` > NOTE: The `ConfigurationWebURL` and `URL` values in the custom MDM setup enrollment profile are automatically populated. Attempting to populate them with custom values may generate server response errors. ### Get custom MDM setup enrollment profile _Available in Fleet Premium_ Gets the custom MDM setup enrollment profile for a fleet or "Unassigned". `GET /api/v1/fleet/enrollment_profiles/automatic` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | integer | query | The fleet ID for which to return the custom enrollment profile, or "Unassigned" if omitted. | #### Example `GET /api/v1/fleet/enrollment_profiles/automatic?fleet_id=123` ##### Default response `Status: 200` ```json { "team_id": 123, "fleet_id": 123, "name": "dep_profile.json", "uploaded_at": "2023-04-04:00:00Z", "enrollment_profile": { "is_mandatory": true, "is_mdm_removable": false } } ``` ### Get Fleet default MDM setup enrollment profile _Available in Fleet Premium_ Gets the Fleet default MDM setup enrollment profile. This is the profile Fleet registers with Apple for devices in fleets that do not have a custom MDM setup enrollment profile uploaded. `GET /api/v1/fleet/enrollment_profiles/automatic/default` The default profile is a single profile per Fleet instance. It is shared across all fleets and all Apple Business Manager (ABM) tokens and cannot be scoped by `fleet_id`. If the default profile has not yet been stored (for example, on a new Fleet instance that has not completed its first automatic enrollment registration), Fleet returns the in-code defaults that will be registered on first use, and `updated_at` is `null`. #### Parameters None. #### Example `GET /api/v1/fleet/enrollment_profiles/automatic/default` ##### Default response `Status: 200` ```json { "updated_at": "2026-04-04T00:00:00Z", "enrollment_profile": { "profile_name": "Fleet default enrollment profile", "is_supervised": true, "is_mdm_removable": false, "skip_setup_items": [] } } ``` > NOTE: The `ConfigurationWebURL` and `URL` values are automatically populated by Fleet at registration time and are not included in this response. ### Delete custom MDM setup enrollment profile _Available in Fleet Premium_ Deletes the custom MDM setup enrollment profile assigned to a fleet or "Unassigned". `DELETE /api/v1/fleet/enrollment_profiles/automatic` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | integer | query | The fleet ID for which to delete the custom enrollment profile, or "Unassigned" if omitted. | #### Example `DELETE /api/v1/fleet/enrollment_profiles/automatic?fleet_id=123` ##### Default response `Status: 204` ### Get Over-the-Air (OTA) enrollment profile `GET /api/v1/fleet/enrollment_profiles/ota` The returned value is a signed `.mobileconfig` OTA enrollment profile (see [Apple enrollment profile docs](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/OTASecurity/OTASecurity.html)). Install this profile on macOS, iOS, or iPadOS hosts to enroll them to a specific fleet in Fleet and turn on MDM features. If the fleet has [Require IdP authentication](https://fleetdm.com/guides/setup-experience#require-idp-authentication) enabled, the OTA enrollment profile won't work. Use the [manual enrollment profile](#get-manual-enrollment-profile) instead. To enroll macOS hosts, turn on MDM features, and add [human-device mapping](https://fleetdm.com/guides/foreign-vitals-map-idp-users-to-hosts), use the [manual enrollment profile](#get-manual-enrollment-profile) instead. #### Parameters | Name | Type | In | Description | |-------------------|---------|-------|----------------------------------------------------------------------------------| | enroll_secret | string | query | **Required**. The enroll secret of the fleet this host will be assigned to. | #### Example `GET /api/v1/fleet/enrollment_profiles/ota?enroll_secret=foobar` ##### Default response `Status: 200` > **Note:** To confirm success, it is important for clients to match content length with the response header (this is done automatically by most clients, including the browser) rather than relying solely on the response status code returned by this endpoint. ##### Example response headers ```http Content-Length: 542 Content-Type: application/x-apple-aspen-config; charset=utf-8 Content-Disposition: attachment;filename="fleet-mdm-enrollment-profile.mobileconfig" X-Content-Type-Options: nosniff ``` ###### Example response body ```xml PayloadContent URL https://foo.example.com/api/fleet/ota_enrollment?enroll_secret=foobar DeviceAttributes UDID VERSION PRODUCT SERIAL PayloadOrganization Acme Inc. PayloadDisplayName Acme Inc. enrollment PayloadVersion 1 PayloadUUID fdb376e5-b5bb-4d8c-829e-e90865f990c9 PayloadIdentifier com.fleetdm.fleet.mdm.apple.ota PayloadType Profile Service ``` ### Get manual enrollment profile Retrieves an unsigned manual enrollment profile for macOS hosts. Install this profile on macOS hosts to turn on MDM features manually. To add [human-device mapping](https://fleetdm.com/guides/foreign-vitals-map-idp-users-to-hosts), [add the end user's email to the enrollment profile](https://fleetdm.com/guides/config-less-fleetd-agent-deployment#using-human-device-mapping). `GET /api/v1/fleet/enrollment_profiles/manual` ##### Example `GET /api/v1/fleet/enrollment_profiles/manual` ##### Default response `Status: 200` ```xml ``` ### Create bootstrap package _Available in Fleet Premium_ Upload a bootstrap package that will be automatically installed during DEP setup. > You need to send a request of type `multipart/form-data`. > This endpoint accepts a maximum request body size of 10GB. `POST /api/v1/fleet/bootstrap` #### Parameters | Name | Type | In | Description | | ------- | ------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | package | file | body | **Required**. The bootstrap package installer. It must be a signed `pkg` file. | | fleet_id | string | body | The fleet ID for the package. If specified, the package will be installed to hosts that are assigned to the specified fleet. If not specified, the package will be installed on "Unassigned" hosts. | | manual_agent_install | boolean | body | If set to `true` Fleet's agent (fleetd) won't be installed as part of automatic enrollment (ADE) on macOS hosts. (Default: `false`) | #### Example Upload a bootstrap package that will be installed to macOS hosts enrolled to MDM that are assigned to a fleet. Note that in this example the form data specifies `fleet_id` in addition to `package`. `POST /api/v1/fleet/bootstrap` ##### Request body ```http fleet_id="1" package="bootstrap-package.pkg" ``` ##### Default response `Status: 200` ### Get bootstrap package metadata _Available in Fleet Premium_ Get information about a bootstrap package that was uploaded to Fleet. `GET /api/v1/fleet/bootstrap/:fleet_id/metadata` #### Parameters | Name | Type | In | Description | | ------- | ------ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | fleet_id | string | url | **Required** The fleet ID for the package. Zero (0) can be specified to get information about the bootstrap package for "Unassigned" hosts. | | for_update | boolean | query | If set to `true`, the authorization will be for a `write` action instead of a `read`. Useful for the write-only `gitops` role when requesting the bootstrap metadata to check if the package needs to be replaced. | #### Example `GET /api/v1/fleet/bootstrap/0/metadata` ##### Default response `Status: 200` ```json { "name": "bootstrap-package.pkg", "team_id": 0, "fleet_id": 0, "sha256": "6bebb4433322fd52837de9e4787de534b4089ac645b0692dfb74d000438da4a3", "token": "AA598E2A-7952-46E3-B89D-526D45F7E233", "created_at": "2023-04-20T13:02:05Z" } ``` In the response above: - `token` is the value you can use to [download a bootstrap package](#download-bootstrap-package) - `sha256` is the SHA256 digest of the bytes of the bootstrap package file. ### Delete bootstrap package _Available in Fleet Premium_ Delete a fleet's bootstrap package. `DELETE /api/v1/fleet/bootstrap/:fleet_id` #### Parameters | Name | Type | In | Description | | ------- | ------ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | fleet_id | string | url | **Required** The fleet ID for the package. Zero (0) can be specified to get information about the bootstrap package for "Unassigned" hosts. | #### Example `DELETE /api/v1/fleet/bootstrap/1` ##### Default response `Status: 200` ### Download bootstrap package _Available in Fleet Premium_ Download a bootstrap package. `GET /api/v1/fleet/bootstrap` #### Parameters | Name | Type | In | Description | | ----- | ------ | ----- | ------------------------------------------------ | | token | string | query | **Required** The token of the bootstrap package. | #### Example `GET /api/v1/fleet/bootstrap?token=AA598E2A-7952-46E3-B89D-526D45F7E233` ##### Default response `Status: 200` ```http Status: 200 Content-Type: application/octet-stream Content-Disposition: attachment Content-Length: Body: ``` ### Get bootstrap package status _Available in Fleet Premium_ Get aggregate status counts of bootstrap packages delivered to DEP enrolled hosts. The summary can optionally be filtered by fleet ID. `GET /api/v1/fleet/bootstrap/summary` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | fleet_id | string | query | The fleet ID to filter the summary. | #### Example `GET /api/v1/fleet/bootstrap/summary` ##### Default response `Status: 200` ```json { "installed": 10, "failed": 1, "pending": 4 } ``` ### Update setup experience _Available in Fleet Premium_ `PATCH /api/v1/fleet/setup_experience` #### Parameters | Name | Type | In | Description | | ------------- | ------ | ---- | -------------------------------------------------------------------------------------- | | fleet_id | integer | body | The fleet ID to apply the settings to. Settings are applied to "Unassigned" hosts if absent. | | enable_end_user_authentication | boolean | body | When enabled, require end users to authenticate with your identity provider (IdP) when they set up their new macOS hosts. | | lock_end_user_info | boolean | body | When enabled, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) | | require_all_software_macos | boolean | body | If set to `true`, setup will be canceled on macOS hosts if any software installs fail. | | require_all_software_windows | boolean | body | If set to `true`, setup will be canceled on Windows hosts if any software installs fail (the host is blocked at the Windows Enrollment Status Page until the device is reset). If `false`, the Enrollment Status Page lists the failed software and the end user can continue to the desktop and install it later via self-service. | | enable_release_device_manually | boolean | body | When enabled, you're responsible for sending the [`DeviceConfigured` command](https://developer.apple.com/documentation/devicemanagement/device-configured-command). End users will be stuck in Setup Assistant until this command is sent. | | manual_agent_install | boolean | body | If set to `true` Fleet's agent (fleetd) won't be installed as part of automatic enrollment (ADE) on macOS hosts. (Default: `false`) | | enable_managed_local_account | boolean | body | _Available in Fleet Premium._ During the Setup experience, a managed local account will be created on macOS hosts if set to true. | | end_user_local_account_type | string | body | Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | #### Example `PATCH /api/v1/fleet/setup_experience` ##### Request body ```json { "team_id": 1, "fleet_id": 1, "enable_end_user_authentication": true, "enable_release_device_manually": true } ``` ##### Default response `Status: 204` ### Create EULA _Available in Fleet Premium_ Upload an EULA that will be shown during the DEP flow. > You need to send a request of type `multipart/form-data`. > This endpoint accepts a maximum request body size of 25MiB. `POST /api/v1/fleet/setup_experience/eula` #### Parameters | Name | Type | In | Description | | ---- | ---- | ---- | ------------------------------------------------- | | eula | file | body | **Required**. A PDF document containing the EULA. | #### Example `POST /api/v1/fleet/setup_experience/eula` ##### Request body ```http eula="eula.pdf" ``` ##### Default response `Status: 200` ### Get EULA metadata _Available in Fleet Premium_ Get information about the EULA file that was uploaded to Fleet. If no EULA was previously uploaded, this endpoint returns a `404` status code. `GET /api/v1/fleet/setup_experience/eula/metadata` #### Example `GET /api/v1/fleet/setup_experience/eula/metadata` ##### Default response `Status: 200` ```json { "name": "eula.pdf", "token": "AA598E2A-7952-46E3-B89D-526D45F7E233", "created_at": "2023-04-20T13:02:05Z" } ``` In the response above: - `token` is the value you can use to [download an EULA](#download-an-eula-file) ### Delete EULA _Available in Fleet Premium_ Delete an EULA file. `DELETE /api/v1/fleet/setup_experience/eula/:token` #### Parameters | Name | Type | In | Description | | ----- | ------ | ----- | ---------------------------------------- | | token | string | path | **Required** The token of the EULA file. | #### Example `DELETE /api/v1/fleet/setup_experience/eula/AA598E2A-7952-46E3-B89D-526D45F7E233` ##### Default response `Status: 200` ### Download EULA _Available in Fleet Premium_ Download an EULA file `GET /api/v1/fleet/setup_experience/eula/:token` #### Parameters | Name | Type | In | Description | | ----- | ------ | ----- | ---------------------------------------- | | token | string | path | **Required** The token of the EULA file. | #### Example `GET /api/v1/fleet/setup_experience/eula/AA598E2A-7952-46E3-B89D-526D45F7E233` ##### Default response `Status: 200` ```http Status: 200 Content-Type: application/pdf Content-Disposition: attachment Content-Length: Body: ``` ### List setup experience software _Available in Fleet Premium_ List software that can be automatically installed during setup. If `install_during_setup` is `true` it will be installed during setup. On Windows and Linux hosts, Fleet checks the software's associated policies first and skips the install when the host passes all of them. Learn more in the [Windows and Linux setup experience guide](https://fleetdm.com/guides/windows-linux-setup-experience#policies-are-checked-before-install). `GET /api/v1/fleet/setup_experience/software` #### Parameters | Name | Type | In | Description | | ----- | ------ | ----- | ---------------------------------------- | | platform | string | query | Filters software titles available for install by platforms. Options are `"macos"`, `"windows"`, `"linux"`, `"ios"`, `"ipados"`, and `"android"`. Defaults to `"macos"`. To show titles from multiple platforms, separate the platforms with commas (e.g. `?platform=macos,ios,android`). | | fleet_id | integer | query | _Available in Fleet Premium_. The ID of the fleet to filter software by. If not specified, it will filter only software that's available for "Unassigned" hosts. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `name` and `hosts_count`. Default is `hosts_count` (descending). | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | #### Example `GET /api/v1/fleet/setup_experience/software?fleet_id=3` ##### Default response `Status: 200` ```json { "software_titles": [ { "id": 12, "name": "Firefox.app", "icon_url": "/api/latest/fleet/software/titles/12/icon?fleet_id=3", "software_package": { "name": "FirefoxInstall.pkg", "platform": "darwin", "version": "125.6", "self_service": true, "install_during_setup": true }, "app_store_app": null, "versions_count": 3, "source": "apps", "hosts_count": 48, "versions": [ { "id": 123, "version": "1.12", "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"] }, { "id": 124, "version": "3.4", "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"] }, { "id": 12, "version": "1.13", "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"] } ] } ], "count": 2, "counts_updated_at": "2024-10-04T10:00:00Z", "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Update setup experience software _Available in Fleet Premium_ Set software that will be automatically installed during setup. Software that isn't included in the request will be unset. `PUT /api/v1/fleet/setup_experience/software` #### Parameters | Name | Type | In | Description | | ----- | ------ | ----- | ---------------------------------------- | | platform | string | query | Platform to install software for. Either `"macos"`, `"windows"`, `"linux"`, `"ios"`, `"ipados"`, or `"android"`. Defaults to `"macos"`. | | fleet_id | integer | query | _Available in Fleet Premium_. The ID of the fleet to set the software for. If not specified, it will set the software for "Unassigned" hosts. | | software_title_ids | array | body | The ID of software titles to install during setup. | #### Example `PUT /api/v1/fleet/setup_experience/software` ##### Request body ```json { "platform": "linux", "team_id": 1, "fleet_id": 1, "software_title_ids": [3000, 3001] } ``` ##### Default response `Status: 200` ```json {} ``` ### Create setup experience script _Available in Fleet Premium_ Add a script that will automatically run during macOS setup. > You need to send a request of type `multipart/form-data`. `POST /api/v1/fleet/setup_experience/script` | Name | Type | In | Description | | ----- | ------ | ----- | ---------------------------------------- | | fleet_id | integer | body | _Available in Fleet Premium_. The ID of the fleet to add the script to. If not specified, a script will be added for "Unassigned" hosts. | | script | file | body | The contents of the script to run during setup. | #### Example `POST /api/v1/fleet/setup_experience/script` ##### Request body ```http fleet_id="1" script="myscript.sh" ``` ##### Default response `Status: 200` ### Get or download setup experience script _Available in Fleet Premium_ Get a script that will automatically run during macOS setup. `GET /api/v1/fleet/setup_experience/script` | Name | Type | In | Description | | ----- | ------ | ----- | ---------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. The ID of the fleet to get the script for. If not specified, script will be returned for "Unassigned" hosts. | | alt | string | query | If specified and set to "media", downloads the script's contents. | #### Example (get script) `GET /api/v1/fleet/setup_experience/script?fleet_id=3` ##### Default response `Status: 200` ```json { "id": 1, "team_id": 3, "fleet_id": 3, "name": "setup-experience-script.sh", "created_at": "2023-07-30T13:41:07Z", "updated_at": "2023-07-30T13:41:07Z" } ``` #### Example (download script) `GET /api/v1/fleet/setup_experience/script?fleet_id=3?alt=media` ##### Example response headers ```http Content-Length: 13 Content-Type: application/octet-stream Content-Disposition: attachment;filename="2023-09-27 script_1.sh" ``` ###### Example response body `Status: 200` ``` echo "hello" ``` ### Delete setup experience script _Available in Fleet Premium_ Delete a script that will automatically run during macOS setup. `DELETE /api/v1/fleet/setup_experience/script` | Name | Type | In | Description | | ----- | ------ | ----- | ---------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. The ID of the fleet to get the script for. If not specified, script will be returned for "Unassigned" hosts. | #### Example `DELETE /api/v1/fleet/setup_experience/script?fleet_id=3` ##### Default response `Status: 200` ### Update managed local account _Available in Fleet Premium_ Edit managed local account enforcement settings for eligible hosts. `POST /api/v1/fleet/managed_local_account` #### Parameters | Name | Type | In | Description | | ------------------------------------ | ------ | ---- | -------------------------------------------------------------------------------------| | fleet_id | integer | body | The fleet ID to apply the settings to. If omitted, settings apply to unassigned hosts.| | enable_managed_local_account | boolean | body | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on eligible hosts if set to true. | | end_user_local_account_type | string | body | Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | #### Example `POST /api/v1/fleet/managed_local_account` ##### Default response `204` ```json { "fleet_id": 3, "enable_managed_local_account": true, "end_user_local_account_type": "admin" } ``` --- ## Commands - [Run MDM command](#run-mdm-command) - [Get MDM command results](#get-mdm-command-results) - [List MDM commands](#list-mdm-commands) ### Run MDM command > `POST /api/v1/fleet/mdm/apple/enqueue` API endpoint is deprecated as of Fleet 4.40. It is maintained for backward compatibility. Please use the new API endpoint below. [Archived documentation](https://github.com/fleetdm/fleet/blob/fleet-v4.39.0/docs/REST%20API/rest-api.md#run-custom-mdm-command) is available for the deprecated endpoint. This endpoint tells Fleet to run a custom MDM command on the targeted macOS, iOS, iPadOS, or Windows hosts the next time they come online. > This endpoint accepts a maximum request body size of 2MiB. `POST /api/v1/fleet/commands/run` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | command | string | json | A Base64 encoded MDM command as described in [Apple's documentation](https://developer.apple.com/documentation/devicemanagement/commands_and_queries) or [Windows's documentation](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-mdm/0353f3d6-dbe2-42b6-b8d5-50db9333bba4). Supported formats are standard and raw (unpadded). You can paste your Base64 code to the [online decoder](https://devpal.co/base64-decode/) to check if you're using the valid format. | | host_uuids | array | json | An array of host UUIDs enrolled in Fleet on which the command should run. | Note that the `EraseDevice` and `DeviceLock` commands are _available in Fleet Premium_ only. #### Example `POST /api/v1/fleet/commands/run` ##### Default response `Status: 200` ```json { "command_uuid": "a2064cef-0000-1234-afb9-283e3c1d487e", "request_type": "ProfileList" } ``` ### Get MDM command results > `GET /api/v1/fleet/mdm/apple/commandresults` API endpoint is deprecated as of Fleet 4.40. It is maintained for backward compatibility. Please use the new API endpoint below. [Archived documentation](https://github.com/fleetdm/fleet/blob/fleet-v4.39.0/docs/REST%20API/rest-api.md#get-custom-mdm-command-results) is available for the deprecated endpoint. This endpoint returns the results for a specific custom MDM command. In the response, the possible `status` values for macOS, iOS, and iPadOS hosts are the following: * Pending: the command has yet to run on the host. The host will run the command the next time it comes online. * NotNow: the host acknowledged the MDM command but couldn’t run for one of [Apple's documented reasons](https://developer.apple.com/documentation/devicemanagement/handling-notnow-status-responses#Handle-NotNow-Responses). Per Apple, the host retries automatically. Apple doesn’t specify when the retries happen, or whether they depend on clearing _all_ blocking reasons or just one. * Acknowledged: the host responded with "Acknowledged" status via the MDM protocol: the host processed the command successfully. * Error: the host responded with "Error" status via the MDM protocol: an error occurred. Run the `fleetctl get mdm-command-results --id= Note: If the server has not yet received a result for a command, it will return an empty object (`{}`). ### List MDM commands > `GET /api/v1/fleet/mdm/apple/commands` API endpoint is deprecated as of Fleet 4.40. It is maintained for backward compatibility. Please use the new API endpoint below. [Archived documentation](https://github.com/fleetdm/fleet/blob/fleet-v4.39.0/docs/REST%20API/rest-api.md#list-custom-mdm-commands) is available for the deprecated endpoint. This endpoint returns the list of custom MDM commands that have been executed. `GET /api/v1/fleet/commands` #### Parameters | Name | Type | In | Description | | ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | | host_identifier | string | query | **Required.** The host's `hostname`, `uuid`, or `hardware_serial`. Returns only commands that target the specified host. Omitting `host_identifier` is deprecated (see the deprecation notice below). Requests w/o it continue to work for backward compatibility but are not recommended; the underlying query is not performant at scale and may time out on large fleets. Support will be removed in Fleet 5. | | page | integer | query | Page number of the results to fetch. Maximum is `100`. | | per_page | integer | query | Results per page. Default is `10`. Maximum is 1,000 records. | | order_key | string | query | What to order results by. Allowed values: `host_uuid`, `command_uuid`, `status`, `updated_at`, `request_type`, `hostname`. Default is `updated_at`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | request_type | string | query | The request type to filter commands by. | | command_status | string | query | Comma-separated string of one of the following options: 'ran', 'pending', or 'failed'. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | > Currently, `⁠command_status` is only available when ⁠`host_identifier` is provided and the host is macOS, iOS, or iPadOS. Additionally, ⁠`count` is returned only when ⁠`command_status` is `⁠pending`; for any other values, ⁠`count` will be `⁠null`. > > Apple (macOS, iOS, iPadOS) MDM commands that 'ran' have an 'Acknowledged' `status`. Commands that are 'pending' have a 'Pending' or 'NotNow' `status`. Apple commands that 'failed' have an 'Error' `status`. > > Apple (macOS, iOS, iPadOS) InstallProfile and RemoveProfile commands enqueued by Fleet going forward will have a non-`null` "name" which represents the profile name. Previously-enqueued(prior to v4.84.0) or manually-enqueued commands will have a `null` name, as will other types of Apple MDM commands and all Windows commands. #### Example `GET /api/v1/fleet/commands?host_identifier=A1B2C3D4-E5F6-7890-1234-567890ABCDEF&per_page=5` ##### Default response `Status: 200` ```json { "meta": { "has_next_results": true, "has_previous_results": false }, "count": null, "results": [ { "host_uuid": "A1B2C3D4-E5F6-7890-1234-567890ABCDEF", "command_uuid": "a3650ec9-6dd0-40e9-b5d8-feffe9939461", "status": "Acknowledged", "command_status": "ran", "updated_at": "2026-03-20T19:45:27Z", "request_type": "DeclarativeManagement", "name": null, "hostname": "Mac-mini.local" }, { "host_uuid": "A1B2C3D4-E5F6-7890-1234-567890ABCDEF", "command_uuid": "97ceaa39-eadc-4953-98a8-2ffe72ab120d", "status": "Error", "command_status": "failed", "updated_at": "2026-03-24T21:37:32Z", "request_type": "InstallProfile", "name": null, "hostname": "Mac-mini.local" } ] } ``` --- ## Integrations - [Get Apple Push Notification service (APNs)](#get-apple-push-notification-service-apns) - [List Apple Business (AB) tokens](#list-apple-business-ab-tokens) - [List Volume Purchasing Program (VPP) tokens](#list-volume-purchasing-program-vpp-tokens) - [Get Android Enterprise](#get-android-enterprise) ### Get Apple Push Notification service (APNs) `GET /api/v1/fleet/apns` #### Parameters None. #### Example `GET /api/v1/fleet/apns` ##### Default response `Status: 200` ```json { "common_name": "APSP:04u52i98aewuh-xxxx-xxxx-xxxx-xxxx", "serial_number": "1234567890987654321", "issuer": "Apple Application Integration 2 Certification Authority", "renew_date": "2023-09-30T00:00:00Z" } ``` ### List Apple Business (AB) tokens _Available in Fleet Premium_ `GET /api/v1/fleet/ab_tokens` #### Parameters None. #### Example `GET /api/v1/fleet/ab_tokens` ##### Default response `Status: 200` ```json { "ab_tokens": [ { "id": 1, "apple_id": "apple@example.com", "org_name": "Fleet Device Management Inc.", "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2023-11-29T00:00:00Z", "terms_expired": false, "macos_fleet": { "name": "💻 Workstations", "fleet_id": 1 }, "ios_fleet": { "name": "📱🏢 Company-owned iPhones", "fleet_id": 2 }, "ipados_fleet": { "name": "🔳🏢 Company-owned iPads", "fleet_id": 3 } } ], "abm_tokens": [ { "id": 1, "apple_id": "apple@example.com", "org_name": "Fleet Device Management Inc.", "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2023-11-29T00:00:00Z", "terms_expired": false, "token_invalid": false, "macos_team": { "name": "💻 Workstations", "id": 1 }, "macos_fleet": { "name": "💻 Workstations", "id": 1 }, "ios_team": { "name": "📱🏢 Company-owned iPhones", "id": 2 }, "ios_fleet": { "name": "📱🏢 Company-owned iPhones", "id": 2 }, "ipados_team": { "name": "🔳🏢 Company-owned iPads", "id": 3 }, "ipados_fleet": { "name": "🔳🏢 Company-owned iPads", "id": 3 }, "byod_team": { "name": "📱 BYOD iPhones", "id": 4 }, "byod_fleet": { "name": "📱 BYOD iPhones", "id": 4 } } ] } ``` ### List Volume Purchasing Program (VPP) tokens _Available in Fleet Premium_ `GET /api/v1/fleet/vpp_tokens` #### Parameters None. #### Example `GET /api/v1/fleet/vpp_tokens` ##### Default response `Status: 200` ```json { "vpp_tokens": [ { "id": 1, "org_name": "Fleet Device Management Inc.", "location": "https://example.com/mdm/apple/mdm", "country_code": "us", "renew_date": "2023-11-29T00:00:00Z", "teams": [ { "name": "💻 Workstations", "team_id": 1 }, { "name": "💻🐣 Workstations (canary)", "team_id": 2 }, { "name": "📱🏢 Company-owned iPhones", "team_id": 3 }, { "name": "🔳🏢 Company-owned iPads", "team_id": 4 } ], "fleets": [ { "name": "💻 Workstations", "fleet_id": 1 }, { "name": "💻🐣 Workstations (canary)", "fleet_id": 2 }, { "name": "📱🏢 Company-owned iPhones", "fleet_id": 3 }, { "name": "🔳🏢 Company-owned iPads", "fleet_id": 4 } ] } ] } ``` ### Get Android Enterprise Get info about Android Enterprise that's connected to Fleet. `GET /api/v1/fleet/android_enterprise` #### Parameters None. #### Example `GET /api/v1/fleet/android_enterprise` ##### Default response `Status: 200` ```json { "android_enterprise_id": "LC0445szuv" } ``` --- ## SCIM - [List users](#list-scim-users) - [Create user](#create-scim-user) - [Get user](#get-scim-user) - [Replace user](#replace-scim-user) - [Update user](#update-scim-user) - [Delete user](#delete-scim-user) - [List groups](#list-scim-groups) - [Create group](#create-scim-group) - [Get group](#get-scim-group) - [Replace group](#replace-scim-group) - [Update group](#update-scim-group) - [Delete group](#delete-scim-group) - [Get schemas](#get-scim-schemas) - [Get service provider config](#get-scim-service-provider-config) - [Get resource types](#get-scim-resource-types) - [Get identity provider (IdP) details](#get-identity-provider-idp-details) Fleet's SCIM ([System for Cross-domain Identity Management](https://datatracker.ietf.org/doc/html/rfc7644)) API endpoints are used to [map end user's identity providers (IdPs) details](https://fleetdm.com/guides/foreign-vitals-map-idp-users-to-hosts) to their hosts and automatically delete a user's Fleet account when the user is deleted or deactivated in the IdP. SCIM resource type names (e.g. `Users`, `Groups`, `Schemas`) are defined by the [SCIM spec](https://datatracker.ietf.org/doc/html/rfc7644#section-2) and must be capitalized exactly as shown to work with identity providers. This is why they differ from Fleet's usual lowercase API naming convention. ### List SCIM users _Available in Fleet Premium_ `GET /api/v1/fleet/scim/Users` #### Parameters | Name | Type | In | Description | | ---------- | ------- | ----- | ------------------------------------------------------------------------------------------------------ | | startIndex | integer | query | 1-based index of the first result to return. Defaults to 1. | | count | integer | query | Number of results per page. Maximum 100. Defaults to 100. | | filter | string | query | SCIM filter expression. Only `userName eq ""` and `emails[type eq ""].value eq ""` are supported. | #### Example `GET /api/v1/fleet/scim/Users` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 1, "startIndex": 1, "itemsPerPage": 100, "Resources": [ { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "1", "externalId": "ext-123", "userName": "user@example.com", "name": { "givenName": "Jane", "familyName": "Doe" }, "emails": [ { "value": "user@example.com", "type": "work", "primary": true } ], "active": true, "groups": [], "meta": { "resourceType": "User" } } ] } ``` --- ### Create SCIM user _Available in Fleet Premium_ `POST /api/v1/fleet/scim/Users` #### Parameters | Name | Type | In | Description | | -------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------- | | schemas | array | body | **Required**. Must include `"urn:ietf:params:scim:schemas:core:2.0:User"`. | | userName | string | body | **Required**. Unique username (typically an email address). | | name.givenName | string | body | **Required**. User's first name. | | name.familyName | string | body | **Required**. User's last name. | | externalId | string | body | Optional. External identifier from the IdP. | | emails | array | body | Optional. List of email objects with `value`, `type`, and `primary` fields. | | active | boolean | body | Optional. Whether the user account is active. | | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department | string | body | Optional. User's department. | #### Example `POST /api/v1/fleet/scim/Users` ##### Request body ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "user@example.com", "externalId": "ext-123", "name": { "givenName": "Jane", "familyName": "Doe" }, "emails": [ { "value": "user@example.com", "type": "work", "primary": true } ], "active": true } ``` ##### Default response `Status: 201` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "1", "externalId": "ext-123", "userName": "user@example.com", "name": { "givenName": "Jane", "familyName": "Doe" }, "emails": [ { "value": "user@example.com", "type": "work", "primary": true } ], "active": true, "groups": [], "meta": { "resourceType": "User" } } ``` --- ### Get SCIM user _Available in Fleet Premium_ `GET /api/v1/fleet/scim/Users/:id` #### Parameters | Name | Type | In | Description | | ---- | ------ | ---- | ---------------------------- | | id | string | path | **Required**. The user's ID. | #### Example `GET /api/v1/fleet/scim/Users/1` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "1", "externalId": "ext-123", "userName": "user@example.com", "name": { "givenName": "Jane", "familyName": "Doe" }, "emails": [ { "value": "user@example.com", "type": "work", "primary": true } ], "active": true, "groups": [ { "value": "group-1", "$ref": "Groups/group-1", "display": "Engineering" } ], "meta": { "resourceType": "User" } } ``` --- ### Replace SCIM user _Available in Fleet Premium_ Replaces all attributes of an existing user. Any attributes not included in the request body are cleared. `PUT /api/v1/fleet/scim/Users/:id` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ---- | -------------------------------------------------------------------------------- | | id | string | path | **Required**. The user's ID. | | schemas | array | body | **Required**. Must include `"urn:ietf:params:scim:schemas:core:2.0:User"`. | | userName | string | body | **Required**. Unique username. | | name.givenName | string | body | **Required**. User's first name. | | name.familyName | string | body | **Required**. User's last name. | | externalId | string | body | Optional. External identifier from the IdP. | | emails | array | body | Optional. List of email objects with `value`, `type`, and `primary` fields. | | active | boolean | body | Optional. Whether the user account is active. | | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department | string | body | Optional. User's department. | #### Example `PUT /api/v1/fleet/scim/Users/1` ##### Request body ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "user@example.com", "name": { "givenName": "Jane", "familyName": "Smith" }, "active": true } ``` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "1", "userName": "user@example.com", "name": { "givenName": "Jane", "familyName": "Smith" }, "active": true, "groups": [], "meta": { "resourceType": "User" } } ``` --- ### Update SCIM user _Available in Fleet Premium_ Partially updates a user using SCIM patch operations. Supports `add`, `replace`, and `remove` operations on `userName`, `externalId`, `active`, `name.givenName`, `name.familyName`, `emails`, and `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department`. `PATCH /api/v1/fleet/scim/Users/:id` #### Parameters | Name | Type | In | Description | | ---------- | ------ | ---- | ---------------------------------------------------------------------- | | id | string | path | **Required**. The user's ID. | | schemas | array | body | **Required**. Must include `"urn:ietf:params:scim:api:messages:2.0:PatchOp"`. | | Operations | array | body | **Required**. List of patch operations. Each has `op`, optional `path`, and `value`. | #### Example `PATCH /api/v1/fleet/scim/Users/1` ##### Request body ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace", "path": "active", "value": false } ] } ``` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "1", "userName": "user@example.com", "name": { "givenName": "Jane", "familyName": "Doe" }, "active": false, "groups": [], "meta": { "resourceType": "User" } } ``` --- ### Delete SCIM user _Available in Fleet Premium_ `DELETE /api/v1/fleet/scim/Users/:id` #### Parameters | Name | Type | In | Description | | ---- | ------ | ---- | ---------------------------- | | id | string | path | **Required**. The user's ID. | #### Example `DELETE /api/v1/fleet/scim/Users/1` ##### Default response `Status: 204` No content. --- ### List SCIM groups _Available in Fleet Premium_ `GET /api/v1/fleet/scim/Groups` #### Parameters | Name | Type | In | Description | | ------------------ | ------- | ----- | ---------------------------------------------------------------------------------------- | | startIndex | integer | query | 1-based index of the first result to return. Defaults to 1. | | count | integer | query | Number of results per page. Maximum 100. Defaults to 100. | | filter | string | query | SCIM filter expression. Only `displayName eq ""` is supported. | | excludedAttributes | string | query | Comma-separated list of attributes to exclude. Use `members` to omit group member lists. | #### Example `GET /api/v1/fleet/scim/Groups` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 1, "startIndex": 1, "itemsPerPage": 100, "Resources": [ { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "group-1", "externalId": "ext-group-123", "displayName": "Engineering", "members": [ { "value": "1", "type": "User" } ], "meta": { "resourceType": "Group" } } ] } ``` --- ### Create SCIM group _Available in Fleet Premium_ `POST /api/v1/fleet/scim/Groups` #### Parameters | Name | Type | In | Description | | ----------- | ------ | ---- | ------------------------------------------------------------------------------------------ | | schemas | array | body | **Required**. Must include `"urn:ietf:params:scim:schemas:core:2.0:Group"`. | | displayName | string | body | **Required**. Human-readable group name. Must be unique. | | externalId | string | body | Optional. External identifier from the IdP. | | members | array | body | Optional. List of member objects with a `value` field containing a SCIM user ID. | #### Example `POST /api/v1/fleet/scim/Groups` ##### Request body ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Engineering", "members": [ { "value": "1" } ] } ``` ##### Default response `Status: 201` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "group-1", "displayName": "Engineering", "members": [ { "value": "1", "type": "User" } ], "meta": { "resourceType": "Group" } } ``` --- ### Get SCIM group _Available in Fleet Premium_ `GET /api/v1/fleet/scim/Groups/:id` #### Parameters | Name | Type | In | Description | | ------------------ | ------ | ----- | ---------------------------------------------------------------------------------------- | | id | string | path | **Required**. The group's ID (format: `group-`). | | excludedAttributes | string | query | Comma-separated list of attributes to exclude. Use `members` to omit the member list. | #### Example `GET /api/v1/fleet/scim/Groups/group-1` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "group-1", "externalId": "ext-group-123", "displayName": "Engineering", "members": [ { "value": "1", "type": "User" } ], "meta": { "resourceType": "Group" } } ``` --- ### Replace SCIM group _Available in Fleet Premium_ Replaces all attributes of an existing group. Any attributes not included in the request body are cleared. `PUT /api/v1/fleet/scim/Groups/:id` #### Parameters | Name | Type | In | Description | | ----------- | ------ | ---- | ------------------------------------------------------------------------------------------ | | id | string | path | **Required**. The group's ID (format: `group-`). | | schemas | array | body | **Required**. Must include `"urn:ietf:params:scim:schemas:core:2.0:Group"`. | | displayName | string | body | **Required**. Human-readable group name. Must be unique. | | externalId | string | body | Optional. External identifier from the IdP. | | members | array | body | Optional. List of member objects with a `value` field containing a SCIM user ID. | #### Example `PUT /api/v1/fleet/scim/Groups/group-1` ##### Request body ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Engineering", "members": [ { "value": "1" }, { "value": "2" } ] } ``` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "group-1", "displayName": "Engineering", "members": [ { "value": "1", "type": "User" }, { "value": "2", "type": "User" } ], "meta": { "resourceType": "Group" } } ``` --- ### Update SCIM group _Available in Fleet Premium_ Partially updates a group using SCIM patch operations. Supports `add`, `replace`, and `remove` operations on `displayName`, `externalId`, and `members`. `PATCH /api/v1/fleet/scim/Groups/:id` #### Parameters | Name | Type | In | Description | | ---------- | ------ | ---- | ------------------------------------------------------------------------------------- | | id | string | path | **Required**. The group's ID (format: `group-`). | | schemas | array | body | **Required**. Must include `"urn:ietf:params:scim:api:messages:2.0:PatchOp"`. | | Operations | array | body | **Required**. List of patch operations. Each has `op`, optional `path`, and `value`. | #### Example `PATCH /api/v1/fleet/scim/Groups/group-1` ##### Request body ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "add", "path": "members", "value": [ { "value": "3" } ] } ] } ``` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "group-1", "displayName": "Engineering", "members": [ { "value": "1", "type": "User" }, { "value": "3", "type": "User" } ], "meta": { "resourceType": "Group" } } ``` --- ### Delete SCIM group _Available in Fleet Premium_ `DELETE /api/v1/fleet/scim/Groups/:id` #### Parameters | Name | Type | In | Description | | ---- | ------ | ---- | -------------------------------------------------------- | | id | string | path | **Required**. The group's ID (format: `group-`). | #### Example `DELETE /api/v1/fleet/scim/Groups/group-1` ##### Default response `Status: 204` No content. --- ### Get SCIM schemas _Available in Fleet Premium_ Returns the SCIM schemas supported by Fleet: the core User schema and Group schema. `GET /api/v1/fleet/scim/Schemas` #### Parameters None. #### Example `GET /api/v1/fleet/scim/Schemas` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 2, "Resources": [ { "id": "urn:ietf:params:scim:schemas:core:2.0:User", "name": "User", "description": "SCIM User" }, { "id": "urn:ietf:params:scim:schemas:core:2.0:Group", "name": "Group", "description": "SCIM Group" } ] } ``` --- ### Get SCIM service provider config _Available in Fleet Premium_ Returns Fleet's SCIM service provider configuration, including supported features. `GET /api/v1/fleet/scim/ServiceProviderConfig` #### Parameters None. #### Example `GET /api/v1/fleet/scim/ServiceProviderConfig` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"], "documentationUri": "https://fleetdm.com/docs/get-started/why-fleet", "patch": { "supported": true }, "filter": { "supported": true, "maxResults": 100 }, "bulk": { "supported": false }, "changePassword": { "supported": false }, "sort": { "supported": false }, "etag": { "supported": false } } ``` --- ### Get SCIM resource types _Available in Fleet Premium_ Returns the resource types supported by Fleet's SCIM implementation (`User` and `Group`). `GET /api/v1/fleet/scim/ResourceTypes` #### Parameters None. #### Example `GET /api/v1/fleet/scim/ResourceTypes` ##### Default response `Status: 200` ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "totalResults": 2, "Resources": [ { "id": "User", "name": "User", "description": "User Account", "endpoint": "/Users", "schema": "urn:ietf:params:scim:schemas:core:2.0:User" }, { "id": "Group", "name": "Group", "description": "Group", "endpoint": "/Groups", "schema": "urn:ietf:params:scim:schemas:core:2.0:Group" } ] } ``` --- ### Get identity provider (IdP) details _Available in Fleet Premium_ Get details about the most recent SCIM request from your identity provider (IdP). Useful for diagnosing SCIM integration issues. `GET /api/v1/fleet/scim/details` #### Parameters None. #### Example `GET /api/v1/fleet/scim/details` ##### Default response `Status: 200` ```json { "last_request": { "requested_at": "2025-03-11T02:02:17Z", "status": "success", "details": "" } } ``` --- ## Policies - [List policies](#list-policies) - [List fleet-level policies](#list-fleet-level-policies) - [Get policies count](#get-policies-count) - [Get fleet-level policies count](#get-fleet-level-policies-count) - [Get policy](#get-policy) - [Get fleet-level policy](#get-fleet-level-policy) - [Create policy](#create-policy) - [Create fleet-level policy](#create-fleet-level-policy) - [Delete policies](#delete-policies) - [Delete fleet-level policies](#delete-fleet-level-policies) - [Update policy](#update-policy) - [Update fleet-level policy](#update-fleet-level-policy) - [Reset policy automations](#reset-policy-automations) Policies are yes or no questions you can ask about your hosts. Policies in Fleet are defined by osquery queries. A passing host answers "yes" to a policy if the host returns results for a policy's query. A failing host answers "no" to a policy if the host does not return results for a policy's query. For example, a policy might ask "Is Gatekeeper enabled on macOS devices?" This policy's osquery query might look like the following: `SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;` ### List policies `GET /api/v1/fleet/global/policies` #### Parameters | Name | Type | In | Description | | ----------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `id`, `name`, `team_id`, `created_at`, `updated_at`, `failing_host_count`, and `passing_host_count`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | platform | string | query | Filters policies by targeted platform. Accepts `"darwin"`, `"windows"`, `"linux"`, or `"chrome"`. Policies that target all platforms (empty `platform` field) are always included. | #### Example `GET /api/v1/fleet/global/policies` ##### Default response `Status: 200` ```json { "policies": [ { "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", "labels_include_any": ["Macs on Sonoma"] }, { "id": 2, "name": "Windows machines with encrypted hard disks", "query": "SELECT 1 FROM bitlocker_info WHERE protection_status = 1;", "description": "Checks if the hard disk is encrypted on Windows devices", "critical": true, "author_id": 43, "author_name": "Alice", "author_email": "alice@example.com", "team_id": null, "resolution": "Resolution steps", "platform": "windows", "created_at": "2021-12-31T14:52:27Z", "updated_at": "2022-02-10T20:59:35Z", "passing_host_count": 2300, "failing_host_count": 0, "host_count_updated_at": "2023-12-20T15:23:57Z", "labels_exclude_any": ["Compliance exclusions", "Workstations (Canary)"] } ] } ``` --- ### List fleet-level policies _Available in Fleet Premium_ `GET /api/v1/fleet/fleets/:id/policies` #### Parameters | Name | Type | In | Description | | ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- | | id | integer | path | **Required.** Defines what fleet ID to operate on | | merge_inherited | boolean | query | If `true`, will return both fleet policies **and** inherited ("All fleets") policies in the `policies` list, and will not return a separate `inherited_policies` list. | | query | string | query | Search query keywords. Searchable fields include `name`. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `id`, `name`, `team_id`, `created_at`, `updated_at`, `failing_host_count`, and `passing_host_count`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | | automation_type | string | query | Filters by automation type. Supported values are "software", "scripts", "calendar", "conditional_access", and "other". | | platform | string | query | Filters policies by targeted platform. Accepts `"darwin"`, `"windows"`, `"linux"`, or `"chrome"`. Policies that target all platforms (empty `platform` field) are always included. | #### Example (default usage) `GET /api/v1/fleet/fleets/1/policies` ##### Default response `Status: 200` ```json { "policies": [ { "id": 1, "name": "Gatekeeper enabled", "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;", "description": "Checks if gatekeeper is enabled on macOS devices", "type": "dynamic", "critical": true, "author_id": 42, "author_name": "John", "author_email": "john@example.com", "team_id": 1, "resolution": "Resolution steps", "platform": "darwin", "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 2000, "failing_host_count": 300, "host_count_updated_at": "2023-12-20T15:23:57Z", "calendar_events_enabled": true, "conditional_access_enabled": true, "labels_include_any": ["Macs on Sonoma"] }, { "id": 2, "name": "Windows machines with encrypted hard disks", "query": "SELECT 1 FROM bitlocker_info WHERE protection_status = 1;", "description": "Checks if the hard disk is encrypted on Windows devices", "critical": false, "type": "dynamic", "author_id": 43, "author_name": "Alice", "author_email": "alice@example.com", "team_id": 1, "resolution": "Resolution steps", "platform": "windows", "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 2300, "failing_host_count": 0, "host_count_updated_at": "2023-12-20T15:23:57Z", "calendar_events_enabled": false, "conditional_access_enabled": false, "labels_exclude_any": ["Compliance exclusions", "Workstations (Canary)"], "run_script": { "name": "Encrypt Windows disk with BitLocker", "id": 234 } }, { "id": 3, "name": "macOS - Adobe Acrobat up to date", "query": "SELECT 1 FROM apps WHERE bundle_identifier = 'com.adobe.Reader' AND version_compare(bundle_short_version, '23.001.20687') >= 0;", "description": "Checks if the hard disk is encrypted on Windows devices", "critical": false, "type": "patch", "author_id": 43, "author_name": "Alice", "author_email": "alice@example.com", "team_id": 1, "resolution": "Resolution steps", "platform": "darwin", "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 2300, "failing_host_count": 3, "host_count_updated_at": "2023-12-20T15:23:57Z", "calendar_events_enabled": false, "conditional_access_enabled": false, "install_software": { "name": "Adobe Acrobat", "software_title_id": 1234 } } ], "inherited_policies": [ { "id": 136, "name": "Arbitrary Test Policy (all platforms) (all fleets)", "query": "SELECT 1 FROM osquery_info WHERE 1=1;", "description": "If you're seeing this, mostly likely this is because someone is testing out failing policies in dogfood. You can ignore this.", "critical": true, "author_id": 77, "author_name": "Test Admin", "author_email": "test@admin.com", "team_id": null, "resolution": "To make it pass, change \"1=0\" to \"1=1\". To make it fail, change \"1=1\" to \"1=0\".", "platform": "darwin,windows,linux", "created_at": "2022-08-04T19:30:18Z", "updated_at": "2022-08-30T15:08:26Z", "passing_host_count": 10, "failing_host_count": 9, "host_count_updated_at": "2023-12-20T15:23:57Z" } ] } ``` #### Example (returns single list) `GET /api/v1/fleet/fleets/1/policies?merge_inherited=true` ##### Default response `Status: 200` ```json { "policies": [ { "id": 1, "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": 1, "resolution": "Resolution steps", "platform": "darwin", "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 2000, "failing_host_count": 300, "host_count_updated_at": "2023-12-20T15:23:57Z", "calendar_events_enabled": false, "conditional_access_enabled": false, "fleet_maintained": false, "labels_include_any": ["Macs on Sonoma"] }, { "id": 2, "name": "Windows machines with encrypted hard disks", "query": "SELECT 1 FROM bitlocker_info WHERE protection_status = 1;", "description": "Checks if the hard disk is encrypted on Windows devices", "critical": false, "author_id": 43, "author_name": "Alice", "author_email": "alice@example.com", "team_id": 1, "resolution": "Resolution steps", "platform": "windows", "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 2300, "failing_host_count": 0, "host_count_updated_at": "2023-12-20T15:23:57Z", "calendar_events_enabled": false, "conditional_access_enabled": false, "fleet_maintained": false }, { "id": 136, "name": "Arbitrary Test Policy (all platforms) (all fleets)", "query": "SELECT 1 FROM osquery_info WHERE 1=1;", "description": "If you're seeing this, mostly likely this is because someone is testing out failing policies in dogfood. You can ignore this.", "critical": true, "author_id": 77, "author_name": "Test Admin", "author_email": "test@admin.com", "team_id": null, "resolution": "To make it pass, change \"1=0\" to \"1=1\". To make it fail, change \"1=1\" to \"1=0\".", "platform": "darwin,windows,linux", "created_at": "2022-08-04T19:30:18Z", "updated_at": "2022-08-30T15:08:26Z", "passing_host_count": 10, "failing_host_count": 9, "host_count_updated_at": "2023-12-20T15:23:57Z", "fleet_maintained": false } ] } ``` --- ### Get policies count `GET /api/v1/fleet/policies/count` #### Parameters | Name | Type | In | Description | | ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- | | query | string | query | Search query keywords. Searchable fields include `name`. | | platform | string | query | Filters policies by targeted platform. Accepts `"darwin"`, `"windows"`, `"linux"`, or `"chrome"`. Policies that target all platforms (empty `platform` field) are always included. | #### Example `GET /api/v1/fleet/policies/count` ##### Default response `Status: 200` ```json { "count": 43 } ``` --- ### Get fleet-level policies count _Available in Fleet Premium_ `GET /api/v1/fleet/fleets/:fleet_id/policies/count` #### Parameters | Name | Type | In | Description | | ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- | | fleet_id | integer | path | **Required.** Defines what fleet ID to operate on | query | string | query | Search query keywords. Searchable fields include `name`. | | merge_inherited | boolean | query | If `true`, will include inherited ("All fleets") policies in the count. | | automation_type | string | query | Filters by automation type. Supported values are "software", "scripts", "calendar", "conditional_access", and "other". | | platform | string | query | Filters policies by targeted platform. Accepts `"darwin"`, `"windows"`, `"linux"`, or `"chrome"`. Policies that target all platforms (empty `platform` field) are always included. | #### Example `GET /api/v1/fleet/fleets/1/policies/count` ##### Default response `Status: 200` ```json { "count": 43 } ``` --- ### Get policy `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 fleet-level policy _Available in Fleet Premium_ `GET /api/v1/fleet/fleets/:fleet_id/policies/:policy_id` #### Parameters | Name | Type | In | Description | | ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- | | fleet_id | integer | path | **Required.** Defines what fleet ID to operate on | | policy_id | integer | path | **Required.** The policy's ID. | #### Example `GET /api/v1/fleet/fleets/1/policies/43` ##### 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, "type": "dynamic", "author_id": 42, "author_name": "John", "author_email": "john@example.com", "team_id": 1, "resolution": "Resolution steps", "platform": "darwin", "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 0, "failing_host_count": 0, "host_count_updated_at": null, "calendar_events_enabled": true, "conditional_access_enabled": false, "fleet_maintained": false, "labels_include_any": ["Macs on Sonoma"], "patch_software": { "display_name": "", "name": "Adobe Acrobat.app", "software_title_id": 1234 }, "install_software": { "name": "Adobe Acrobat.app", "software_title_id": 1234 }, "run_script": { "name": "Enable gatekeeper", "id": 1337 } } } ``` --- ### Create 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. | | labels_include_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. | | labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. | | labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **any of these** labels. | | labels_exclude_all | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **all of these** labels. | Only one set of label targets (`labels_include_any`/`labels_include_all`) and one set of label exclusions (`labels_exclude_any`/`labels_exclude_all`) can be specified. If none are set, all hosts on the specified `platform` are targeted. #### Example `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, "labels_include_any": ["Macs on Sonoma"] } } ``` --- ### Create fleet-level policy _Available in Fleet Premium_ The semantics for creating a fleet policy are the same as for global policies, see [Create policy](#create-policy). `POST /api/v1/fleet/fleets/:id/policies` #### Parameters | Name | Type | In | Description | |-------------------| ------- | ---- |--------------------------------------------------------------------------------------------------------------------------------------------------------| | id | integer | path | Defines what fleet ID to operate on. | | 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. Critical policies can never bypass conditional access. | | type | string | body | The type of the policy. Options are `"dynamic"` (classic policy with an editable query) or `"patch"` (tied to `patch_software_title_id` and automatically updated to include the newest Fleet-maintained app version). If not specified, defaults to `"dynamic"`. | | patch_software_title_id | integer | body | _Available in Fleet Premium_. ID of the software title (Fleet-maintained only) to create a patch policy for. Required if `type` is `patch`. | | calendar_events_enabled | boolean | body | _Available in Fleet Premium_. Whether to trigger calendar events when policy is failing. | | conditional_access_enabled | boolean | body | _Available in Fleet Premium_. Whether to block single sign-on for end users whose hosts fail this policy. | | software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. If `software_title_id` is specified and the software has `labels_include_any` or `labels_exclude_any` defined, the policy will inherit this target in addition to specified `platform`. | | script_id | integer | body | _Available in Fleet Premium_. ID of script to run if the policy fails. | | continuous_automations_enabled | boolean | body | _Available in Fleet Premium_. If enabled, software and script automations will run every time Fleet receives a failing response from a host. If not, all automations run on a host's first failure, and when a host's response changes from pass to fail. | | labels_include_any | array | form | Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. | | labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. | | labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **any of these** labels. | | labels_exclude_all | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **all of these** labels. | Either `query` or `query_id` must be provided. Only one set of label targets (`labels_include_any`/`labels_include_all`) and one set of label exclusions (`labels_exclude_any`/`labels_exclude_all`) can be specified. If none are set, all hosts on the specified `platform` are targeted. #### Example `POST /api/v1/fleet/fleets/1/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", "critical": true, "resolution": "Resolution steps", "platform": "darwin" } ``` ##### 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": 1, "fleet_id": 1, "resolution": "Resolution steps", "platform": "darwin", "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 0, "failing_host_count": 0, "host_count_updated_at": null, "calendar_events_enabled": false, "labels_include_any": ["Macs on Sonoma"], "install_software": { "name": "Adobe Acrobat.app", "software_title_id": 1234 }, "run_script": { "name": "Enable gatekeeper", "id": 1337 } } } ``` --- ### 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 fleet-level policies _Available in Fleet Premium_ `POST /api/v1/fleet/fleets/:fleet_id/policies/delete` #### Parameters | Name | Type | In | Description | | -------- | ------- | ---- | ------------------------------------------------- | | fleet_id | integer | path | **Required.** Defines what fleet ID to operate on | | ids | array | body | **Required.** The IDs of the policies to delete. | #### Example `POST /api/v1/fleet/fleets/1/policies/delete` ##### Request body ```json { "ids": [ 1 ] } ``` ##### Default response `Status: 200` ```json { "deleted": 1 } ``` --- ### Update 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. | | labels_include_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. | | labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. | | labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **any of these** labels. | | labels_exclude_all | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **all of these** labels. | Only one set of label targets (`labels_include_any`/`labels_include_all`) and one set of label exclusions (`labels_exclude_any`/`labels_exclude_all`) can be specified. If none are set, all hosts on the specified `platform` are targeted. #### 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 } } ``` --- ### Update fleet-level policy _Available in Fleet Premium_ `PATCH /api/v1/fleet/fleets/:fleet_id/policies/:policy_id` #### Parameters | Name | Type | In | Description | |-------------------------| ------- | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------| | fleet_id | integer | path | The fleet's ID. | | policy_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. Critical policies can never bypass conditional access. | | calendar_events_enabled | boolean | body | _Available in Fleet Premium_. Whether to trigger calendar events when policy is failing. | | conditional_access_enabled | boolean | body | _Available in Fleet Premium_. Whether to block single sign-on for end users whose hosts fail this policy. | | software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. Set to `null` to remove the automation. | | script_id | integer | body | _Available in Fleet Premium_. ID of script to run if the policy fails. Set to `null` to remove the automation. | | continuous_automations_enabled | boolean | body | _Available in Fleet Premium_. If enabled, software and script automations will run every time Fleet receives a failing response from a host. If not, all automations run on a host's first failure, and when a host's response changes from pass to fail. | | labels_include_any | array | form | Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. | | labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. | | labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **any of these** labels. | | labels_exclude_all | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will **not** run on hosts that match **any of these** labels. | Either `query` or `query_id` must be provided. Only one set of label targets (`labels_include_any`/`labels_include_all`) and one set of label exclusions (`labels_exclude_any`/`labels_exclude_all`) can be specified. If none are set, all hosts on the specified `platform` are targeted. #### Example `PATCH /api/v1/fleet/fleets/2/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", "script_id": 1337 } ``` ##### 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", "resolution": "Resolution steps", "platform": "darwin", "team_id": 2, "created_at": "2021-12-16T14:37:37Z", "updated_at": "2021-12-16T16:39:00Z", "passing_host_count": 0, "failing_host_count": 0, "host_count_updated_at": null, "calendar_events_enabled": true, "conditional_access_enabled": false, "fleet_maintained": false, "install_software": { "name": "Adobe Acrobat.app", "software_title_id": 1234 }, "run_script": { "name": "Enable gatekeeper", "id": 1337 } } } ``` ### Reset policy automations Resets [webhook and ticket policy automations](https://fleetdm.com/docs/using-fleet/automations#webhooks-and-tickets) 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. | | fleet_ids | array | body | _Available in Fleet Premium_. Filters to only run policy automations for hosts in the specified fleets. | #### Example `POST /api/v1/fleet/automations/reset` ##### Request body ```json { "team_ids": [1], "fleet_ids": [1], "policy_ids": [1, 2, 3] } ``` ##### Default response `Status: 200` ```json {} ``` --- ## Reports - [List reports](#list-reports) - [List host's reports](#list-hosts-reports) - [Get report](#get-report) - [Get report data](#get-report-data) - [Get host's report data](#get-hosts-report-data) - [Create report](#create-report) - [Update report](#update-report) - [Delete report by name](#delete-report-by-name) - [Delete report by ID](#delete-report-by-id) - [Delete reports](#delete-reports) - [Run live report](#run-live-report) ### List reports Returns a list of reports. To see each report's data, use the [get report data](#get-report-data) endpoint. `GET /api/v1/fleet/reports` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | order_key | string | query | What to order results by. Can be any column in the reports table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | fleet_id | integer | query | _Available in Fleet Premium_. The ID of the fleet for the reports to be listed. When omitted, returns global reports. | | query | string | query | Search query keywords. Searchable fields include `name`. | | merge_inherited | boolean | query | _Available in Fleet Premium_. If `true`, will include global reports in addition to fleet-level reports when filtering by `fleet_id`. (If no `fleet_id` is provided, this parameter is ignored.) | | platform | string | query | Return reports that are scheduled to run on this platform. One of: `"macos"`, `"windows"`, `"linux"` (case-insensitive). (Since reports cannot be scheduled to run on `"chrome"` hosts, it's not a valid value here) | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/reports` ##### Default response `Status: 200` ```json { "queries": [ { "created_at": "2021-01-04T21:19:57Z", "updated_at": "2021-01-04T21:19:57Z", "id": 1, "name": "report1", "description": "report", "query": "SELECT * FROM osquery_info", "team_id": null, "interval": 3600, "platform": "darwin,windows,linux", "min_osquery_version": "", "automations_enabled": true, "logging": "snapshot", "saved": true, "observer_can_run": true, "discard_data": false, "author_id": 1, "author_name": "noah", "author_email": "noah@example.com", "labels_include_any": [], "packs": [ { "created_at": "2021-01-05T21:13:04Z", "updated_at": "2021-01-07T19:12:54Z", "id": 1, "name": "Pack", "description": "Pack", "platform": "", "disabled": true } ], "stats": { "system_time_p50": 1.32, "system_time_p95": 4.02, "user_time_p50": 3.55, "user_time_p95": 3.00, "total_executions": 3920 } } ], "reports": [ { "created_at": "2021-01-04T21:19:57Z", "updated_at": "2021-01-04T21:19:57Z", "id": 1, "name": "report1", "description": "report", "query": "SELECT * FROM osquery_info", "team_id": null, "interval": 3600, "platform": "darwin,windows,linux", "min_osquery_version": "", "automations_enabled": true, "logging": "snapshot", "saved": true, "observer_can_run": true, "discard_data": false, "author_id": 1, "author_name": "noah", "author_email": "noah@example.com", "labels_include_any": [], "packs": [ { "created_at": "2021-01-05T21:13:04Z", "updated_at": "2021-01-07T19:12:54Z", "id": 1, "name": "Pack", "description": "Pack", "platform": "", "disabled": true } ], "stats": { "system_time_p50": 1.32, "system_time_p95": 4.02, "user_time_p50": 3.55, "user_time_p95": 3.00, "total_executions": 3920 } }, { "created_at": "2021-01-19T17:08:24Z", "updated_at": "2021-01-19T17:08:24Z", "id": 3, "name": "osquery_schedule", "description": "Report performance stats for each file in the query schedule.", "query": "select name, interval, executions, output_size, wall_time, (user_time/executions) as avg_user_time, (system_time/executions) as avg_system_time, average_memory, last_executed from osquery_schedule;", "team_id": null, "interval": 3600, "platform": "", "version": "", "automations_enabled": true, "logging": "differential", "saved": true, "observer_can_run": true, "discard_data": true, "author_id": 1, "author_name": "noah", "author_email": "noah@example.com", "labels_include_any": ["macOS 13+"], "packs": [ { "created_at": "2021-01-19T17:08:31Z", "updated_at": "2021-01-19T17:08:31Z", "id": 14, "name": "test_pack", "description": "", "platform": "", "disabled": false } ], "stats": { "system_time_p50": null, "system_time_p95": null, "user_time_p50": null, "user_time_p95": null, "total_executions": null } } ], "meta": { "has_next_results": true, "has_previous_results": false }, "count": 200 } ``` ### List host's reports Lists the saved reports that run on a host, along with the first result for each report that saves results. `GET /api/v1/fleet/hosts/:id/reports` #### Parameters | Name | Type | In | Description | | ------------------ | ------- | ----- | ------------------------------------------------------------------------------------------------------------- | | id | integer | path | **Required**. The host's ID. | | query | string | query | Search query keywords. Searchable fields include `name`. | | exclude_no_results | boolean | query | If `true`, exclude reports that don't save results. Default is `false`. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Valid options are `"name"` and `"last_fetched"`. Default is `"name"`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | #### Example `GET /api/v1/fleet/hosts/123/reports` ##### Default response `Status: 200` ```json { "reports": [ { "id": 31, "name": "List USB devices", "description": "Retrieves USB devices and their details.", "query": "SELECT model, vendor FROM usb_devices;", "logging": "snapshot", "discard_data": false, "total_results_count": 4, "last_fetched": "2021-01-19T17:08:31Z", "first_result_columns": { "model": "USB 2.0 Hub", "vendor": "VIA Labs, Inc." } }, { "id": 44, "name": "Get operating system version", "description": "Retrieves the host's operating system version.", "query": "SELECT name, version, major, minor, patch FROM os_version;", "logging": "differential", "discard_data": false, "total_results_count": 1, "last_fetched": "2021-01-20T14:52:09Z", "first_result_columns": { "name": "macOS", "version": "14.2.1", "major": "14", "minor": "2", "patch": "1" } }, { "id": 52, "name": "Check disk encryption status", "description": "Checks disk encryption status.", "query": "SELECT 1 FROM disk_encryption WHERE encrypted = 1;", "logging": "snapshot", "discard_data": true, "total_results_count": 0, "last_fetched": "2021-01-21T09:30:00Z", "first_result_columns": null } ], "meta": { "has_next_results": false, "has_previous_results": false }, "count": 3 } ``` > The report's first row reflects the order returned by the underlying [table](https://fleetdm.com/tables) implementation. Without an `ORDER BY` clause in the query, this order is not guaranteed to be consistent across runs — particularly for tables backed by live OS state (e.g. processes, network connections). To ensure a predictable first result, add `ORDER BY ` to your query. ### Get report Returns the report specified by ID. `GET /api/v1/fleet/reports/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ------------------------------------------ | | id | integer | path | **Required**. The id of the desired report. | #### Example `GET /api/v1/fleet/reports/31` ##### Default response `Status: 200` ```json { "query": { "created_at": "2021-01-19T17:08:24Z", "updated_at": "2021-01-19T17:08:24Z", "id": 31, "name": "centos_hosts", "description": "", "query": "select 1 from os_version where platform = \"centos\";", "team_id": null, "interval": 3600, "platform": "", "min_osquery_version": "", "automations_enabled": true, "logging": "snapshot", "saved": true, "observer_can_run": true, "discard_data": false, "author_id": 1, "author_name": "John", "author_email": "john@example.com", "labels_include_any": [], "packs": [ { "created_at": "2021-01-19T17:08:31Z", "updated_at": "2021-01-19T17:08:31Z", "id": 14, "name": "test_pack", "description": "", "platform": "", "disabled": false } ], "stats": { "system_time_p50": 1.32, "system_time_p95": 4.02, "user_time_p50": 3.55, "user_time_p95": 3.00, "total_executions": 3920 } } } ``` ### Get report data Returns a specific report's data. `GET /api/v1/fleet/reports/:id/report` #### Parameters | Name | Type | In | Description | | --------- | ------- | ----- | ----------------------------------------------------------------------------------------- | | id | integer | path | **Required**. The ID of the desired query. | | fleet_id | integer | query | Filter the query report to only include hosts that are associated with the fleet specified | #### Example `GET /api/v1/fleet/reports/31/report` ##### Default response `Status: 200` ```json { "query_id": 31, "report_id": 31, "report_clipped": false, "results": [ { "host_id": 1, "host_name": "foo", "last_fetched": "2021-01-19T17:08:31Z", "columns": { "model": "USB 2.0 Hub", "vendor": "VIA Labs, Inc." } }, { "host_id": 1, "host_name": "foo", "last_fetched": "2021-01-19T17:08:31Z", "columns": { "model": "USB Keyboard", "vendor": "VIA Labs, Inc." } }, { "host_id": 2, "host_name": "bar", "last_fetched": "2021-01-19T17:20:00Z", "columns": { "model": "USB Receiver", "vendor": "Logitech" } }, { "host_id": 2, "host_name": "bar", "last_fetched": "2021-01-19T17:20:00Z", "columns": { "model": "USB Receiver", "vendor": "Logitech" } }, { "host_id": 2, "host_name": "bar", "last_fetched": "2021-01-19T17:20:00Z", "columns": { "model": "Display Audio", "vendor": "Apple Inc." } } ] } ``` If a query has no results stored, then `results` will be an empty array: ```json { "query_id": 32, "results": [] } ``` > Scheduled reports do not return errors, so only non-error results are included. If you suspect a report may be running into errors, you can use the [live report](#run-live-report) endpoint to get diagnostics. ### Get host's report data Returns a specific report's data for a single host. `GET /api/v1/fleet/hosts/:id/reports/:report_id` #### Parameters | Name | Type | In | Description | | --------- | ------- | ----- | ------------------------------------------ | | id | integer | path | **Required**. The ID of the desired host. | | report_id | integer | path | **Required**. The ID of the desired report. | #### Example `GET /api/v1/fleet/hosts/123/reports/31` ##### Default response `Status: 200` ```json { "query_id": 31, "report_id": 31, "host_id": 1, "host_name": "foo", "last_fetched": "2021-01-19T17:08:31Z", "report_clipped": false, "results": [ { "columns": { "model": "USB 2.0 Hub", "vendor": "VIA Labs, Inc." } }, { "columns": { "model": "USB Keyboard", "vendor": "VIA Labs, Inc." } }, { "columns": { "model": "USB Receiver", "vendor": "Logitech" } } ] } ``` If a report has no results stored for the specified host, then `results` will be an empty array: ```json { "query_id": 31, "report_id": 31, "host_id": 1, "host_name": "foo", "last_fetched": "2021-01-19T17:08:31Z", "report_clipped": false, "results": [] } ``` > Scheduled reports do not return errors, so only non-error results are included in the report. If you suspect a report may be running into errors, you can use the [live report](#run-live-report) endpoint to get diagnostics. ### Create report Creates a global report or fleet report. `POST /api/v1/fleet/reports` #### Parameters | Name | Type | In | Description | | ------------------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | body | **Required**. The name of the report. | | query | string | body | **Required**. The SQL query for collecting report data. | | description | string | body | The query's description. | | observer_can_run | boolean | body | Whether or not users with the `observer` role can run the report as a live report. This field is only relevant for the `observer` role. The `observer_plus` role can run any report and is not limited by this flag. | | fleet_id | integer | body | _Available in Fleet Premium_. The fleet to which the new report should be added. If omitted, the report will be global. | | interval | integer | body | The amount of time, in seconds, the report waits before running. Can be set to `0` to never run. Default: 0. | | platform | string | body | The OS platforms where this report will run (other platforms ignored). Comma-separated string. If omitted, runs on all compatible platforms. | | labels_include_any | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **any of these** labels. | | labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **all of these** labels. | | min_osquery_version | string | body | The minimum required osqueryd version installed on a host. If omitted, all osqueryd versions are acceptable. | | automations_enabled | boolean | body | Whether to send data to the configured log destination according to the report's `interval`. | | logging | string | body | The type of log output for this report. Valid values: `"snapshot"`(default), `"differential"`, or `"differential_ignore_removals"`. | | discard_data | boolean | body | Whether to skip saving the latest results for each host. If set to `true`, data is still sent to the configured log destination if `automations_enabled`. Default: `false`. | Only one of `labels_include_any` or `labels_include_all` can be specified. If none are specified, all hosts are targeted. #### Example `POST /api/v1/fleet/reports` ##### Request body ```json { "name": "new_report", "description": "This is a new report.", "query": "SELECT * FROM osquery_info", "interval": 3600, // Once per hour "platform": "darwin,windows,linux", "min_osquery_version": "", "automations_enabled": true, "logging": "snapshot", "discard_data": false, "labels_include_any": [ "Hosts with Docker installed" ] } ``` ##### Default response `Status: 200` ```json { "query": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 288, "name": "new_query", "query": "SELECT * FROM osquery_info", "description": "This is a new query.", "team_id": null, "interval": 3600, "platform": "darwin,windows,linux", "min_osquery_version": "", "automations_enabled": true, "logging": "snapshot", "saved": true, "author_id": 1, "author_name": "", "author_email": "", "observer_can_run": true, "discard_data": false, "packs": [], "labels_include_any": [ "Hosts with Docker installed" ] }, "report": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 288, "name": "new_query", "query": "SELECT * FROM osquery_info", "description": "This is a new query.", "team_id": null, "interval": 3600, "platform": "darwin,windows,linux", "min_osquery_version": "", "automations_enabled": true, "logging": "snapshot", "saved": true, "author_id": 1, "author_name": "", "author_email": "", "observer_can_run": true, "discard_data": false, "packs": [], "labels_include_any": [ "Hosts with Docker installed" ] } } ``` ### Update report Modifies the report specified by ID. `PATCH /api/v1/fleet/reports/:id` #### Parameters | Name | Type | In | Description | | --------------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | integer | path | **Required.** The ID of the report. | | name | string | body | The name of the report. | | query | string | body | The report's SQL query. | | description | string | body | The report's description. | | observer_can_run | boolean | body | Whether or not users with the `observer` role can run the report as a live report. This field is only relevant for the `observer` role. The `observer_plus` role can run any query and is not limited by this flag. | | interval | integer | body | The amount of time, in seconds, the report waits before running. Can be set to `0` to never run. Default: 0. | | platform | string | body | The OS platforms where this report will run (other platforms ignored). Comma-separated string. If set to "", runs on all compatible platforms. | | labels_include_any | list | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **any of these** labels. | | labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **all of these** labels. | | min_osquery_version | string | body | The minimum required osqueryd version installed on a host. If omitted, all osqueryd versions are acceptable. | | automations_enabled | boolean | body | Whether to send data to the configured log destination according to the report's `interval`. | | logging | string | body | The type of log output for this query. Valid values: `"snapshot"`(default), `"differential"`, or `"differential_ignore_removals"`. | | discard_data | boolean | body | Whether to skip saving the latest results for each host. If set to `true`, data is still sent to the configured log destination if `automations_enabled`. | Only one of `labels_include_any` or `labels_include_all` can be specified. If none are specified, all hosts are targeted. > Note that any of the following conditions will cause the existing report's data to be discarded: > - Updating the `query` (SQL) field > - Updating the filters for targeted hosts (`platform`, `min_osquery_version`, `labels_include_any`) > - Changing `discard_data` from `false` to `true` > - Changing `logging` from `"snapshot"` to `"differential"` or `"differential_ignore_removals"` #### Example `PATCH /api/v1/fleet/reports/2` ##### Request body ```json { "name": "new_title_for_my_report", "interval": 3600, // Once per hour, "platform": "", "min_osquery_version": "", "automations_enabled": false, "discard_data": true, "labels_include_any": [ "Hosts with Docker installed", "macOS 13+" ] } ``` ##### Default response `Status: 200` ```json { "query": { "created_at": "2021-01-22T17:23:27Z", "updated_at": "2021-01-22T17:23:27Z", "id": 288, "name": "new_title_for_my_query", "description": "This is a new query.", "query": "SELECT * FROM osquery_info", "team_id": null, "interval": 3600, "platform": "", "min_osquery_version": "", "automations_enabled": false, "logging": "snapshot", "saved": true, "author_id": 1, "author_name": "noah", "observer_can_run": true, "discard_data": true, "packs": [], "labels_include_any": [ "Hosts with Docker installed", "macOS 13+" ] }, "report": { "created_at": "2021-01-22T17:23:27Z", "updated_at": "2021-01-22T17:23:27Z", "id": 288, "name": "new_title_for_my_query", "description": "This is a new query.", "query": "SELECT * FROM osquery_info", "team_id": null, "interval": 3600, "platform": "", "min_osquery_version": "", "automations_enabled": false, "logging": "snapshot", "saved": true, "author_id": 1, "author_name": "noah", "observer_can_run": true, "discard_data": true, "packs": [], "labels_include_any": [ "Hosts with Docker installed", "macOS 13+" ] } } ``` ### Delete report by name Deletes the report specified by name. `DELETE /api/v1/fleet/reports/:name` #### Parameters | Name | Type | In | Description | | ---- | ---------- | ---- | ------------------------------------ | | name | string | path | **Required.** The name of the report. | | fleet_id | integer | body | _Available in Fleet Premium_. The ID of the report's fleet. If omitted, Fleet will search among only global reports. | #### Example `DELETE /api/v1/fleet/reports/foo` ##### Default response `Status: 200` ### Delete report by ID Deletes the report specified by ID. `DELETE /api/v1/fleet/reports/id/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------------- | | id | integer | path | **Required.** The ID of the report. | #### Example `DELETE /api/v1/fleet/reports/id/28` ##### Default response `Status: 200` ### Delete reports Deletes the reports specified by ID. Returns the count of reports successfully deleted. `POST /api/v1/fleet/reports/delete` #### Parameters | Name | Type | In | Description | | ---- | ----- | ---- | ------------------------------------- | | ids | array | body | **Required.** The IDs of the reports. | #### Example `POST /api/v1/fleet/reports/delete` ##### Request body ```json { "ids": [ 2, 24, 25 ] } ``` ##### Default response `Status: 200` ```json { "deleted": 3 } ``` ### Run live report > This updated API endpoint replaced `GET /api/v1/fleet/queries/run` in Fleet 4.43.0, for improved compatibility with many HTTP clients. The [deprecated endpoint](https://github.com/fleetdm/fleet/blob/fleet-v4.42.0/docs/REST%20API/rest-api.md#run-live-query) is maintained for backwards compatibility. Runs a live report against the specified hosts and responds with the results. The live report will stop if the request times out. Timeouts happen if targeted hosts haven't responded after the configured `FLEET_LIVE_QUERY_REST_PERIOD` (default 25 seconds) or if the `distributed_interval` agent option (default 10 seconds) is higher than the `FLEET_LIVE_QUERY_REST_PERIOD`. `POST /api/v1/fleet/reports/:id/run` #### Parameters | Name | Type | In | Description | |-----------|-------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | report_id | integer | path | **Required**. The ID of the saved report to run. | | host_ids | array | body | **Required**. The IDs of the hosts to target. User must be authorized to target all of these hosts. | #### Example `POST /api/v1/fleet/reports/123/run` ##### Request body ```json { "host_ids": [ 1, 4, 34, 27 ] } ``` ##### Default response ```json { "query_id": 123, "report_id": 123, "targeted_host_count": 4, "responded_host_count": 2, "results": [ { "host_id": 1, "rows": [ { "build_distro": "10.12", "build_platform": "darwin", "config_hash": "7bb99fa2c8a998c9459ec71da3a84d66c592d6d3", "config_valid": "1", "extensions": "active", "instance_id": "9a2ec7bf-4946-46ea-93bf-455e0bcbd068", "pid": "23413", "platform_mask": "21", "start_time": "1635194306", "uuid": "4C182AC7-75F7-5AF4-A74B-1E165ED35742", "version": "4.9.0", "watcher": "23412" } ], "error": null }, { "host_id": 2, "rows": [], "error": "no such table: os_version" } ] } ``` --- ## Schedule The [schedule API endpoints](https://github.com/fleetdm/fleet/blob/f6631e27f56b6704c555adfb7a3bb8c6d1a74d98/docs/REST%20API/rest-api.md#schedule) are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the [reports](#reports) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling. --- ## Scripts - [Run script](#run-script) - [Get script result](#get-script-result) - [Batch-run script](#batch-run-script) - [List batch scripts](#list-batch-scripts) - [Get batch script](#get-batch-script) - [List hosts targeted in batch script](#list-hosts-targeted-in-batch-script) - [Cancel batch script](#cancel-batch-script) - [Create script](#create-script) - [Update script](#update-script) - [Delete script](#delete-script) - [List scripts](#list-scripts) - [List host's scripts](#list-hosts-scripts) - [Get or download script](#get-or-download-script) ### Run script Run a script on a host. The script will be added to the host's list of upcoming activities. The new script will run after other activities finish. Failure of one activity won't cancel other activities. By default, script runs time out after 5 minutes. You can modify this default in your [agent configuration](https://fleetdm.com/docs/configuration/agent-configuration#script-execution-timeout). `POST /api/v1/fleet/scripts/run` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | host_id | integer | body | **Required**. The ID of the host to run the script on. | | script_id | integer | body | The ID of the existing saved script to run. Only one of either `script_id`, `script_contents`, or `script_name` can be included. | | script_contents | string | body | The contents of the script to run. Only one of either `script_id`, `script_contents`, or `script_name` can be included. Scripts must be less than 10,000 characters. To run scripts with more than 10k characters, save the script and use `script_id` or `script_name` and `fleet_id` instead. | | script_name | integer | body | The name of the existing saved script to run. If specified, requires `fleet_id`. Only one of either `script_id`, `script_contents`, or `script_name` can be included in the request. | | fleet_id | integer | body | The ID of the fleet the existing saved script belongs to. If specified, requires `script_name`. Only one of either `script_id`, `script_contents`, or `script_name` can be included in the request. | > Note that if any combination of `script_id`, `script_contents`, and `script_name` are included in the request, this endpoint will respond with an error. #### Example `POST /api/v1/fleet/scripts/run` ##### Default response `Status: 202` ```json { "host_id": 1227, "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002" } ``` ### Get script result Gets the result of a script that was executed. `GET /api/v1/fleet/scripts/results/:execution_id` #### Parameters | Name | Type | In | Description | | ---- | ------ | ---- | -------------------------------------------- | | execution_id | string | path | **Required**. The execution id of the script. | #### Example `GET /api/v1/fleet/scripts/results/:execution_id` ##### Default response `Status: 200` ```json { "script_contents": "echo 'hello'", "exit_code": 0, "output": "hello", "message": "", "hostname": "Test Host", "host_timeout": false, "host_id": 1, "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002", "runtime": 20, "created_at": "2024-09-11T20:30:24Z" } ``` > Note: `exit_code` can be `null` if Fleet hasn't heard back from the host yet. > Note: `created_at` is the creation timestamp of the script execution request. ### Batch-run script Run a script on multiple hosts. The script will be added to each host's list of upcoming activities. `POST /api/v1/fleet/scripts/run/batch` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | script_id | integer | body | **Required**. The ID of the existing saved script to run. | | host_ids | array | body | List of host IDs. Required if `filters` not specified. Only one of `host_ids` or `filters` may be included in the request. | | filters | object | body | See [filters](#filters4). Required if `host_ids` not specified. Only one of `host_ids` or `filters` may be included in the request. | | not_before | string | body | UTC time when the script run is scheduled to begin. If omitted, the batch script will begin right away. | ##### Filters | Name | Type | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------- | | query | string | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, and `ipv4`. | | status | string | Host status. Can either be `new`, `online`, `offline`, `mia` or `missing`. | | label_id | number | ID of a label to filter by. | | fleet_id | number | ID of the fleet to filter by. | > Note that if a batch script is scheduled for the future using `not_before`, and hosts are targeted using `filters`, the script will run on any hosts matching the filters _at the time the batch script was added_. To see all targeted hosts, use the [List hosts targeted in batch script](#list-hosts-targeted-in-batch-script) endpoint. #### Example `POST /api/v1/fleet/scripts/run/batch` ##### Request body Request (using `host_ids`): ```json { "script_id": 123, "host_ids": [1, 2, 3], "not_before": "2025-07-01T15:00:00Z" } ``` Request (using `filters`): ```json { "script_id": 123, "filters": { "status": "online", "query": "abc" } } ``` ##### Default response `Status: 202` ```json { "batch_execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002" } ``` ### List batch scripts Returns a list of batch script executions. `GET /api/v1/fleet/scripts/batch` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. Filters to batch script runs for the specified fleet. | | status | string | query | Filters to batch script runs with this status. Either `"started"`, `"scheduled"`, or `"finished"`. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | #### Example `GET /api/v1/fleet/scripts/batch` ##### Request body ```json { "team_id": 123, "fleet_id": 123, "status": "completed" } ``` ##### Default response `Status: 200` ```json { "batch_executions": [ { "script_id": 555, "script_name": "my-script.sh", "batch_execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002", "team_id": 123, "fleet_id": 123, "not_before": "2025-07-01T15:00:00Z", "finished_at": "2025-07-06T15:00:00Z", "started_at": "2025-07-06T14:00:00Z", "status": "finished", "canceled": false, "targeted_host_count": 12599, "ran_host_count": 12345, "pending_host_count": 234, "errored_host_count": 18, "incompatible_host_count": 3, "canceled_host_count": 2, "created_at": "2025-07-01T10:00:00Z" } ], "meta": { "has_next_results": false, "has_previous_results": false }, "count": 1 } ``` ### Get batch script Returns a summary of a batch-run script, including host counts and current status. > The [Get batch script summary](https://github.com/fleetdm/fleet/blob/fleet-v4.71.1/docs/REST%20API/rest-api.md#get-batch-script-summary) endpoint is deprecated as of Fleet 4.73. It is maintained for backwards compatibility. Please use this endpoint instead. `GET /api/v1/fleet/scripts/batch/:batch_execution_id` #### Parameters | Name | Type | In | Description | | ------------------ | ------- | ---- | --------------------------------------------| | batch_execution_id | string | path | **Required**. The ID returned from a batch script run. | #### Example `GET /api/v1/fleet/scripts/batch/abc-def` ##### Default response `Status: 200` ```json { "script_id": 555, "script_name": "my-script.sh", "team_id": 123, "fleet_id": 123, "not_before": "2025-07-01T15:00:00Z", "finished_at": "2025-07-06T15:00:00Z", "started_at": "2025-07-06T14:00:00Z", "status": "finished", "canceled": false, "targeted_host_count": 12599, "ran_host_count": 12345, "pending_host_count": 234, "errored_host_count": 18, "incompatible_host_count": 3, "canceled_host_count": 2, "created_at": "2025-07-01T10:00:00Z" } ``` ### List hosts targeted in batch script Returns a list hosts targeted in a batch script run, along with their script execution status. `GET /api/v1/fleet/scripts/batch/:batch_execution_id/host_results` #### Parameters | Name | Type | In | Description | | --------------------| ------- | ----- | -------------------------------------------- | | batch_execution_id | string | path | **Required**. The ID returned from a batch script run. | | status | string | query | **Required** Filters to hosts with this script status. Either `"ran"`, `"pending"`, `"errored"`, `"incompatible"`, or "`canceled`". | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `display_name`, `hostname`, and `updated_at`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/scripts/batch/abc-def/host-results?status=ran` ##### Default response `Status: 200` ```json { "hosts": [ { "id": 123, "display_name": "Anna's MacBook Pro", "script_status": "ran", "script_execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002", "script_executed_at": "2024-09-11T20:30:24Z", "script_output_preview": "hello world" } ], "meta": { "has_next_results": false, "has_previous_results": false }, "count": 1 } ``` ### Cancel batch script `POST /api/v1/fleet/scripts/batch/:batch_execution_id/cancel` #### Example `POST /api/v1/fleet/scripts/batch/abc-def/cancel` ##### Default response `Status: 200` ### Create script Uploads a script, making it available to run on hosts assigned to the specified fleet (or "Unassigned"). > You need to send a request of type `multipart/form-data`. > This endpoint accepts a maximum request body size of 1.5MiB. `POST /api/v1/fleet/scripts` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | script | file | body | **Required**. The file containing the script. | | fleet_id | integer | body | _Available in Fleet Premium_. The fleet ID. If specified, the script will only be available to hosts assigned to this fleet. If not specified, the script will only be available for "Unassigned" hosts. | Script line endings are automatically converted from [CRLF to LF](https://en.wikipedia.org/wiki/Newline) for compatibility with both non-Windows shells and PowerShell. #### Example `POST /api/v1/fleet/scripts` ##### Request body ```http fleet_id="1" script="myscript.sh" ``` ##### Default response `Status: 200` ```json { "script_id": 1227 } ``` ### Update script Modifies an existing script. > You need to send a request of type `multipart/form-data`. `PATCH /api/v1/fleet/scripts/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The ID of the script to modify. | | script | file | body | **Required**. The file containing the script. Filename will be ignored. | #### Example `PATCH /api/v1/fleet/scripts/1` ##### Request body ```http script="myscript.sh" ``` ##### Default response `Status: 200` ```json { "id": 1, "team_id": null, "name": "script_1.sh", "created_at": "2023-07-30T13:41:07Z", "updated_at": "2023-07-30T13:41:07Z" } ``` ### Delete script Deletes an existing script. `DELETE /api/v1/fleet/scripts/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The ID of the script to delete. | #### Example `DELETE /api/v1/fleet/scripts/1` ##### Default response `Status: 204` ### List scripts `GET /api/v1/fleet/scripts` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | fleet_id | integer | query | _Available in Fleet Premium_. The ID of the fleet to filter scripts by. If not specified, it will filter only scripts that are available for "Unassigned" hosts. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be ordered by `id`, `name`, `created_at`, or `updated_at`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/scripts` ##### Default response `Status: 200` ```json { "scripts": [ { "id": 1, "team_id": null, "name": "script_1.sh", "created_at": "2023-07-30T13:41:07Z", "updated_at": "2023-07-30T13:41:07Z" }, { "id": 2, "team_id": null, "name": "script_2.sh", "created_at": "2023-08-30T13:41:07Z", "updated_at": "2023-08-30T13:41:07Z" } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### List host's scripts `GET /api/v1/fleet/hosts/:id/scripts` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The host's id. | | page | integer | query | Page number of the results to fetch.| | per_page | integer | query | Results per page.| | order_key | string | query | What to order results by. Can be ordered by `name` or `executed_at`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/hosts/123/scripts` ##### Default response `Status: 200` ```json { "scripts": [ { "script_id": 3, "name": "remove-zoom-artifacts.sh", "last_execution": { "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002", "executed_at": "2021-12-15T15:23:57Z", "status": "error" } }, { "script_id": 5, "name": "set-timezone.sh", "last_execution": { "id": "e797d6c6-3aae-11ee-be56-0242ac120002", "executed_at": "2021-12-15T15:23:57Z", "status": "pending" } }, { "script_id": 8, "name": "uninstall-zoom.sh", "last_execution": { "id": "e797d6c6-3aae-11ee-be56-0242ac120002", "executed_at": "2021-12-15T15:23:57Z", "status": "ran" } } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Get or download script `GET /api/v1/fleet/scripts/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ------------------------------------- | | id | integer | path | **Required.** The desired script's ID. | | alt | string | query | If specified and set to "media", downloads the script's contents. | #### Example (get script) `GET /api/v1/fleet/scripts/123` ##### Default response `Status: 200` ```json { "id": 123, "team_id": null, "name": "script_1.sh", "created_at": "2023-07-30T13:41:07Z", "updated_at": "2023-07-30T13:41:07Z" } ``` #### Example (download script) `GET /api/v1/fleet/scripts/123?alt=media` ##### Example response headers ```http Content-Length: 13 Content-Type: application/octet-stream Content-Disposition: attachment;filename="2023-09-27 script_1.sh" ``` ###### Example response body `Status: 200` ``` echo "hello" ``` ## Sessions - [Get session](#get-session) - [Delete session](#delete-session) ### Get session Returns the session information for the session specified by ID. `GET /api/v1/fleet/sessions/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The ID of the desired session. | #### Example `GET /api/v1/fleet/sessions/1` ##### Default response `Status: 200` ```json { "session_id": 1, "user_id": 1, "created_at": "2021-03-02T18:41:34Z" } ``` ### Delete session Deletes the session specified by ID. When the user associated with the session next attempts to access Fleet, they will be asked to log in. `DELETE /api/v1/fleet/sessions/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The id of the desired session. | #### Example `DELETE /api/v1/fleet/sessions/1` ##### Default response `Status: 200` --- ## Software - [List software](#list-software) - [List software versions](#list-software-versions) - [List operating systems](#list-operating-systems) - [Get software](#get-software) - [Get software version](#get-software-version) - [Get operating system version](#get-operating-system-version) - [Add package](#add-package) - [Update package](#update-package) - [Update software icon](#update-software-icon) - [Download software icon](#download-software-icon) - [Delete software icon](#delete-software-icon) - [List Apple App Store apps](#list-apple-app-store-apps) - [Add app store app](#add-app-store-app) - [Update app store app](#update-app-store-app) - [List Fleet-maintained apps](#list-fleet-maintained-apps) - [Get Fleet-maintained app](#get-fleet-maintained-app) - [Create Fleet-maintained app](#create-fleet-maintained-app) - [Install software](#install-software) - [Uninstall software](#uninstall-software) - [Install self-service software by Fleet Desktop token](#install-self-service-software-by-fleet-desktop-token) - [Get software install result](#get-software-install-result) - [Download software](#download-package) - [Delete software](#delete-software) ### List software Get a list of all software. `GET /api/v1/fleet/software/titles` #### Parameters | Name | Type | In | Description | | ----------------------- | ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `name` and `hosts_count`. Default is `hosts_count` (descending). | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | query | string | query | Search query keywords. Searchable fields include `title` and `cve`. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters the software to only include the software installed on the hosts that are assigned to the specified fleet. Use `0` to filter by "Unassigned" hosts. | | vulnerable | boolean | query | If true or 1, only list software that has detected vulnerabilities. Default is `false`. | | available_for_install | boolean | query | If `true` or `1`, only list software that is available for install (added by the user). Default is `false`. | | self_service | boolean | query | If `true` or `1`, only lists self-service software. Default is `false`. | | packages_only | boolean | query | _Available in Fleet Premium_. If `true` or `1`, only lists packages available for install (without app store apps). | | min_cvss_score | integer | query | _Available in Fleet Premium_. Filters to include only software with vulnerabilities that have a CVSS version 3.x base score higher than the specified value. | | max_cvss_score | integer | query | _Available in Fleet Premium_. Filters to only include software with vulnerabilities that have a CVSS version 3.x base score lower than what's specified. | | exploit | boolean | query | _Available in Fleet Premium_. If `true`, filters to only include software with vulnerabilities that have been actively exploited in the wild (`cisa_known_exploit: true`). Default is `false`. | | platform | string | query | Filters software titles available for install by platforms. `fleet_id` must be specified to filter by platform. Options are: `"macos"` (alias of `"darwin"`), `"darwin"` `"windows"`, `"linux"`, `"chrome"`, `"ios"`, `"ipados"`. To show titles from multiple platforms, separate the platforms with commas (e.g. `?platform=darwin,windows`). | | hash_sha256 | string | query | Filters to only include custom software packages (uploaded installers) with the specified SHA-256 hash. `fleet_id` must be specified to filter by hash. This allows checking if a specific package already exists before uploading. | | package_name | string | query | Filters to only include custom software packages (uploaded installers) with the specified package filename. `fleet_id` must be specified to filter by package name. This allows checking if a specific package already exists before uploading. | | exclude_fleet_maintained_apps | boolean | query | If `true` or `1`, Fleet maintained apps will not be included in the list of `software_titles`. Default is `false` | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/software/titles?fleet_id=3&platform=darwin,windows` ##### Default response `Status: 200` ```json { "counts_updated_at": "2026-06-04T12:34:56Z", "count": 2, "software_titles": [ { "id": 2792, "name": "Slack", "icon_url": null, "source": "apps", "extension_for": "", "browser": "", "hosts_count": 5, "versions_count": 4, "versions": [ { "id": 515953, "version": "4.39.88", "vulnerabilities": null }, { "id": 610801, "version": "4.47.72", "vulnerabilities": null } ], "packages": [ { "name": "Slack-4.50.128-macOS.pkg", "automatic_install_policies": null, "version": "4.50.128", "platform": "darwin", "self_service": false, "package_url": "" }, { "name": "Slack-4.51.133-macOS.pkg", "automatic_install_policies": null, "version": "4.51.133", "platform": "darwin", "self_service": true, "package_url": "" } ], "software_package": { "name": "Slack-4.50.128-macOS.pkg", "automatic_install_policies": null, "version": "4.50.128", "platform": "darwin", "self_service": false, "last_install": null, "last_uninstall": null, "package_url": "" }, "app_store_app": null, "bundle_identifier": "com.tinyspeck.slackmacgap", "hash_sha256": "f7e4cba7676dacb03ac4cdbe5a99cc1d80ef751c484a13c6a7cf6a93de4a494e", "display_name": "" }, { "id": 2618, "name": "Raycast", "icon_url": null, "source": "apps", "extension_for": "", "browser": "", "hosts_count": 1, "versions_count": 1, "versions": [ { "id": 651354, "version": "1.104.19", "vulnerabilities": null } ], "packages": null, "software_package": null, "app_store_app": null, "bundle_identifier": "com.raycast.macos", "display_name": "" } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` `browser` and `extension_for` fields are included when set and when empty. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. A software title can have more than one package. The `packages` array lists all packages added for the title. `software_package` is kept for backwards compatibility and contains the oldest (first added) package; it's `null` when no package is available. ### List software versions Get a list of all software versions. `GET /api/v1/fleet/software/versions` #### Parameters | Name | Type | In | Description | | ----------------------- | ------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `name`, `hosts_count`, `cve_published`, `cvss_score`, `epss_probability` and `cisa_known_exploit`. Default is `hosts_count` (descending). | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | query | string | query | Search query keywords. Searchable fields include `name`, `version`, and `cve`. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters the software to only include the software installed on the hosts that are assigned to the specified fleet. Use `0` to filter by "Unassigned" hosts. | | vulnerable | boolean | query | If true or 1, only list software that has detected vulnerabilities. Default is `false`. | | min_cvss_score | integer | query | _Available in Fleet Premium_. Filters to include only software with vulnerabilities that have a CVSS version 3.x base score higher than the specified value. | | max_cvss_score | integer | query | _Available in Fleet Premium_. Filters to only include software with vulnerabilities that have a CVSS version 3.x base score lower than what's specified. | | exploit | boolean | query | _Available in Fleet Premium_. If `true`, filters to only include software with vulnerabilities that have been actively exploited in the wild (`cisa_known_exploit: true`). Default is `false`. | | without_vulnerability_details | boolean | query | _Available in Fleet Premium_. If `true` only vulnerability name is included in response. If `false` (or omitted), adds vulnerability description, CVSS score, and other details available in Fleet Premium. See notes below on performance. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | > For optimal performance, we recommend Fleet Premium users set `without_vulnerability_details` to `true` whenever possible. If set to `false` a large amount of data will be included in the response. If you need vulnerability details, consider using the [Get vulnerability](#get-vulnerability) endpoint. #### Example `GET /api/v1/fleet/software/versions` ##### Default response `Status: 200` ```json { "counts_updated_at": "2022-01-01T12:32:00Z", "count": 2, "software": [ { "id": 1, "name": "glibc", "display_name": "", "version": "2.12", "source": "rpm_packages", "release": "1.212.el6", "vendor": "CentOS", "arch": "x86_64", "generated_cpe": "cpe:2.3:a:gnu:glibc:2.12:*:*:*:*:*:*:*", "vulnerabilities": [ { "cve": "CVE-2009-5155", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2009-5155", "cvss_score": 7.5, "epss_probability": 0.01537, "cisa_known_exploit": false, "cve_published": "2022-01-01T12:32:00Z", "cve_description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.", "resolved_in_version": "2.28" } ], "hosts_count": 1 }, { "id": 2, "name": "1Password – Password Manager", "display_name": "", "version": "2.10.0", "source": "chrome_extensions", "browser": "chrome", "extension_for": "chrome", "extension_id": "aeblfdkhhhdcdjpifhhbdiojplfjncoa", "generated_cpe": "cpe:2.3:a:1password:1password:2.19.0:*:*:*:*:chrome:*:*", "hosts_count": 345, "vulnerabilities": null }, { "id": 3, "name": "Prettier", "version": "232.1.0", "source": "jetbrains_plugins", "extensions_for": "goland", "generated_cpe": "cpe:2.3:a:*:prettier:232.1.0:*:*:*:*:node.js:*:*", "hosts_count": 19, "vulnerabilities": null } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` `browser` and `extension_for` fields are included when set and when empty. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. ### List operating systems Returns a list of all operating systems. `GET /api/v1/fleet/os_versions` #### Parameters | Name | Type | In | Description | | --- | --- | --- | --- | | fleet_id | integer | query | _Available in Fleet Premium_. Filters response data to the specified fleet. Use `0` to filter by "Unassigned" hosts. | | platform | string | query | Filters the hosts to the specified platform. One of: `"darwin"` (macOS), `"windows"`, `"linux"`, `"chrome"`, `"ios"`, `"ipados"`,` or `"android"`. | | os_name | string | query | The name of the operating system to filter hosts by. `os_version` must also be specified with `os_name` | | os_version | string | query | The version of the operating system to filter hosts by. `os_name` must also be specified with `os_version` | | max_vulnerabilities | integer | query | Limits the number of `vulnerabilities` returned per OS version. (If omitted, returns all vulnerabilities.) | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. Default is `20`. | | order_key | string | query | What to order results by. Allowed fields are: `hosts_count`. Default is `hosts_count` (descending). | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | ##### Default response `Status: 200` ```json { "count": 1, "counts_updated_at": "2023-12-06T22:17:30Z", "os_versions": [ { "os_version_id": 123, "hosts_count": 21, "name": "Microsoft Windows 11 Pro 23H2 10.0.22621.1234", "name_only": "Microsoft Windows 11 Pro 23H2", "version": "10.0.22621.1234", "platform": "windows", "generated_cpes": [], "vulnerabilities_count": 1, "vulnerabilities": [ { "cve": "CVE-2022-30190", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190", "cvss_score": 7.8,// Available in Fleet Premium "epss_probability": 0.9729,// Available in Fleet Premium "cisa_known_exploit": false,// Available in Fleet Premium "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability.",// Available in Fleet Premium "resolved_in_version": ""// Available in Fleet Premium } ] } ], "meta": { "has_next_results": false, "has_previous_results": false } } ``` Windows and macOS listed vulnerabilities are based on OS version-specific data. Linux vulnerabilities are based on kernel vulnerabilities for hosts running the specified OS version. Both active and inactive kernels on a host are accounted for in kernel vulnerability reporting. Other operating systems do not report vulnerabilities. ### Get software Returns information about the specified software. By default, `versions` are sorted in descending order by the `hosts_count` field. `GET /api/v1/fleet/software/titles/:id` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | id | integer | path | **Required.** The software title's ID. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters response data to the specified fleet. Use `0` to filter by "Unassigned" hosts. | #### Example `GET /api/v1/fleet/software/titles/2792?fleet_id=3` ##### Default response `Status: 200` ```json { "software_title": { "id": 2792, "name": "Slack", "icon_url": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/90/f7/27/90f727be-835b-54ad-4d9d-8b597e63e321/electron.png/512x512bb.png", "source": "apps", "extension_for": "", "browser": "", "hosts_count": 5, "versions_count": 4, "versions": [ { "id": 515953, "version": "4.39.88", "vulnerabilities": null, "hosts_count": 1 }, { "id": 610801, "version": "4.47.72", "vulnerabilities": null, "hosts_count": 2 } ], "counts_updated_at": "2026-06-04T17:23:45Z", "packages": [ { "team_id": 310, "title_id": 2792, "name": "Slack-4.50.128-macOS.pkg", "icon_url": null, "version": "4.50.128", "platform": "darwin", "uploaded_at": "2026-06-04T17:29:09.155424Z", "installer_id": 36817, "install_script": "#!/bin/sh\n\ninstaller -pkg \"$INSTALLER_PATH\" -target /\n", "pre_install_query": "", "post_install_script": "", "uninstall_script": "#!/bin/sh\n\n# Fleet extracts and saves package IDs.\npkg_ids=(\n 'com.tinyspeck.slackmacgap'\n)\n", "hash_sha256": "f7e4cba7676dacb03ac4cdbe5a99cc1d80ef751c484a13c6a7cf6a93de4a494e", "status": { "installed": 0, "pending_install": 1, "failed_install": 0, "pending_uninstall": 0, "failed_uninstall": 0 }, "self_service": false, "url": "", "fleet_maintained_app_id": null, "automatic_install_policies": null, "labels_include_any": null, "labels_exclude_any": null, "labels_include_all": null, "categories": null, "display_name": "", "patch_policy": null, "fleet_id": 310 }, { "team_id": 310, "title_id": 2792, "name": "Slack-4.51.133-macOS.pkg", "icon_url": null, "version": "4.51.133", "platform": "darwin", "uploaded_at": "2026-06-10T09:14:51.482217Z", "installer_id": 36901, "install_script": "#!/bin/sh\n\ninstaller -pkg \"$INSTALLER_PATH\" -target /\n", "pre_install_query": "", "post_install_script": "", "uninstall_script": "#!/bin/sh\n\n# Fleet extracts and saves package IDs.\npkg_ids=(\n 'com.tinyspeck.slackmacgap'\n)\n", "hash_sha256": "a1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f70819203a4b5c6d7e8f9", "status": { "installed": 0, "pending_install": 0, "failed_install": 0, "pending_uninstall": 0, "failed_uninstall": 0 }, "self_service": true, "url": "", "fleet_maintained_app_id": null, "automatic_install_policies": null, "labels_include_any": null, "labels_exclude_any": null, "labels_include_all": [ { "id": 12, "name": "IT test team" } ], "categories": null, "display_name": "", "patch_policy": null, "fleet_id": 310 } ], "software_package": { "team_id": 310, "title_id": 2792, "name": "Slack-4.50.128-macOS.pkg", "icon_url": null, "version": "4.50.128", "platform": "darwin", "uploaded_at": "2026-06-04T17:29:09.155424Z", "installer_id": 36817, "install_script": "#!/bin/sh\n\ninstaller -pkg \"$INSTALLER_PATH\" -target /\n", "pre_install_query": "", "post_install_script": "", "uninstall_script": "#!/bin/sh\n\n# Fleet extracts and saves package IDs.\npkg_ids=(\n 'com.tinyspeck.slackmacgap'\n)\n\n# For each package id, get all .app folders associated with the package and remove them.\nfor pkg_id in \"${pkg_ids[@]}\"\ndo\n # Get volume and location of the package.\n volume=$(pkgutil --pkg-info \"$pkg_id\" | grep -i \"volume\" | awk '{if (NF>1) print $NF}')\n location=$(pkgutil --pkg-info \"$pkg_id\" | grep -i \"location\" | awk '{if (NF>1) print $NF}')\n # Check if this package id corresponds to a valid/installed package\n if [[ ! -z \"$volume\" ]]; then\n # Remove individual directories that end with \".app\" belonging to the package.\n # Only process directories that end with \".app\" to prevent Fleet from removing top level directories.\n pkgutil --only-dirs --files \"$pkg_id\" | grep \"\\.app$\" | sed -e 's@^@'\"$volume\"\"$location\"'/@' | tr '\\n' '\\0' | xargs -n 1 -0 rm -rf\n # Remove receipts\n pkgutil --forget \"$pkg_id\"\n else\n echo \"WARNING: volume is empty for package ID $pkg_id\"\n fi\ndone\n", "hash_sha256": "f7e4cba7676dacb03ac4cdbe5a99cc1d80ef751c484a13c6a7cf6a93de4a494e", "status": { "installed": 0, "pending_install": 1, "failed_install": 0, "pending_uninstall": 0, "failed_uninstall": 0 }, "self_service": false, "url": "", "fleet_maintained_app_id": null, "automatic_install_policies": null, "labels_include_any": null, "labels_exclude_any": null, "labels_include_all": null, "categories": null, "display_name": "", "patch_policy": null, "fleet_id": 310 }, "app_store_app": null, "bundle_identifier": "com.tinyspeck.slackmacgap", "display_name": "" } } ``` `browser` and `extension_for` fields are included when set and when empty, at the same level as `source`. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. A software title can have more than one package. The `packages` array lists all packages added for the title, including per-package `self_service`, `categories`, and labels (`labels_include_any`, `labels_exclude_any`, `labels_include_all`). `software_package` is kept for backwards compatibility and contains the oldest (first added) package. > Install, pending, and failed counts in `packages.status` are combined across policy automations, setup experience, and manual installs. For Fleet-maintained apps, software package objects include two additional fields: - `pinned_version`: The version the app is pinned to — a specific version (e.g. `"149.0.7827.54"`) or a caret major-version constraint (e.g. `"^147"`). Omitted when the app automatically updates to the latest version. - `fleet_maintained_versions`: The versions Fleet has cached and that are available to pin or roll back to. Each entry includes `id`, `version`, and `uploaded_at`. For example: ```json "packages": [ { "name": "GoogleChrome.pkg", "version": "149.0.7827.54", "platform": "darwin", "fleet_maintained_app_id": 12, "pinned_version": "149.0.7827.54", "fleet_maintained_versions": [ { "id": 36818, "version": "149.0.7827.54", "uploaded_at": "2026-06-04T17:47:23Z" }, { "id": 36817, "version": "148.0.7794.0", "uploaded_at": "2026-05-21T11:02:55Z" } ] } ] ``` For in-house iOS apps, the `software_package` field is populated with package information. For Apple App Store and Google Play apps, the `software_package` field is `null` and `app_store_app` is populated with information from the store. For example: ```json { "app_store_app": { "app_store_id": "361285480", "platform": "darwin", "name": "Keynote: Design Presentations", "latest_version": "15.2.1", "status": { "installed": 13, "pending": 0, "failed": 2 }, "self_service": true, "automatic_install_policies": null, "labels_include_any": null, "labels_exclude_any": null, "labels_include_all": null, "created_at": "2026-01-28T21:49:04.145909Z", "categories": [ "Productivity" ], "display_name": "Keynote" } } ``` ### Get software version Returns information about the specified software version. `GET /api/v1/fleet/software/versions/:id` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | id | integer | path | **Required.** The software version's ID. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters response data to the specified fleet. Use `0` to filter by "Unassigned" hosts. | #### Example `GET /api/v1/fleet/software/versions/12` ##### Default response `Status: 200` ```json { "software": { "id": 425224, "name": "Firefox.app", "display_name": "Firefox", "version": "117.0", "bundle_identifier": "org.mozilla.firefox", "source": "apps", "generated_cpe": "cpe:2.3:a:mozilla:firefox:117.0:*:*:*:*:macos:*:*", "vulnerabilities": [ { "cve": "CVE-2023-4863", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2023-4863", "created_at": "2024-07-01T00:15:00Z", "cvss_score": 8.8, // Available in Fleet Premium "epss_probability": 0.4101, // Available in Fleet Premium "cisa_known_exploit": true, // Available in Fleet Premium "cve_published": "2023-09-12T15:15:00Z", // Available in Fleet Premium "resolved_in_version": "" // Available in Fleet Premium }, { "cve": "CVE-2023-5169", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2023-5169", "created_at": "2024-07-01T00:15:00Z", "cvss_score": 6.5, // Available in Fleet Premium "epss_probability": 0.00073, // Available in Fleet Premium "cisa_known_exploit": false, // Available in Fleet Premium "cve_published": "2023-09-27T15:19:00Z", // Available in Fleet Premium "resolved_in_version": "118" // Available in Fleet Premium } ] } } ``` `browser` and `extension_for` fields are included when set and when empty, at the same level as `source`. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. ### Get operating system version Retrieves information about the specified operating system (OS) version. `GET /api/v1/fleet/os_versions/:id` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | id | integer | path | **Required.** The OS version's ID. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters response data to the specified fleet. Use `0` to filter by "Unassigned" hosts. | | max_vulnerabilities | integer | query | Limits the number of `vulnerabilities` returned. (If omitted, returns all vulnerabilities.) For Linux OS's, doesn't limit the number of vulnerabilities returned in the `kernels` array. | ##### Default response `Status: 200` ```json { "counts_updated_at": "2023-12-06T22:17:30Z", "os_version": { "os_version_id": 123, "hosts_count": 21, "name": "Microsoft Windows 11 Pro 23H2 10.0.22621.1234", "name_only": "Microsoft Windows 11 Pro 23H2", "version": "10.0.22621.1234", "platform": "windows", "generated_cpes": [], "kernels": [], // empty for non-Linux "vulnerabilities": [ { "cve": "CVE-2022-30190", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190", "created_at": "2024-07-01T00:15:00Z", "cvss_score": 7.8,// Available in Fleet Premium "epss_probability": 0.9729,// Available in Fleet Premium "cisa_known_exploit": false,// Available in Fleet Premium "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability.",// Available in Fleet Premium "resolved_in_version": ""// Available in Fleet Premium } ] } } ``` Windows and macOS listed vulnerabilities are based on OS version-specific data. Linux vulnerabilities are based on kernel vulnerabilities for hosts running the specified OS version. Both active and inactive kernels on a host are accounted for in kernel vulnerability reporting, so host counts across kernels may sum to more than the count of hosts running a given OS version. Hosts running in a container or paravirtualized environment do not have a kernel of their own. ```json { "counts_updated_at": "2023-12-06T22:17:30Z", "os_version": { "os_version_id": 321, "hosts_count": 2, "name": "Ubuntu 24.04.1 LTS", "name_only": "Ubuntu", "version": "24.04.1 LTS", "platform": "ubuntu", "generated_cpes": [], "kernels": [ { "id": 561703, // the software version ID of the kernel "version": "6.11.0-26.26~24.04.1", "vulnerabilities": [ "CVE-2023-53034", "CVE-2024-53222", "CVE-2024-58092", "CVE-2024-58093", "CVE-2025-21893", "CVE-2025-21894", "CVE-2025-21902", "CVE-2025-21903", "CVE-2025-21904", "CVE-2025-21905", "CVE-2025-21906", "CVE-2025-21908", "CVE-2025-21909", "CVE-2025-21910", ], "hosts_count": 1 }, { "id": 568096, "version": "6.11.0-29.29~24.04.1", "vulnerabilities": null, "hosts_count": 2 } ], "vulnerabilities": [ { "cve": "CVE-2023-53034", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2023-53034", "created_at": "2023-07-01T00:15:00Z", "cvss_score": 7.8, // Available in Fleet Premium "epss_probability": 0.9729, // Available in Fleet Premium "cisa_known_exploit": false, // Available in Fleet Premium "cve_published": "2023-06-01T00:15:00Z", // Available in Fleet Premium "cve_description": "A description", // Available in Fleet Premium "resolved_in_version": "" // Available in Fleet Premium } ] } } ``` Operating systems other than Windows, macOS, and Linux do not report vulnerabilities. ### Add package _Available in Fleet Premium._ Add a package (.pkg, .msi, .exe, .deb, .rpm, .tar.gz, .ipa) to install on Apple (macOS/iOS/iPadOS), Windows, or Linux hosts. Also supports adding a custom script (.sh and .py for macOS and Linux, .ps1 for Windows). > You need to send a request of type `multipart/form-data`. > This endpoint accepts a maximum request body size of 10GB. `POST /api/v1/fleet/software/package` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | software | file | body | **Required**. Installer package file or custom script file. Supported packages are `.pkg`, `.msi`, `.exe`, `.deb`, `.rpm`, `.tar.gz`, `.ipa`, `.sh`, `.py`, and `.ps1`. | | fleet_id | integer | body | The fleet ID. Adds a software package to the specified fleet. If not specified, it will add the software for "Unassigned" hosts. | | install_script | string | body | Script that Fleet runs to install software. If not specified Fleet runs the [default install script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type if one exists. Required for `.tar.gz` and `.exe` (no default script). Not supported for `.sh`, `.py`, and `.ps1`. | | uninstall_script | string | body | Script that Fleet runs to uninstall software. If not specified Fleet runs the [default uninstall script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type if one exists. Required for `.tar.gz` and `.exe` (no default script). | | pre_install_query | string | body | Query that is pre-install condition. If the query doesn't return any result, Fleet won't proceed to install. | | post_install_script | string | body | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. | | self_service | boolean | body | Self-service software is optional and can be installed by the end user. | | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | body | Target hosts that don't have any label, specified by label name, in the array. | | automatic_install | boolean | body | Specifies whether to create a policy that triggers a software install only on hosts missing the software. Not supported for iOS, iPadOS, Android, or for `.sh`, `.py`, and `.ps1`. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. Add the `X-Fleet-Scripts-Encoded: base64` header line to parse `install_script`, `uninstall_script`, `post_install_script`, and `pre_install_query` fields as bas64-encoded rather than as-is. #### Example ``` POST /api/v1/fleet/software/package ``` ##### Request body ``` fleet_id="1" self_service="true" install_script="sudo installer -pkg /temp/FalconSensor-6.44.pkg -target /" pre_install_query"SELECT 1 FROM macos_profiles WHERE uuid='c9f4f0d5-8426-4eb8-b61b-27c543c9d3db';" post_install_script"sudo /Applications/Falcon.app/Contents/Resources/falconctl license 0123456789ABCDEFGHIJKLMNOPQRSTUV-WX" software="FalconSensor-6.44.pkg" labels_exclude_any="Engineering" labels_exclude_any="QA" ``` ##### Default response `Status: 200` ```json { "software_package": { "team_id": 310, "title_id": 2792, "name": "Slack-4.50.128-macOS.pkg", "icon_url": null, "version": "4.50.128", "platform": "darwin", "uploaded_at": "2026-06-04T17:43:46.125681Z", "installer_id": 36818, "install_script": "#!/bin/sh\n\ninstaller -pkg \"$INSTALLER_PATH\" -target /\n", "pre_install_query": "", "post_install_script": "", "uninstall_script": "#!/bin/sh\n\n# Fleet extracts and saves package IDs.\npkg_ids=(\n 'com.tinyspeck.slackmacgap'\n)\n\n# For each package id, get all .app folders associated with the package and remove them.\nfor pkg_id in \"${pkg_ids[@]}\"\ndo\n # Get volume and location of the package.\n volume=$(pkgutil --pkg-info \"$pkg_id\" | grep -i \"volume\" | awk '{if (NF>1) print $NF}')\n location=$(pkgutil --pkg-info \"$pkg_id\" | grep -i \"location\" | awk '{if (NF>1) print $NF}')\n # Check if this package id corresponds to a valid/installed package\n if [[ ! -z \"$volume\" ]]; then\n # Remove individual directories that end with \".app\" belonging to the package.\n # Only process directories that end with \".app\" to prevent Fleet from removing top level directories.\n pkgutil --only-dirs --files \"$pkg_id\" | grep \"\\.app$\" | sed -e 's@^@'\"$volume\"\"$location\"'/@' | tr '\\n' '\\0' | xargs -n 1 -0 rm -rf\n # Remove receipts\n pkgutil --forget \"$pkg_id\"\n else\n echo \"WARNING: volume is empty for package ID $pkg_id\"\n fi\ndone\n", "hash_sha256": "f7e4cba7676dacb03ac4cdbe5a99cc1d80ef751c484a13c6a7cf6a93de4a494e", "self_service": false, "url": "", "fleet_maintained_app_id": null, "automatic_install_policies": null, "labels_include_any": null, "labels_exclude_any": null, "labels_include_all": null, "categories": null, "display_name": "", "patch_policy": null, "fleet_id": 310 } } ``` ### Update package _Available in Fleet Premium._ Update a package to install on macOS, Windows, Linux, iOS, or iPadOS hosts. > You need to send a request of type `multipart/form-data`. > This endpoint accepts a maximum request body size of 10GB. `PATCH /api/v1/fleet/software/titles/:id/package` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | ID of the software title being updated. | | software | file | body | Installer package file or custom script file. Supported packages are `.pkg`, `.msi`, `.exe`, `.deb`, `.rpm`, `.tar.gz`, `.ipa`, `.sh`, `.py`, and `.ps1`. | | fleet_id | integer | body | **Required**. The fleet ID. Updates a software package in the specified fleet. | | display_name | string | body | Optional override for the default `name`. | | categories | array | body | Zero or more [self-service category](#list-self-service-categories) names defined on the fleet, used to group self-service software on your end users' **Fleet Desktop > My device** page. Each value must match a category that exists on the fleet. Software with no categories will still be shown under **All**. | | install_script | string | body | Command that Fleet runs to install software. If not specified Fleet runs the [default install command](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type. Not supported for `.sh`, `.py`, and `.ps1`. | | pre_install_query | string | body | Query that is pre-install condition. If the query doesn't return any result, the package will not be installed. | | post_install_script | string | body | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. | | self_service | boolean | body | Whether this is optional self-service software that can be installed by the end user. | | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. Only one of either `labels_include_any` or `labels_exclude_any` can be specified. | | labels_exclude_any | array | body | Target hosts that don't have any label, specified by label name, in the array. | | version | string | body | Only available for Fleet-maintained apps. Pins the app to a specific or major version. Available versions are listed in the Fleet UI under **Actions > Versions**. To pin to a major version, use a caret (`^`) constraint and specify only the major version, without the minor and patch versions. For example, `"^147"` means Fleet continuously updates to the latest version until the app reaches 148.0. Set `version` to an empty string (`""`) to switch back to automatically updating to the latest version found in [Fleet's catalog](https://fleetdm.com/software-catalog). `version` can't be changed in the same request as other fields; omit it to leave the current pin unchanged. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. > Changes to the installer package will reset installation counts. Changes to any field other than `self_service` will cancel pending installs for the old package. Add the `X-Fleet-Scripts-Encoded: base64` header line to parse `install_script`, `uninstall_script`, `post_install_script`, and `pre_install_query` fields as bas64-encoded rather than as-is. #### Example `PATCH /api/v1/fleet/software/titles/1/package` ##### Request body ```http fleet_id="1" software="FalconSensor-6.44.pkg" self_service="true" display_name="CrowdStrike agent" install_script="sudo installer -pkg /temp/FalconSensor-6.44.pkg -target /" pre_install_query="SELECT 1 FROM macos_profiles WHERE uuid='c9f4f0d5-8426-4eb8-b61b-27c543c9d3db';" post_install_script="sudo /Applications/Falcon.app/Contents/Resources/falconctl license 0123456789ABCDEFGHIJKLMNOPQRSTUV-WX" ``` ##### Default response `Status: 200` ```json { "software_installer": { "team_id": 310, "title_id": 2792, "name": "Slack-4.45.64-macOS.pkg", "icon_url": null, "version": "4.45.64", "platform": "darwin", "uploaded_at": "2026-06-04T17:47:23Z", "installer_id": 36818, "install_script": "#!/bin/sh\n\ninstaller -pkg \"$INSTALLER_PATH\" -target /\n", "pre_install_query": "", "post_install_script": "", "uninstall_script": "#!/bin/sh\n\n# Fleet extracts and saves package IDs.\npkg_ids=(\n 'com.tinyspeck.slackmacgap'\n)\n\n# For each package id, get all .app folders associated with the package and remove them.\nfor pkg_id in \"${pkg_ids[@]}\"\ndo\n # Get volume and location of the package.\n volume=$(pkgutil --pkg-info \"$pkg_id\" | grep -i \"volume\" | awk '{if (NF>1) print $NF}')\n location=$(pkgutil --pkg-info \"$pkg_id\" | grep -i \"location\" | awk '{if (NF>1) print $NF}')\n # Check if this package id corresponds to a valid/installed package\n if [[ ! -z \"$volume\" ]]; then\n # Remove individual directories that end with \".app\" belonging to the package.\n # Only process directories that end with \".app\" to prevent Fleet from removing top level directories.\n pkgutil --only-dirs --files \"$pkg_id\" | grep \"\\.app$\" | sed -e 's@^@'\"$volume\"\"$location\"'/@' | tr '\\n' '\\0' | xargs -n 1 -0 rm -rf\n # Remove receipts\n pkgutil --forget \"$pkg_id\"\n else\n echo \"WARNING: volume is empty for package ID $pkg_id\"\n fi\ndone\n", "hash_sha256": "dff5434f8ef573f108ec6a48f19ab56c76985178e152ae45de9a575634f849e2", "status": { "installed": 0, "pending_install": 0, "failed_install": 0, "pending_uninstall": 0, "failed_uninstall": 0 }, "self_service": false, "url": "", "fleet_maintained_app_id": null, "automatic_install_policies": null, "labels_include_any": null, "labels_exclude_any": null, "labels_include_all": null, "categories": null, "display_name": "", "patch_policy": null, "fleet_id": 310 } } ``` ### Update software icon _Available in Fleet Premium._ Icon will be displayed in Fleet and on **Fleet Desktop > Self-service**. In the UI for the specified team, overriding the default icon built into Fleet, as well as the Apple-sourced icon if the software has an associated VPP app. > You need to send a request of type `multipart/form-data`. `PUT /api/v1/fleet/software/titles/:id/icon` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | ID of the software title being updated. | | fleet_id | integer | query | **Required**. The fleet ID. Updates a software icon in the specified fleet. | | icon | file | body | Must be PNG format. It must be square with dimensions between 120x120 px and 1024x1024 px. | | hash_sha256 | string | body | SHA256 hash of an already-uploaded icon to use. If provided, `filename` is required and `icon` should be omitted. | | filename | string | body | Filename to record for the icon image, if `hash_sha256` was supplied. | #### Example `PUT /api/v1/fleet/software/titles/33/icon?team_id=2` ##### Request body ```http icon="crowdstrike-icon-512x512.png" ``` ##### Default response `Status: 200` ```json { "icon_url": "/api/latest/fleet/software/titles/33/icon?team_id=2" } ``` ### Download software icon _Available in Fleet Premium._ Download the icon added via [Update software icon](#update-software-icon) or icon from the Apple App Store (VPP). **This endpoint requires authentication.** `GET /api/v1/fleet/software/titles/:id/icon` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | ID of the software title to get icon for. | | fleet_id | integer | query | **Required**. The fleet ID. | This endpoint will redirect (302) to the Apple-hosted URL of an icon if an icon override isn't set and a VPP app is added for the title on the host's team. #### Example `GET /api/v1/fleet/software/titles/33/icon?team_id=2` ##### Default response `Status: 200` ```http Status: 200 Content-Type: image/png Content-Disposition: inline; filename="zoom-icon-512x512.png" Content-Length: 124567 ``` ### Delete software icon _Available in Fleet Premium._ Delete a custom icon added via [Update software icon](#update-software-icon). This will revert to using the software title's built-in icon. `DELETE /api/v1/fleet/software/titles/:id/icon` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | ID of the software title being updated. | | team_id | integer | query | **Required**. The team ID. Updates a software icon in the specified team. | #### Example `DELETE /api/v1/fleet/software/titles/33/icon?team_id=2` ##### Default response `Status: 204` ### List Apple App Store apps Returns the list of Apple App Store (VPP) apps that can be added to the specified fleet. If an app is already added to the fleet, it's excluded from the list. `GET /api/v1/fleet/software/app_store_apps` #### Parameters | Name | Type | In | Description | | ------- | ---- | -- | ----------- | | fleet_id | integer | query | **Required**. The fleet ID. | #### Example `GET /api/v1/fleet/software/app_store_apps/?fleet_id=3` ##### Default response `Status: 200` ```json { "app_store_apps": [ { "name": "Xcode", "display_name": "", "icon_url": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f1/65/1e/a4844ccd-486d-455f-bb31-67336fe46b14/AppIcon-1x_U007emarketing-0-7-0-85-220-0.png/512x512bb.jpg", "latest_version": "15.4", "app_store_id": "497799835", "platform": "darwin" }, { "name": "Logic Pro", "display_name": "", "icon_url": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f1/65/1e/a4844ccd-486d-455f-bb31-67336fe46b14/AppIcon-1x_U007emarketing-0-7-0-85-220-0.png/512x512bb.jpg", "latest_version": "2.04", "app_store_id": "634148309", "platform": "ios" }, { "name": "Logic Pro", "display_name": "", "icon_url": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/f1/65/1e/a4844ccd-486d-455f-bb31-67336fe46b14/AppIcon-1x_U007emarketing-0-7-0-85-220-0.png/512x512bb.jpg", "latest_version": "2.04", "app_store_id": "634148309", "platform": "ipados" } ] } ``` ### Add app store app _Available in Fleet Premium._ Add Apple App Store or Google Play store app. Apple apps must be added in Apple Business (AB) before adding them to Fleet. `POST /api/v1/fleet/software/app_store_apps` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | app_store_id | string | body | **Required.** The ID of the Apple App Store app or Google Play app. | | fleet_id | integer | body | **Required**. The fleet ID. Adds app from the store to the specified fleet. | | platform | string | body | The platform of the app (`darwin`, `ios`, `ipados`, or `android`). Default is `darwin`. | | self_service | boolean | body | **Required if platform is Android**. Currently supported for macOS and Android apps. Specifies whether the app shows up in self-service and is available for install by the end user. For macOS shows up on **Fleet Desktop > My device** page, for Android in **Play Store** app in end user's work profile, and for iOS/iPadOS in [self-service web](https://fleetdm.com/learn-more-about/deploy-self-service-to-ios) app. | | ensure | string | form | For macOS only, if set to "present" (currently the only valid value if set), create a policy that triggers a software install only on hosts missing the software. | | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | form | Target hosts that don't have any label, specified by label name, in the array. | | configuration | object | form | The app's managed configuration. For iOS and iPadOS apps it is in XML format, and for Android Play Store apps it is in JSON format. Currently only supported for iOS, iPadOS, and Android. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. #### Example `POST /api/v1/fleet/software/app_store_apps` ##### Request body ```json { "app_store_id": "497799835", "categories": ["Productivity"], "team_id": 2, "platform": "ipados", "self_service": true } ``` ##### Default response `Status: 200` ```json { "software_title_id": 123, "name": "Xcode" } ``` ##### Default response `Status: 200` ```json { "software_title_id": 456, "name": "Slack" } ``` ### Update app store app _Available in Fleet Premium._ Modify an Apple App Store (VPP) or a Google Play app's options. `PATCH /api/v1/fleet/software/titles/:title_id/app_store_app` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | fleet_id | integer | body | **Required**. The fleet ID. Edits Apple App Store or Android Play store app from the specified fleet. | | display_name | string | body | Optional override for the default `name`. | | self_service | boolean | body | **Required if platform is Android**. Currently supported for macOS and Android apps. Specifies whether the app shows up in self-service and is available for install by the end user. For macOS shows up on **Fleet Desktop > My device** page, and for Android in **Play Store** app in end user's work profile. | | categories | array | body | Zero or more [self-service category](#list-self-service-categories) names defined on the fleet, used to group self-service software on your end users' **Fleet Desktop > My device** page. Each value must match a category that exists on the fleet. Software with no categories will still be shown under **All**. | | auto_update_enabled | boolean | body | Whether to enable automatic updates for iOS/iPadOS App Store (VPP) apps. | | auto_update_window_start | string | body | Update window start time (local time of the device) when automatic updates will take place for iOS/iPadOS App Store (VPP) apps, formatted as HH:MM. Required if `auto_update_enabled` is `true`. | | auto_update_window_end | string | body | Update window end time (local time of the device) when automatic updates will take place for iOS/iPadOS App Store (VPP) apps, formatted as HH:MM. Required if `auto_update_enabled` is `true`. | | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | body | Target hosts that don't have any label, specified by label name, in the array. | | configuration | object | body | The app's managed configuration. For iOS and iPadOS apps it is in XML format, and for Android Play Store apps it is in JSON format. Currently only supported for iOS, iPadOS, and Android. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. `configuration` only supports `managedConfiguration` and `workProfileWidgets` from [Android application policy](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#ApplicationPolicy). Configuration keys vary by app. Refer to the app vendor's documentation for available managed configuration options. For example, see [Zoom's Android managed configuration](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0064790) or [GlobalProtect's Android configuration](https://docs.paloaltonetworks.com/globalprotect/10-1/globalprotect-admin/mobile-endpoint-management/manage-the-globalprotect-app-using-other-third-party-mdms/configure-the-globalprotect-app-for-android). #### Example `PATCH /api/v1/fleet/software/titles/3467/app_store_app` ##### Request body ```json { "team_id": 2, "self_service": true, "categories": ["Browser"], "labels_include_any": [ "Product", "Marketing" ] } ``` ##### Default response `Status: 200` ```json { "app_store_app": { "name": "Logic Pro", "display_name": "", "icon_url": null, "app_store_id": 1091189122, "categories": ["Browser"], "latest_version": "2.04", "self_service": true, "labels_include_any": [ { "name": "Product", "id": 12 }, { "name": "Marketing", "id": 17 } ], "automatic_install_policies": [ { "id": 345, "name": "[Install software] Logic Pro", "type": "dynamic" } ], "status": { "installed": 3, "pending": 1, "failed": 2 } } } ``` ### List Fleet-maintained apps List available Fleet-maintained apps. `GET /api/v1/fleet/software/fleet_maintained_apps` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | fleet_id | integer | query | If specified, each app includes the `software_title_id` if the software has already been added to that fleet. | | query | string | query | Search query keywords. Searches app name. | | order_key | string | query | What to order results by. Currently only `name` is supported. | | order_direction | string | query | **Requires `order_key`**. The direction of the order. Options are `"asc"` and `"desc"`. Default is `"asc"`. | | page | integer | query | Page number of the results to fetch. Pagination is by app: an app's macOS and Windows entries are counted as one result and always returned on the same page. | | per_page | integer | query | Results (apps) per page. | | platform | string | query | Filter to apps available on a platform. Options are `"darwin"` (macOS) and `"windows"`. | | available | boolean | query | If `true`, only return apps that have not yet been added to the fleet. Requires `fleet_id`. | #### Example `GET /api/v1/fleet/software/fleet_maintained_apps?fleet_id=3` ##### Default response `Status: 200` ```json { "fleet_maintained_apps": [ { "id": 1, "name": "1Password", "slug": "1password/darwin", "platform": "darwin", "version": "8.10.40", "software_title_id": 1 }, { "id": 2, "name": "Adobe Acrobat Reader", "slug": "adobe-acrobat-reader/darwin", "platform": "darwin", "version": "24.002.21005", "software_title_id": null }, { "id": 3, "name": "Box Drive", "slug": "box-drive/darwin", "platform": "darwin", "version": "2.39.179", "software_title_id": 3 } ], "count": 250, "meta": { "has_next_results": false, "has_previous_results": false } } ``` > `count` is the total number of Fleet-maintained apps matching the query. An app's macOS and Windows versions are counted separately, even though the UI combines them into a single row. ### Get Fleet-maintained app Returns information about the specified Fleet-maintained app. `GET /api/v1/fleet/software/fleet_maintained_apps/:id` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | id | integer | path | **Required.** The Fleet-maintained app's ID. | | fleet_id | integer | query | If supplied, set `software_title_id` on the response when an installer or VPP app has already been added to that fleet for that software. | #### Example `GET /api/v1/fleet/software/fleet_maintained_apps/1` ##### Default response `Status: 200` ```json { "fleet_maintained_app": { "id": 1, "slug": "1password/darwin", "name": "1Password", "filename": "1Password-8.10.50-aarch64.zip", "version": "8.10.50", "platform": "darwin", "url": "https://downloads.1password.com/mac/1Password-8.10.50-aarch64.zip", "install_script": "#!/bin/sh\ninstaller -pkg \"$INSTALLER_PATH\" -target /", "uninstall_script": "#!/bin/sh\npkg_ids=$PACKAGE_ID\nfor pkg_id in '${pkg_ids[@]}'...", "software_title_id": 3, "categories": ["Productivity"] } } ``` ### Add Fleet-maintained app _Available in Fleet Premium._ Add Fleet-maintained app so it's available for install. `POST /api/v1/fleet/software/fleet_maintained_apps` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | fleet_maintained_app_id | integer | body | **Required.** The ID of Fleet-maintained app. | | fleet_id | integer | body | **Required**. The fleet ID. Adds Fleet-maintained app to the specified fleet. | | install_script | string | body | Command that Fleet runs to install software. If not specified Fleet runs default install command for each Fleet-maintained app. | | pre_install_query | string | body | Query that is pre-install condition. If the query doesn't return any result, Fleet won't proceed to install. | | post_install_script | string | body | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. | | self_service | boolean | body | Self-service software is optional and can be installed by the end user. | | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | form | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | form | Target hosts that don't have any label, specified by label name, in the array. | | automatic_install | boolean | form | Create a policy that triggers a software install only on hosts missing the software. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. Add the `X-Fleet-Scripts-Encoded: base64` header line to parse `install_script`, `uninstall_script`, `post_install_script`, and `pre_install_query` fields as bas64-encoded rather than as-is. #### Example `POST /api/v1/fleet/software/fleet_maintained_apps` ##### Request body ```json { "fleet_maintained_app_id": 3, "team_id": 2, "automatic_install": true } ``` ##### Default response `Status: 200` ```json { "software_title_id": 234 } ``` ### Create Android web app _Available in Fleet Premium._ Creates web app (web clip). This endpoint returns the application ID that can be used to [add an Android app](#add-app-store-app) to Fleet. > You need to send a request of type `multipart/form-data`. `POST /api/v1/fleet/software/web_apps` #### Parameters | Name | Type | In | Description | | ---- | ---- | -- | ----------- | | title | string | body | **Required.** It is displayed to the end user under the app icon. | | url | string | body | **Required.** The URL of the web app. What the end user sees when they open this app. | | icon | file | body | The app icon. The icon must be a PNG file and square, with dimensions of at least 512 x 512px. | #### Example `POST /api/v1/fleet/software/web_apps` ##### Request body ```http title="Acme web app" url="https://app.acme.com" icon="app-icon-512x512.png" ``` ##### Default response `Status: 200` ```json { "app_store_id": "com.google.enterprise.webapp.x1c41e22ab611cb98" } ``` ### Download software _Available in Fleet Premium._ `GET /api/v1/fleet/software/titles/:id/package?alt=media` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The ID of the software title to download software package.| | fleet_id | integer | query | **Required**. The fleet ID. Downloads a software package added to the specified fleet. | | alt | string | query | **Required**. If specified and set to `"media"`, downloads the specified software package. | #### Example `GET /api/v1/fleet/software/titles/123/package?alt=media&team_id=2` ##### Default response `Status: 200` ```http Status: 200 Content-Type: application/octet-stream Content-Disposition: attachment Content-Length: Body: ``` ### Install software _Available in Fleet Premium._ Install software (package or app store app) on a macOS, iOS, iPadOS, Windows, or Linux (Ubuntu) host. Software title must have a `software_package` or `app_store_app` to be installed. Package installs time out after 1 hour. `POST /api/v1/fleet/hosts/:id/software/:software_title_id/install` #### Parameters | Name | Type | In | Description | | --------- | ---------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The host's ID. | | software_title_id | integer | path | **Required**. The software title's ID. | #### Example `POST /api/v1/fleet/hosts/123/software/3435/install` ##### Default response `Status: 202` ### Uninstall software _Available in Fleet Premium._ Uninstalls software from a host. `POST /api/v1/fleet/hosts/:id/software/:software_title_id/uninstall` #### Parameters | Name | Type | In | Description | | --------- | ---------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The host's ID. | | software_title_id | integer | path | **Required**. The software title's ID. | #### Example `POST /api/v1/fleet/hosts/123/software/3435/uninstall` ##### Default response `Status: 202` ### Install self-service software by Fleet Desktop token Install self-service software on a macOS, Windows, or Linux host. The software must have a `self_service` flag `true` to be installed. `POST /api/v1/fleet/device/:token/software/install/:software_title_id` #### Parameters | Name | Type | In | Description | | ----- | ------ | ---- | ---------------------------------- | | token | string | path | **Required**. The host's [Fleet Desktop token](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). | | software_title_id | string | path | **Required**. The software title's ID. | #### Example `POST /api/v1/fleet/device/22aada07-dc73-41f2-8452-c0987543fd29/software/install/123` ##### Default response `Status: 202` ### Get software install result _Available in Fleet Premium._ `GET /api/v1/fleet/software/install/:install_uuid/results` Get the results of a Fleet-maintained app or custom package install. To get uninstall results, use the [List activities](#list-activities) and [Get script result](#get-script-result) API endpoints. To get the results of an Apple App Store app install, use the [List MDM commands](#list-mdm-commands) and [Get MDM command results](#get-mdm-command-results) API endpoints. Fleet uses an MDM command to install Apple App Store apps. | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | install_uuid | string | path | **Required**. The software installation UUID.| #### Example `GET /api/v1/fleet/software/install/b15ce221-e22e-4c6a-afe7-5b3400a017da/results` ##### Default response `Status: 200` ```json { "install_uuid": "b15ce221-e22e-4c6a-afe7-5b3400a017da", "software_title": "Falcon.app", "software_title_id": 8353, "software_package": "FalconSensor-6.44.pkg", "host_id": 123, "host_display_name": "Marko's MacBook Pro", "status": "failed_install", "output": "Installing software...\nError: The operation can’t be completed because the item "Falcon" is in use.", "pre_install_query_output": "Query returned result\nSuccess", "post_install_script_output": "Running script...\nExit code: 1 (Failed)\nRolling back software install...\nSuccess" } ``` ### Delete software _Available in Fleet Premium._ Deletes software that's available for install. This won't uninstall the software from hosts. `DELETE /api/v1/fleet/software/titles/:software_title_id/available_for_install` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | software_title_id | integer | path | **Required**. The ID of the software title to delete software available for install. | | fleet_id | integer | query | **Required**. The fleet ID. Deletes a software package added to the specified fleet. | #### Example `DELETE /api/v1/fleet/software/titles/24/available_for_install?team_id=2` ##### Default response `Status: 204` ## Self-service categories _Available in Fleet Premium_ Self-service categories let IT admins group self-service software on each fleet so end users can browse and install software by category on the **My device > Self-service** page. When a new fleet is created, Fleet seeds it with the following default categories that can be renamed or deleted: **🌎 Browsers**, **👬 Communication**, **🧰 Developer tools**, **💻 Productivity**, **🔐 Security**, and **🛟 Support**. - [List self-service categories](#list-self-service-categories) - [Add self-service category](#add-self-service-category) - [Update self-service category](#update-self-service-category) - [Delete self-service category](#delete-self-service-category) ### List self-service categories Lists all self-service categories on the specified fleet. `GET /api/v1/fleet/software/self_service_categories` #### Parameters | Name | Type | In | Description | | -------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------- | | fleet_id | integer | query | **Required**. The fleet ID. Use `0` to list categories for "Unassigned" hosts. | #### Example `GET /api/v1/fleet/software/self_service_categories?fleet_id=3` ##### Default response `Status: 200` ```json { "self_service_categories": [ { "id": 12, "name": "🌎 Browsers", "fleet_id": 3, "created_at": "2026-05-01T14:22:58Z", "updated_at": "2026-05-01T14:22:58Z" }, { "id": 13, "name": "🧰 Developer tools", "fleet_id": 3, "created_at": "2026-05-01T14:22:58Z", "updated_at": "2026-05-01T14:22:58Z" } ] } ``` ### Add self-service category Creates a new self-service category on the specified fleet. Only global and fleet admins and maintainers can call this endpoint. `POST /api/v1/fleet/software/self_service_categories` #### Parameters | Name | Type | In | Description | | -------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | fleet_id | integer | body | **Required**. The fleet ID. Use `0` to add the category to "Unassigned" hosts. | | name | string | body | **Required**. The category name. Must be unique within the fleet (case-insensitive) and at most 255 characters. Emojis are supported and are part of the name (e.g. `"🌎 Browsers"`). | #### Example `POST /api/v1/fleet/software/self_service_categories` ##### Request body ```json { "fleet_id": 3, "name": "💼 Engineering" } ``` ##### Default response `Status: 200` ```json { "self_service_category": { "id": 42, "name": "💼 Engineering", "fleet_id": 3, "created_at": "2026-05-12T18:45:00Z", "updated_at": "2026-05-12T18:45:00Z" } } ``` ### Update self-service category Renames an existing self-service category. Only global and fleet admins and maintainers can call this endpoint. `PATCH /api/v1/fleet/software/self_service_categories/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | integer | path | **Required**. The self-service category ID. | | name | string | body | **Required**. The new category name. Must be unique within the fleet (case-insensitive) and at most 255 characters. Emojis are supported and are part of the name. | #### Example `PATCH /api/v1/fleet/software/self_service_categories/42` ##### Request body ```json { "name": "💼 Engineering tools" } ``` ##### Default response `Status: 200` ```json { "self_service_category": { "id": 42, "name": "💼 Engineering tools", "fleet_id": 3, "created_at": "2026-05-12T18:45:00Z", "updated_at": "2026-05-12T19:01:00Z" } } ``` ### Delete self-service category Deletes the specified self-service category. Software assigned to the deleted category is removed from that category but otherwise unaffected. Only global and fleet admins and maintainers can call this endpoint. `DELETE /api/v1/fleet/software/self_service_categories/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | **Required**. The self-service category ID. | #### Example `DELETE /api/v1/fleet/software/self_service_categories/42` ##### Default response `Status: 204` ## Vulnerabilities - [List vulnerabilities](#list-vulnerabilities) - [Get vulnerability](#get-vulnerability) ### List vulnerabilities Retrieves a list of all CVEs affecting software and/or OS versions. `GET /api/v1/fleet/vulnerabilities` #### Parameters | Name | Type | In | Description | | --- | --- | --- | --- | | fleet_id | integer | query | _Available in Fleet Premium_. Filters only include vulnerabilities affecting the specified fleet. Use `0` to filter by "Unassigned" hosts. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are: `cve`, `cvss_score`, `epss_probability`, `cve_published`, `created_at`, and `host_count`. Default is `created_at` (descending). | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | query | string | query | Search query keywords. Searchable fields include `cve`. | | exploit | boolean | query | _Available in Fleet Premium_. If `true`, filters to only include vulnerabilities that have been actively exploited in the wild (`cisa_known_exploit: true`). Otherwise, includes vulnerabilities with any `cisa_known_exploit` value. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | ##### Default response `Status: 200` ```json { "vulnerabilities": [ { "cve": "CVE-2022-30190", "created_at": "2022-06-01T00:15:00Z", "hosts_count": 1234, "hosts_count_updated_at": "2023-12-20T15:23:57Z", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190", "cvss_score": 7.8,// Available in Fleet Premium "epss_probability": 0.9729,// Available in Fleet Premium "cisa_known_exploit": false,// Available in Fleet Premium "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability." // Available in Fleet Premium } ], "count": 123, "counts_updated_at": "2024-02-02T16:40:37Z", "meta": { "has_next_results": false, "has_previous_results": false } } ``` ### Get vulnerability Retrieve details about a vulnerability and its affected software and OS versions. If no vulnerable OS versions or software were found, but Fleet is aware of the vulnerability, a `204` status code is returned. `GET /api/v1/fleet/vulnerabilities/:cve` #### Parameters | Name | Type | In | Description | |---------|---------|-------|------------------------------------------------------------------------------------------------------------------------------| | cve | string | path | The cve to get information about (format must be CVE-YYYY-<4 or more digits>, case-insensitive). | | fleet_id | integer | query | _Available in Fleet Premium_. Filters response data to the specified fleet. Use `0` to filter by "Unassigned" hosts. | #### Example `GET /api/v1/fleet/vulnerabilities/cve-2022-30190` ##### Default response `Status: 200` ```json { "vulnerability": { "cve": "CVE-2022-30190", "created_at": "2022-06-01T00:15:00Z", "hosts_count": 1234, "hosts_count_updated_at": "2023-12-20T15:23:57Z", "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190", "cvss_score": 7.8,// Available in Fleet Premium "epss_probability": 0.9729,// Available in Fleet Premium "cisa_known_exploit": false,// Available in Fleet Premium "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability.",// Available in Fleet Premium "os_versions" : [ { "os_version_id": 6, "hosts_count": 200, "name": "macOS 14.1.2", "name_only": "macOS", "version": "14.1.2", "resolved_in_version": "14.2", "generated_cpes": [ "cpe:2.3:o:apple:macos:*:*:*:*:*:14.2:*:*", "cpe:2.3:o:apple:mac_os_x:*:*:*:*:*:14.2:*:*" ] } ], "software": [ { "id": 2363, "software_title_id": 124, "name": "Docker Desktop", "version": "4.9.1", "source": "programs", "generated_cpe": "cpe:2.3:a:docker:docker_desktop:4.9.1:*:*:*:*:windows:*:*", "hosts_count": 50, "resolved_in_version": "5.0.0" } ] } } ``` The `extension_for` field is included when set and when empty, at the same level as `source`. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. --- ## Targets In Fleet, targets are used to run reports against specific hosts or groups of hosts. Labels are used to create groups in Fleet. ### Search targets The search targets endpoint returns two lists. The first list includes the possible target hosts in Fleet given the search query provided and the hosts already selected as targets. The second list includes the possible target labels in Fleet given the search query provided and the labels already selected as targets. The returned lists are filtered based on the hosts the requesting user has access to. `POST /api/v1/fleet/targets` #### Parameters | Name | Type | In | Description | | -------- | ------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | query | string | body | The search query. Searchable items include a host's hostname or IPv4 address and labels. | | query_id | integer | body | The saved query (if any) that will be run. The `observer_can_run` property on the query and the user's roles effect which targets are included. | | selected | object | body | The targets already selected. The object includes a `hosts` property which contains a list of host IDs, a `labels` with label IDs and/or a `fleets` property with fleet IDs. | #### Example `POST /api/v1/fleet/targets` ##### Request body ```json { "query": "172", "selected": { "hosts": [], "labels": [7] }, "include_observer": true } ``` ##### Default response ```json { "targets": { "hosts": [ { "created_at": "2021-02-03T16:11:43Z", "updated_at": "2021-02-03T21:58:19Z", "id": 3, "detail_updated_at": "2021-02-03T21:58:10Z", "label_updated_at": "2021-02-03T21:58:10Z", "policy_updated_at": "2023-06-26T18:33:15Z", "last_enrolled_at": "2021-02-03T16:11:43Z", "software_updated_at": "2020-11-05T05:09:44Z", "seen_time": "2021-02-03T21:58:20Z", "hostname": "7a2f41482833", "uuid": "a2064cef-0000-0000-afb9-283e3c1d487e", "platform": "rhel", "osquery_version": "4.5.1", "os_version": "CentOS 6.10.0", "build": "", "platform_like": "rhel", "code_name": "", "uptime": 32688000000000, "memory": 2086899712, "cpu_type": "x86_64", "cpu_subtype": "142", "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz", "cpu_physical_cores": 4, "cpu_logical_cores": 4, "hardware_vendor": "", "hardware_model": "", "hardware_version": "", "hardware_serial": "", "computer_name": "7a2f41482833", "timezone": null, "display_name": "7a2f41482833", "primary_ip": "172.20.0.3", "primary_mac": "02:42:ac:14:00:03", "distributed_interval": 10, "config_tls_refresh": 10, "logger_tls_period": 10, "additional": {}, "status": "offline", "display_text": "7a2f41482833" }, { "created_at": "2021-02-03T16:11:43Z", "updated_at": "2021-02-03T21:58:19Z", "id": 4, "detail_updated_at": "2021-02-03T21:58:10Z", "label_updated_at": "2021-02-03T21:58:10Z", "policy_updated_at": "2023-06-26T18:33:15Z", "last_enrolled_at": "2021-02-03T16:11:43Z", "software_updated_at": "2020-11-05T05:09:44Z", "seen_time": "2021-02-03T21:58:20Z", "hostname": "78c96e72746c", "uuid": "a2064cef-0000-0000-afb9-283e3c1d487e", "platform": "ubuntu", "osquery_version": "4.5.1", "os_version": "Ubuntu 16.4.0", "build": "", "platform_like": "debian", "code_name": "", "uptime": 32688000000000, "memory": 2086899712, "cpu_type": "x86_64", "cpu_subtype": "142", "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz", "cpu_physical_cores": 4, "cpu_logical_cores": 4, "hardware_vendor": "", "hardware_model": "", "hardware_version": "", "hardware_serial": "", "computer_name": "78c96e72746c", "timezone": null, "display_name": "78c96e72746c", "primary_ip": "172.20.0.7", "primary_mac": "02:42:ac:14:00:07", "distributed_interval": 10, "config_tls_refresh": 10, "logger_tls_period": 10, "additional": {}, "status": "offline", "display_text": "78c96e72746c" } ], "labels": [ { "created_at": "2021-02-02T23:55:25Z", "updated_at": "2021-02-02T23:55:25Z", "id": 6, "name": "All Hosts", "description": "All hosts which have enrolled in Fleet", "query": "SELECT 1;", "label_type": "builtin", "label_membership_type": "dynamic", "host_count": 5, "display_text": "All Hosts", "count": 5 } ], "fleets": [ { "id": 1, "created_at": "2021-05-27T20:02:20Z", "name": "Client Platform Engineering", "description": "", "agent_options": null, "user_count": 4, "host_count": 2, "display_text": "Client Platform Engineering", "count": 2 } ] }, "targets_count": 1, "targets_online": 1, "targets_offline": 0, "targets_missing_in_action": 0 } ``` --- ## Fleets - [List fleets](#list-fleets) - [Get fleet](#get-fleet) - [Create fleet](#create-fleet) - [Update fleet](#update-fleet) - [Add users to fleet](#add-users-to-fleet) - [Update fleet-level agent options](#update-fleets-agent-options) - [Delete fleet](#delete-fleet) ### List fleets _Available in Fleet Premium_ `GET /api/v1/fleet/fleets` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be any column in the `fleets` table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | query | string | query | Search query keywords. Searchable fields include `name`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/fleets` ##### Default response `Status: 200` ```json { "fleets": [ { "id": 1, "created_at": "2021-07-28T15:58:21Z", "name": "workstations", "description": "", "agent_options": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "user_count": 0, "host_count": 0, "secrets": [ { "secret": "", "created_at": "2021-07-28T15:58:21Z", "team_id": 10 } ] }, { "id": 2, "created_at": "2021-08-05T21:41:42Z", "name": "servers", "description": "", "agent_options": { "spec": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "user_count": 0, "host_count": 0, "secrets": [ { "secret": "+ncixtnZB+IE0OrbrkCLeul3U8LMVITd", "created_at": "2021-08-05T21:41:42Z", "team_id": 15 } ] } } ] } ``` ### Get fleet _Available in Fleet Premium_ `GET /api/v1/fleet/fleets/:id` `mdm.apple_settings.configuration_profiles`, `mdm.windows_settings.configuration_profiles`, `scripts`, and `mdm.setup_experience` only include the configuration profiles, scripts, and setup experience settings applied using [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To list profiles, scripts, or setup experience settings added in the UI or API, use the [List configuration profiles](https://fleetdm.com/docs/rest-api/rest-api#list-custom-os-settings-configuration-profiles), [List scripts](https://fleetdm.com/docs/rest-api/rest-api#list-scripts), or GET endpoints from [Setup experience](https://fleetdm.com/docs/rest-api/rest-api#setup-experience) instead. "Unassigned" (id 0) will only return `id`, `name`, `webhook_settings.failing_policies_webhook`, `integrations.jira`, and `integrations.zendesk` fields. #### Parameters | Name | Type | In | Description | |------|---------|------|----------------------------------------------------------------------------------------------| | id | integer | path | **Required.** The desired fleet's ID. Use `0` for "Unassigned" hosts. | #### Example `GET /api/v1/fleet/fleets/1` ##### Default response `Status: 200` ```json { "team": { "name": "Workstations", "id": 1, "user_count": 4, "host_count": 0, "agent_options": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "webhook_settings": { "failing_policies_webhook": { "enable_failing_policies_webhook": false, "destination_url": "", "policy_ids": null, "host_batch_size": 0 } }, "integrations": { "google_calendar": { "enable_calendar_events": true, "webhook_url": "https://server.com/example" } }, "mdm": { "enable_disk_encryption": true, "windows_require_bitlocker_pin": false, "macos_updates": { "minimum_version": "12.3.1", "deadline": "2022-01-01", "update_new_hosts": true }, "windows_updates": { "deadline_days": 5, "grace_period_days": 1 }, "macos_settings": { "custom_settings": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] } ] }, "apple_settings": { "configuration_profiles": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] }, { "path": "path/to/declaration.json", "labels": ["Label 1", "Label 2"] }, { "path": "path/to/assets/asset.json" } ], "assets": [ { "path": "path/to/assets/asset.json" } ], "managed_local_account_settings": { "enabled": true }, }, "windows_settings": { "custom_settings": [ { "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } ], "configuration_profiles": [ { "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } ], "managed_local_account_settings": { "enabled": true }, }, "macos_setup": { "bootstrap_package": "", "enable_end_user_authentication": false, "macos_setup_assistant": "path/to/config.json", "enable_release_device_manually": false, "manual_agent_install": false }, "setup_experience": { "bootstrap_package": "", "enable_end_user_authentication": false, "enable_managed_local_account": false, "end_user_local_account_type": "admin", "apple_setup_assistant": "path/to/config.json", "enable_release_device_manually": false, "manual_agent_install": false } } } } ``` ### Create fleet _Available in Fleet Premium_ `POST /api/v1/fleet/fleets` #### Parameters | Name | Type | In | Description | | ---- | ------ | ---- | ------------------------------ | | name | string | body | **Required.** The fleet's name. Fleet names must differ by more than letter case. | #### Example `POST /api/v1/fleet/fleets` ##### Request body ```json { "name": "workstations" } ``` ##### Name conflict response `Status: 409` Returned when the requested name only differs from an existing fleet's name by letter case. ```json { "message": "Conflict", "errors": [ { "name": "base", "reason": "A fleet named \"Workstations\" already exists. Fleet names must differ by more than letter case." } ] } ``` ##### Default response `Status: 200` ```json { "team": { "name": "workstations", "id": 1, "user_count": 0, "host_count": 0, "agent_options": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "webhook_settings": { "failing_policies_webhook": { "enable_failing_policies_webhook": false, "destination_url": "", "policy_ids": null, "host_batch_size": 0 } } } } ``` ### Update fleet _Available in Fleet Premium_ `PATCH /api/v1/fleet/fleets/:id` #### Parameters | Name | Type | In | Description | | ------------------------------------------------------- | ------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | integer | path | **Required.** The desired fleet's ID. Use `0` for "Unassigned" hosts. **Note:** When using `id=0`, only `webhook_settings.failing_policies_webhook`, `integrations.jira`, and `integrations.zendesk` fields are supported in the request body. | | name | string | body | The fleet's name. Fleet names must differ by more than letter case. Renaming a fleet into another fleet's name returns a 409 Conflict error. | | host_ids | array | body | A list of hosts that belong to the fleet. | | user_ids | array | body | A list of users on the fleet. | | webhook_settings | object | body | Webhook settings for the fleet. See [webhook_settings](#webhook-settings2). | | integrations | object | body | Integrations settings for the fleet. 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 fleet. See [mdm](#mdm2) for details. | | host_expiry_settings | object | body | Host expiry settings for the fleet. See [host_expiry_settings](#host-expiry-settings2) for details. | | features | object | body | Per-fleet feature toggles. v1 accepts only the `historical_data` sub-field; other `features` sub-fields are writable per-fleet only via GitOps. See [features.historical_data](#features-historical-data) below. | #### Example (transfer hosts to a fleet) `PATCH /api/v1/fleet/fleets/1` ##### Request body ```json { "host_ids": [3, 6, 7, 8, 9, 20, 32, 44] } ``` ##### Name conflict response `Status: 409` Returned when the requested name only differs from another fleet's name by letter case. Renaming a fleet to a case variant of its own current name (e.g., `ABC` → `abc`) succeeds. ```json { "message": "Conflict", "errors": [ { "name": "base", "reason": "A fleet named \"Workstations\" already exists. Fleet names must differ by more than letter case." } ] } ``` ##### Default response `Status: 200` ```json { "team": { "name": "Workstations", "id": 1, "user_count": 4, "host_count": 8, "agent_options": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "webhook_settings": { "failing_policies_webhook": { "enable_failing_policies_webhook": false, "destination_url": "", "policy_ids": null, "host_batch_size": 0 } } } } ``` #### 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). |
##### 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). |
##### 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. |
##### 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). | | conditional_access_enabled | boolean | **Available in Fleet Premium.** Whether to block third party app sign-ins on hosts failing policies. Must have Microsoft Entra or Okta connected and configured in global config. |
##### 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`). |
##### 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`). |
##### 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 fleet. | | webhook_url | string | The URL to send a request to during calendar events, to trigger auto-remediation. | ##### Example request body ```json { "integrations": { "conditional_access_enabled": true, "jira": [ { "enable_software_vulnerabilities": false, "enable_failing_poilicies": true, "url": "https://jiraserver.com", "username": "some_user", "api_token": "", "project_key": "jira_project", } ], "zendesk": [], "google_calendar": [ { "domain": "https://domain.com", "api_key_json": "" } ] } } ``` #### mdm | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_disk_encryption | boolean | Hosts that belong to this fleet will have disk encryption enabled if set to true. | | windows_require_bitlocker_pin | boolean | End users on Windows hosts that belong to this fleet will be required to set a BitLocker PIN if set to true. `enable_disk_encryption` must be set to true. When the PIN is set, it's required to unlock Windows host during startup. | | 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). | | apple_settings | object | See [`mdm.apple_settings`](#mdm-apple-settings2). | | windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings2). | | setup_experience | object | See [`mdm.setup_experience`](#mdm-setup-experience2). |
##### mdm.macos_updates `mdm.macos_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that belong to this fleet and have MDM turned on will be prompted to update when their OS is below this version. | | deadline | string | Hosts that belong to this fleet and have MDM turned on will be forced to update their OS after this deadline (7PM local time for hosts already on macOS 14 or above, 20:00 UTC for hosts on earlier macOS versions). | | update_new_hosts | string | macOS hosts that automatically enroll (ADE) are updated to [Apple's latest version](https://fleetdm.com/guides/enforce-os-updates) during macOS Setup Assistant. For backwards compatibility, if not specified, and `deadline` and `minimum_version` are set, `update_new_hosts` is set to `true`. Otherwise, `update_new_hosts` defaults to `false`. |
##### mdm.ios_updates `mdm.ios_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that belong to this fleet will be prompted to update when their OS is below this version. | | deadline | string | Hosts that belong to this fleet will be forced to update their OS after this deadline (7PM local time). |
##### mdm.ipados_updates `mdm.ipados_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that belong to this fleet will be prompted to update when their OS is below this version. | | deadline | string | Hosts that belong to this fleet will be forced to update their OS after this deadline (7PM local time). |
##### mdm.windows_updates `mdm.windows_updates` is an object with the following structure: | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | deadline_days | integer | Hosts that belong to this fleet and have MDM turned on will have this number of days before updates are installed on Windows. | | grace_period_days | integer | Hosts that belong to this fleet and have MDM turned on will have this number of days before Windows restarts to install updates. |
##### mdm.macos_settings `mdm.macos_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 macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. |
##### mdm.apple_settings `mdm.apple_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 macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | | managed_local_account_settings | object | Settings for the managed local account. | | managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). | | end_user_local_account_type | string | The end user account type. Requires `managed_local_account_settings.enabled` to be `true`. Options: `"admin"`, `"standard"`, `"none"` (default: `"admin"`). |
##### 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 [Create configuration profile](#create-configuration-profile) endpoint instead. | | managed_local_account_settings | object | Settings for the managed local account. | | managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). |
##### mdm.setup_experience `mdm.setup_experience` is an object with the following structure: | Name | Type | Description | | ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_end_user_authentication | boolean | If set to true, IdP authentication will be required during automatic MDM enrollment of new macOS hosts. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#require-idp-authentication). | lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) | | enable_managed_local_account | boolean | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on eligible hosts if set to true. | | end_user_local_account_type | string | body | Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | ##### Example request body ```json { "mdm": { "enable_disk_encryption": true, "windows_require_bitlocker_pin": true, "macos_updates": { "minimum_version": "12.3.1", "deadline": "2025-04-01", "update_new_hosts": true }, "ios_updates": { "minimum_version": "18.3.1", "deadline": "2025-04-01" }, "windows_updates": { "deadline_days": 5, "grace_period_days": 1 }, "apple_settings": { "configuration_profiles": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] }, { "path": "path/to/profile2.json", "labels": ["Label 3", "Label 4"] }, { "path": "path/to/assets/asset.json" }, ], "assets": [ { "path": "path/to/assets/asset.json" } ], "managed_local_account_settings": { "enabled": true } }, "windows_settings": { "custom_settings": [ { "path": "path/to/profile3.xml", "labels": ["Label 1", "Label 2"] } ], "configuration_profiles": [ { "path": "path/to/profile3.xml", "labels": ["Label 1", "Label 2"] } ], "managed_local_account_settings": { "enabled": true } }, "setup_experience": { "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. |
##### Example request body ```json { "host_expiry_settings": { "host_expiry_enabled": true, "host_expiry_window": 7 } } ``` ##### features.historical_data Sub-keys mirror the global `features.historical_data` shape and default to `true`. A dataset is collected for a host in this fleet only when both the global sub-key AND this fleet's sub-key are `true`. Sub-keys omitted from the PATCH body retain their current stored value. | Name | Type | Description | | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------- | | uptime | boolean | Whether to collect host-uptime samples for hosts in this fleet. (Default: `true`) | | vulnerabilities | boolean | Whether to collect CVE samples for hosts in this fleet. (Default: `true`) | ###### Example request body ```json { "features": { "historical_data": { "vulnerabilities": false } } } ``` ### Add users to fleet _Available in Fleet Premium_ `PATCH /api/v1/fleet/fleets/:id/users` #### Parameters | Name | Type | In | Description | |------------------|---------|------|----------------------------------------------| | id | integer | path | **Required.** The desired fleet's ID. | | users | string | body | Array of users to add. | |   id | integer | body | The id of the user. | |   role | string | body | The fleet role that the user will be granted. Options are: "admin", "maintainer", "observer", "observer_plus", and "gitops". | #### Example `PATCH /api/v1/fleet/fleets/1/users` ##### Request body ```json { "users": [ { "id": 1, "role": "admin" }, { "id": 17, "role": "observer" } ] } ``` ##### Default response `Status: 200` ```json { "team": { "name": "Workstations", "id": 1, "user_count": 2, "host_count": 0, "agent_options": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 10, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 10, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "webhook_settings": { "failing_policies_webhook": { "enable_failing_policies_webhook": false, "destination_url": "", "policy_ids": null, "host_batch_size": 0 } }, "mdm": { "enable_disk_encryption": true, "windows_require_bitlocker_pin": false, "macos_updates": { "minimum_version": "12.3.1", "deadline": "2022-01-01", "update_new_hosts": true }, "windows_updates": { "deadline_days": 5, "grace_period_days": 1 }, "macos_settings": { "custom_settings": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] } ] }, "apple_settings": { "configuration_profiles": [ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] }, { "path": "path/to/declaration.json", "labels": ["Label 1", "Label 2"] }, { "path": "path/to/assets/asset.json" } ], "assets": [ { "path": "path/to/assets/asset.json" } ], "managed_local_account_settings": { "enabled": true } }, "windows_settings": { "custom_settings": [ { "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } ], "configuration_profiles": [ { "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } ], "managed_local_account_settings": { "enabled": true } }, "macos_setup": { "bootstrap_package": "", "enable_end_user_authentication": false, "macos_setup_assistant": "path/to/config.json" }, "setup_experience": { "bootstrap_package": "", "enable_end_user_authentication": false, "apple_setup_assistant": "path/to/config.json" } }, "users": [ { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 1, "name": "Example User1", "email": "user1@example.com", "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "global_role": null, "api_only": false, "teams": null, "role": "admin" }, { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 17, "name": "Example User2", "email": "user2@example.com", "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "global_role": null, "api_only": false, "teams": null, "role": "observer" } ] } } ``` ### Update fleet-level agent options _Available in Fleet Premium_ `POST /api/v1/fleet/fleets/:id/agent_options` #### Parameters | Name | Type | In | Description | | --- | --- | --- | --- | | id | integer | path | **Required.** The desired fleet's ID. | | force | boolean | query | Force apply the options even if there are validation errors. | | dry_run | boolean | query | Validate the options and return any validation errors, but do not apply the changes. | | _JSON data_ | object | body | The JSON to use as agent options for this fleet. See [Agent options](https://fleetdm.com/docs/using-fleet/configuration-files#agent-options) for details. | #### Example `POST /api/v1/fleet/fleets/1/agent_options` ##### Request body ```json { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 20, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 60, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} } ``` ##### Default response `Status: 200` ```json { "team": { "name": "Workstations", "id": 1, "user_count": 4, "host_count": 8, "agent_options": { "config": { "options": { "pack_delimiter": "/", "logger_tls_period": 20, "distributed_plugin": "tls", "disable_distributed": false, "logger_tls_endpoint": "/api/v1/osquery/log", "distributed_interval": 60, "distributed_tls_max_attempts": 3 }, "decorators": { "load": [ "SELECT uuid AS host_uuid FROM system_info;", "SELECT hostname AS hostname FROM system_info;" ] } }, "overrides": {}, "command_line_flags": {} }, "webhook_settings": { "failing_policies_webhook": { "enable_failing_policies_webhook": false, "destination_url": "", "policy_ids": null, "host_batch_size": 0 } } } } ``` ### Delete fleet _Available in Fleet Premium_ `DELETE /api/v1/fleet/fleets/:id` #### Parameters | Name | Type | In | Description | | ---- | ------ | ---- | ------------------------------------ | | id | integer | path | **Required.** The desired fleet's ID. | #### Example `DELETE /api/v1/fleet/fleets/1` ##### Default response `Status: 200` --- ## Translator - [Translate IDs](#translate-ids) ### Translate IDs Transforms a host name into a host id. For example, the Fleet UI uses this endpoint when sending live reports to a set of hosts. `POST /api/v1/fleet/translate` #### Parameters | Name | Type | In | Description | | ----- | ----- | ---- | ---------------------------------------- | | array | array | body | **Required** list of items to translate. | #### Example `POST /api/v1/fleet/translate` ##### Request body ```json { "list": [ { "type": "user", "payload": { "identifier": "some@email.com" } }, { "type": "label", "payload": { "identifier": "labelA" } }, { "type": "team", "payload": { "identifier": "team1" } }, { "type": "host", "payload": { "identifier": "host-ABC" } } ] } ``` ##### Default response `Status: 200` ```json { "list": [ { "type": "user", "payload": { "identifier": "some@email.com", "id": 32 } }, { "type": "label", "payload": { "identifier": "labelA", "id": 1 } }, { "type": "team", "payload": { "identifier": "team1", "id": 22 } }, { "type": "host", "payload": { "identifier": "host-ABC", "id": 45 } } ] } ``` --- ## Users - [List users](#list-users) - [Create user](#create-user) - [Create user from invite](#create-user-from-invite) - [Get user](#get-user) - [Update user](#update-user) - [Delete user](#delete-user) - [Require password reset](#require-password-reset) - [List sessions](#list-sessions) - [Delete sessions](#delete-sessions) - [Invite user](#invite-user) - [List invites](#list-invites) - [Delete invite](#delete-invite) - [Verify invite](#verify-invite) - [Update invite](#update-invite) - [Create API-only user](#create-api-only-user) - [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions) The Fleet server exposes API endpoints that handles common user management operations, including managing emailed invites to new users. All of these endpoints require prior authentication, so you'll need to log in before calling any of the endpoints documented below. ### List users Returns a list of all enabled users `GET /api/v1/fleet/users` #### Parameters | Name | Type | In | Description | | --------------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | query | string | query | Search query keywords. Searchable fields include `name` and `email`. | | order_key | string | query | What to order results by. Can be any column in the users table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | page | integer | query | Page number of the results to fetch. | | query | string | query | Search query keywords. Searchable fields include `name` and `email`. | | per_page | integer | query | Results per page. | | fleet_id | integer | query | _Available in Fleet Premium_. Filters the users to only include users in the specified fleet. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/users` ##### Request query parameters None. ##### Default response `Status: 200` ```json { "users": [ { "created_at": "2020-12-10T03:52:53Z", "updated_at": "2020-12-10T03:52:53Z", "id": 1, "name": "Jane Doe", "email": "janedoe@example.com", "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "global_role": null, "api_only": false, "fleets": [ { "id": 1, "created_at": "0001-01-01T00:00:00Z", "name": "workstations", "description": "", "role": "admin" } ] } ] } ``` ##### Failed authentication `Status: 401 Authentication Failed` ```json { "message": "Authentication Failed", "errors": [ { "name": "base", "reason": "Authentication failed" } ] } ``` ### Create user Creates a user account without requiring an invitation, the user is enabled immediately. By default, the user will be forced to reset its password upon first login. `POST /api/v1/fleet/users/admin` #### Parameters | Name | Type | In | Description | | ----------- | ------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | email | string | body | **Required**. The user's email address. | | name | string | body | **Required**. The user's full name or nickname. | | password | string | body | The user's password (**required** for API only and non-SSO users). | | sso_enabled | boolean | body | Whether or not SSO is enabled for the user. | | mfa_enabled | boolean | body | _Available in Fleet Premium._ Whether or not the user must click a magic link emailed to them to log in, after they successfully enter their username and password. Incompatible with SSO and API-only users. | | api_only | boolean | body | User is an "API-only" user (cannot use web UI) if true. | | global_role | string | body | The role assigned to the user. If `global_role` is specified, `fleets` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | | admin_forced_password_reset | boolean | body | Sets whether the user will be forced to reset its password upon first login (default=true) | | fleets | array | body | _Available in Fleet Premium_. The fleets and respective roles assigned to the user. Should contain an array of objects in which each object includes the fleet's `id` and the user's `role` on each fleet. If `fleets` is specified, `global_role` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | #### Example `POST /api/v1/fleet/users/admin` ##### Request body ```json { "name": "Jane Doe", "email": "janedoe@example.com", "password": "test-123", "api_only": true, "fleets": [ { "id": 2, "role": "observer" }, { "id": 3, "role": "maintainer" } ] } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 5, "name": "Jane Doe", "email": "janedoe@example.com", "enabled": true, "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "api_only": true, "global_role": null, "fleets": [ { "id": 2, "role": "observer" }, { "id": 3, "role": "maintainer" } ] }, "token": "{API key}" } ``` > Note: The new user's `token` (API key) is only included in the response after creating an api-only user (`api_only: true`). ##### User doesn't exist `Status: 404 Resource Not Found` ```json { "message": "Resource Not Found", "errors": [ { "name": "base", "reason": "User with id=1 was not found in the datastore" } ] } ``` ### Create user from invite Creates a user account after an invited user provides registration information and submits the form. `POST /api/v1/fleet/users` #### Parameters | Name | Type | In | Description | | --------------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | email | string | body | **Required**. The email address of the user. | | invite_token | string | body | **Required**. Token provided to the user in the invitation email. | | name | string | body | **Required**. The name of the user. | | password | string | body | The password chosen by the user (if not SSO user). | | password_confirmation | string | body | Confirmation of the password chosen by the user. | #### Example `POST /api/v1/fleet/users` ##### Request query parameters ```json { "email": "janedoe@example.com", "invite_token": "SjdReDNuZW5jd3dCbTJtQTQ5WjJTc2txWWlEcGpiM3c=", "name": "janedoe", "password": "test-123", "password_confirmation": "test-123" } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 2, "name": "janedoe", "email": "janedoe@example.com", "enabled": true, "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "global_role": "admin", "fleets": [] } } ``` ##### Failed authentication `Status: 401 Authentication Failed` ```json { "message": "Authentication Failed", "errors": [ { "name": "base", "reason": "Authentication failed" } ] } ``` ##### Expired or used invite code `Status: 404 Resource Not Found` ```json { "message": "Resource Not Found", "errors": [ { "name": "base", "reason": "Invite with token SjdReDNuZW5jd3dCbTJtQTQ5WjJTc2txWWlEcGpiM3c= was not found in the datastore" } ] } ``` ##### Validation failed `Status: 422 Validation Failed` The same error will be returned whenever one of the required parameters fails the validation. ```json { "message": "Validation Failed", "errors": [ { "name": "name", "reason": "cannot be empty" } ] } ``` ### Get user Returns all information about a specific user. `GET /api/v1/fleet/users/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The user's id. | #### Example `GET /api/v1/fleet/users/2` ##### Default response `Status: 200` ```json { "user": { "created_at": "2020-12-10T05:20:25Z", "updated_at": "2020-12-10T05:24:27Z", "id": 2, "name": "Jane Doe", "email": "janedoe@example.com", "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "global_role": "admin", "api_only": false, "fleets": [] } } ``` ##### User doesn't exist `Status: 404 Resource Not Found` ```json { "message": "Resource Not Found", "errors": [ { "name": "base", "reason": "User with id=5 was not found in the datastore" } ] } ``` ### Update user `PATCH /api/v1/fleet/users/:id` #### Parameters | Name | Type | In | Description | | ----------- | ------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | integer | path | **Required**. The user's id. | | name | string | body | The user's name. | | position | string | body | The user's position. | | email | string | body | The user's email. | | sso_enabled | boolean | body | Whether or not SSO is enabled for the user. | | mfa_enabled | boolean | body | _Available in Fleet Premium._ Whether or not the user must click a magic link emailed to them to log in, after they successfully enter their username and password. Incompatible with SSO and API-only users. | | api_only | boolean | body | User is an "API-only" user (cannot use web UI) if true. | | password | string | body | The user's current password, required to change the user's own email or password (not required for an admin to modify another user). | | new_password| string | body | The user's new password. | | global_role | string | body | The role assigned to the user. If `global_role` is specified, `fleets` cannot be specified. | | fleets | array | body | _Available in Fleet Premium_. The fleets and respective roles assigned to the user. Should contain an array of objects in which each object includes the fleet's `id` and the user's `role` on each fleet. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). If `fleets` is specified, `global_role` cannot be specified. | #### Example `PATCH /api/v1/fleet/users/2` ##### Request body ```json { "name": "Jane Doe", "global_role": "admin" } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "2021-02-03T16:11:06Z", "updated_at": "2021-02-03T16:11:06Z", "id": 2, "name": "Jane Doe", "email": "janedoe@example.com", "global_role": "admin", "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "api_only": false, "fleets": [] } } ``` #### Example (modify a user's fleets) `PATCH /api/v1/fleet/users/2` ##### Request body ```json { "fleets": [ { "id": 1, "role": "observer" }, { "id": 2, "role": "maintainer" } ] } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "2021-02-03T16:11:06Z", "updated_at": "2021-02-03T16:11:06Z", "id": 2, "name": "Jane Doe", "email": "janedoe@example.com", "enabled": true, "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "global_role": "admin", "fleets": [ { "id": 2, "role": "observer" }, { "id": 3, "role": "maintainer" } ] } } ``` ### Delete user Delete the specified user from Fleet. `DELETE /api/v1/fleet/users/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required**. The user's id. | #### Example `DELETE /api/v1/fleet/users/3` ##### Default response `Status: 200` ### Require password reset The selected user is logged out of Fleet and required to reset their password during the next attempt to log in. This also revokes all active Fleet API tokens for this user. Returns the user object. `POST /api/v1/fleet/users/:id/require_password_reset` #### Parameters | Name | Type | In | Description | | ----- | ------- | ---- | ---------------------------------------------------------------------------------------------- | | id | integer | path | **Required**. The user's id. | | require | boolean | body | Whether or not the user is required to reset their password during the next attempt to log in. | #### Example `POST /api/v1/fleet/users/123/require_password_reset` ##### Request body ```json { "require": true } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "2021-02-23T22:23:34Z", "updated_at": "2021-02-23T22:28:52Z", "id": 2, "name": "Jane Doe", "email": "janedoe@example.com", "force_password_reset": true, "gravatar_url": "", "mfa_enabled": false, "sso_enabled": false, "global_role": "observer", "fleets": [] } } ``` ### List sessions Returns a list of the user's sessions in Fleet. `GET /api/v1/fleet/users/:id/sessions` #### Parameters None. #### Example `GET /api/v1/fleet/users/1/sessions` ##### Default response `Status: 200` ```json { "sessions": [ { "session_id": 2, "user_id": 1, "created_at": "2021-02-03T16:12:50Z" }, { "session_id": 3, "user_id": 1, "created_at": "2021-02-09T23:40:23Z" }, { "session_id": 6, "user_id": 1, "created_at": "2021-02-23T22:23:58Z" } ] } ``` ### Delete sessions Deletes the selected user's sessions in Fleet. Also deletes the user's API token. `DELETE /api/v1/fleet/users/:id/sessions` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ----------------------------------------- | | id | integer | path | **Required**. The ID of the desired user. | #### Example `DELETE /api/v1/fleet/users/1/sessions` ##### Default response `Status: 200` ### Invite user `POST /api/v1/fleet/invites` #### Parameters | Name | Type | In | Description | | ----------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | global_role | string | body | Role the user will be granted. Either a global role is needed, or a fleet role. | | email | string | body | **Required.** The email of the invited user. This email will receive the invitation link. | | name | string | body | **Required.** The name of the invited user. | | sso_enabled | boolean | body | **Required.** Whether or not SSO will be enabled for the invited user. | | mfa_enabled | boolean | body | _Available in Fleet Premium._ Whether or not the invited user must click a magic link emailed to them to log in, after they successfully enter their username and password. Users can have SSO or MFA enabled, but not both. | | fleets | array | body | _Available in Fleet Premium_. A list of the fleets the user is a member of. Each item includes the fleet's ID and the user's role in the specified fleet. | #### Example `POST /api/v1/fleet/invites` ##### Request body ```json { "email": "john_appleseed@example.com", "name": "John", "sso_enabled": false, "mfa_enabled": false, "global_role": null, "fleets": [ { "id": 2, "role": "observer" }, { "id": 3, "role": "maintainer" } ] } ``` ##### Default response `Status: 200` ```json { "invite": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 3, "invited_by": 1, "email": "john_appleseed@example.com", "name": "John", "sso_enabled": false, "mfa_enabled": false, "fleets": [ { "id": 10, "created_at": "0001-01-01T00:00:00Z", "name": "Apples", "description": "", "agent_options": null, "user_count": 0, "host_count": 0, "role": "observer" }, { "id": 14, "created_at": "0001-01-01T00:00:00Z", "name": "Best of the Best Engineering", "description": "", "agent_options": null, "user_count": 0, "host_count": 0, "role": "maintainer" } ] } } ``` ### List invites Returns a list of the active invitations in Fleet. `GET /api/v1/fleet/invites` #### Parameters | Name | Type | In | Description | | --------------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | order_key | string | query | What to order results by. Can be any column in the invites table. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | query | string | query | Search query keywords. Searchable fields include `name` and `email`. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/invites` ##### Default response `Status: 200` ```json { "invites": [ { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 3, "email": "john_appleseed@example.com", "name": "John", "sso_enabled": false, "mfa_enabled": false, "global_role": "admin", "fleets": [] }, { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 4, "email": "bob_marks@example.com", "name": "Bob", "sso_enabled": false, "mfa_enabled": false, "global_role": "admin", "fleets": [] } ] } ``` ### Delete invite Delete the specified invite from Fleet. `DELETE /api/v1/fleet/invites/:id` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | ---------------------------- | | id | integer | path | **Required.** The user's id. | #### Example `DELETE /api/v1/fleet/invites/123` ##### Default response `Status: 200` ### Verify invite Verify the specified invite. `GET /api/v1/fleet/invites/:token` #### Parameters | Name | Type | In | Description | | ----- | -------| ---- | -------------------------------------- | | token | string | path | **Required.** The user's invite token. | #### Example `GET /api/v1/fleet/invites/abcdef012456789` ##### Default response `Status: 200` ```json { "invite": { "created_at": "2021-01-15T00:58:33Z", "updated_at": "2021-01-15T00:58:33Z", "id": 4, "email": "steve@example.com", "name": "Steve", "sso_enabled": false, "mfa_enabled": false, "global_role": "admin", "fleets": [] } } ``` ##### Not found `Status: 404` ```json { "message": "Resource Not Found", "errors": [ { "name": "base", "reason": "Invite with token was not found in the datastore" } ] } ``` ### Update invite `PATCH /api/v1/fleet/invites/:id` #### Parameters | Name | Type | In | Description | | ----------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | global_role | string | body | Role the user will be granted. Either a global role is needed, or a fleet role. | | email | string | body | The email of the invited user. Updates on the email won't resend the invitation. | | name | string | body | The name of the invited user. | | sso_enabled | boolean | body | Whether or not SSO will be enabled for the invited user. | | mfa_enabled | boolean | body | _Available in Fleet Premium._ Whether or not the invited user must click a magic link emailed to them to log in, after they successfully enter their username and password. Users can have SSO or MFA enabled, but not both. | | fleets | array | body | _Available in Fleet Premium_. A list of the fleets the user is a member of. Each item includes the fleet's ID and the user's role in the specified fleet. | #### Example `PATCH /api/v1/fleet/invites/123` ##### Request body ```json { "email": "john_appleseed@example.com", "name": "John", "sso_enabled": false, "mfa_enabled": false, "global_role": null, "fleets": [ { "id": 2, "role": "observer" }, { "id": 3, "role": "maintainer" } ] } ``` ##### Default response `Status: 200` ```json { "invite": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 3, "invited_by": 1, "email": "john_appleseed@example.com", "name": "John", "sso_enabled": false, "mfa_enabled": false, "fleets": [ { "id": 10, "created_at": "0001-01-01T00:00:00Z", "name": "Apples", "description": "", "agent_options": null, "user_count": 0, "host_count": 0, "role": "observer" }, { "id": 14, "created_at": "0001-01-01T00:00:00Z", "name": "Best of the Best Engineering", "description": "", "agent_options": null, "user_count": 0, "host_count": 0, "role": "maintainer" } ] } } ``` ### Create API-only user Creates an API-only user that does not have access to the UI. `POST /api/v1/fleet/users/api_only` | Name | Type | In | Description | | :---------------------- | :------ | :---- | :---------- | | name | string | body | The display name for the API-only user. | | global_role | string | body | The role assigned to the user. If `global_role` is specified, `fleets` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | | fleets | array | body | _Available in Fleet Premium_. The fleets and respective roles assigned to the user. Should contain an array of objects in which each object includes the fleet's `id` and the user's `role` on each fleet. If `fleets` is specified, `global_role` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | | api_endpoints | array | body | _Available in Fleet Premium_. A list of `id`s of API endpoints this user will have access to. For available endpoints, see [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions). | If `api_endpoints` is specified, these do not grant additional permissions otherwise forbidden by the user's `role`. #### Example `POST /api/v1/fleet/users/api_only` ##### Request body ```json { "name": "Jane Doe", "fleets": [ { "id": 2, "role": "observer" }, { "id": 3, "role": "maintainer" } ], "api_endpoints": [1,5,7,32] } ``` ##### Default response `Status: 200` ```json { "user": { "created_at": "0001-01-01T00:00:00Z", "updated_at": "0001-01-01T00:00:00Z", "id": 5, "name": "Jane Doe", "email": "janedoe+randomlygeneratedstring@example.com", "enabled": true, "force_password_reset": false, "gravatar_url": "", "sso_enabled": false, "mfa_enabled": false, "api_only": true, "global_role": null, "fleets": [ { "id": 2, "role": "observer" }, { "id": 3, "role": "maintainer" } ], "api_endpoints": [1,5,7,32] }, "token": "{API key}" } ``` ### List API endpoints for API-only user permissions _Available in Fleet Premium._ Lists Fleet REST API endpoints that an API-only user can be granted access to. `GET /api/v1/fleet/rest_api` | Name | Type | In | Description | | :---------------------- | :------ | :---- | :---------- | | query | string | query | Search query keywords. Searchable fields include `display_name` and `path`. | Searching by path ignores the naming of path parameters that are specified with `:` , e.g. `:id`. So searching `/hosts/:id/report` is the same as searching `/hosts/:host_id/report`. Experimental endpoints are excluded from the results, since they are not for use in automated workflows. #### Example `GET /api/v1/fleet/rest_api?query=get%20host%20by%20identifier` or `GET /api/v1/fleet/rest_api?query=%2Fapi%2Fv1%2Ffleet%2Fhosts%2Fidentifier%2F%3Ahost_identifier` ##### Default response `Status: 200` ```json { "api_endpoints": [ { "id": 123, "display_name": "Get host by identifier", "method": "GET", "path": "/api/v1/fleet/hosts/identifier/:identifier", "deprecated": false } ], "meta": { "has_next_results": true, "has_previous_results": false }, "count": 1 } ``` --- ## Debug - [Get errors](#get-errors) - [Get database information](#get-database-information) - [Get profiling information](#get-profiling-information) - [Get trace sampling settings](#get-trace-sampling-settings) - [Adjust trace sampling](#adjust-trace-sampling) The Fleet server exposes a handful of API endpoints to retrieve debug information about the server itself in order to help troubleshooting. All the following endpoints require prior authentication meaning you must first log in successfully before calling any of the endpoints documented below. ### Get errors Returns a set of all the errors that happened in the server during the interval of time defined by the [logging_error_retention_period](https://fleetdm.com/docs/deploying/configuration#logging-error-retention-period) configuration. The server only stores and returns a single instance of each error. `GET /debug/errors` #### Parameters | Name | Type | In | Description | | ----- | ------- | ----- | --------------------------------------------------------------------------------- | | flush | boolean | query | Whether or not clear the errors from Redis after reading them. Default is `false` | #### Example `GET /debug/errors?flush=true` ##### Default response `Status: 200` ```json [ { "count": "3", "chain": [ { "message": "Authorization header required" }, { "message": "missing FleetError in chain", "data": { "timestamp": "2022-06-03T14:16:01-03:00" }, "stack": [ "github.com/fleetdm/fleet/v4/server/contexts/ctxerr.Handle (ctxerr.go:262)", "github.com/fleetdm/fleet/v4/server/service.encodeError (transport_error.go:80)", "github.com/go-kit/kit/transport/http.Server.ServeHTTP (server.go:124)" ] } ] } ] ``` ### Get database information Returns information about the current state of the database; valid keys are: - `locks`: returns transaction locking information. - `innodb-status`: returns InnoDB status information. - `process-list`: returns running processes (queries, etc). `GET /debug/db/:key` #### Parameters None. #### Example `GET /debug/db/process-list` ##### Default response `Status: 200` ```json [ { "id": 1234, "user": "fleet", "host": "10.0.0.5:52014", "db": "fleet", "command": "Query", "time": 0, "state": "executing", "info": "SELECT * FROM hosts" } ] ``` > The response shape depends on the requested `key`. `locks` returns a list of objects with `waiting_trx_id`, `waiting_thread`, `waiting_query`, `blocking_trx_id`, `blocking_thread`, and `blocking_query`. `innodb-status` returns a JSON string containing the raw `SHOW ENGINE INNODB STATUS` output. `process-list` returns a list of objects as shown above. ### Get profiling information Returns runtime profiling data of the server in the format expected by `go tools pprof`. The responses are equivalent to those returned by the Go `http/pprof` package. Valid keys are: `cmdline`, `profile`, `symbol` and `trace`. `GET /debug/pprof/:key` #### Parameters None. #### Example `GET /debug/pprof/cmdline` ##### Default response `Status: 200` The response body is the same as the Go [`net/http/pprof`](https://pkg.go.dev/net/http/pprof) package returns for the given `key`: plain text for `cmdline` and `symbol`, and a binary pprof profile for `profile` and `trace`. ### Get trace sampling settings Returns the current [trace sampling](https://fleetdm.com/docs/deploy/reference-architectures#sampling) settings. Only has effect when tracing is enabled (see [logging_tracing_enabled](https://fleetdm.com/docs/configuration/fleet-server-configuration#logging-tracing-enabled)). Requires a global admin. `GET /debug/trace_sampler` #### Parameters None. #### Example `GET /debug/trace_sampler` ##### Default response `Status: 200` ```json { "high_volume_ratio": 0.001, "standard_ratio": 0.02, "force_full": false, "updated_at": "2026-06-01T00:00:00Z" } ``` ### Adjust trace sampling Updates one or more [trace sampling](https://fleetdm.com/docs/deploy/reference-architectures#sampling) settings at runtime, without restarting the server. Only the fields included in the request body are changed. Each Fleet server polls for changes about once a minute, so an update applies across all servers within roughly a minute. Requires a global admin. `PATCH /debug/trace_sampler` #### Parameters | Name | Type | In | Description | | ----------------- | ------- | ---- | -------------------------------------------------------------------------------------------------------------------- | | high_volume_ratio | float | body | Sample rate for high-volume agent routes, between 0 and 1 (inclusive). | | standard_ratio | float | body | Sample rate for standard admin/read routes, between 0 and 1 (inclusive). | | force_full | boolean | body | When `true`, sample every route at 100% (except never-sampled infrastructure paths), ignoring the ratios above. | At least one field is required. Ratios outside the `[0, 1]` range are rejected. #### Example `PATCH /debug/trace_sampler` ##### Request body ```json { "force_full": true } ``` ##### Default response `Status: 200` ```json { "high_volume_ratio": 0.001, "standard_ratio": 0.02, "force_full": true } ``` ## Custom variables - [List custom variables](#list-custom-variables) - [Create custom variable](#create-custom-variable) - [Delete custom variable](#delete-custom-variable) ### List custom variables Lists all custom variables that can be used in scripts, configuration profiles, and host name templates prefixed with `$FLEET_SECRET_`. `GET /api/v1/fleet/custom_variables` #### Parameters | Name | Type | In | Description | |:--------------- |:------- |:----- |:------------------------------------------------------------| | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `name`, `id`, and `updated_at`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/custom_variables` ##### Default response `Status: 200` ```json { "custom_variables": [ { "id": 123, "name": "SOME_API_TOKEN", "created_at": "2020-11-13T22:57:12Z", "updated_at": "2020-11-13T22:57:12Z" } ], "meta": { "has_next_results": false, "has_previous_results": false }, "count": 1 } ``` ### Create custom variable Creates a custom variable that can be used in scripts, configuration profiles, and host name templates prefixed with `$FLEET_SECRET_`. `POST /api/v1/fleet/custom_variables` #### Parameters | Name | Type | In | Description | |:--------------- |:------- |:----- |:------------------------------------------------------------| | name | string | body | **Required.** The desired variable name, without the `FLEET_SECRET_` prefix. | | value | string | body | **Required.** The value for the custom variable. | #### Example `POST /api/v1/fleet/custom_variables` ##### Request body ```json { "name": "SOME_API_TOKEN", "value": "971ef02b93c74ca9b22b694a9251f1d6" } ``` ##### Default response `Status: 200` ```json { "id": 123, "name": "SOME_API_TOKEN" } ``` ### Delete custom variable Removes a custom variable from Fleet. `DELETE /api/v1/fleet/custom_variables/:id` #### Example `DELETE /api/v1/fleet/custom_variables/123` ##### Default response `Status: 200` ## Custom host vitals - [List custom host vitals](#list-custom-host-vitals) - [Create custom host vital](#create-custom-host-vital) - [Update custom host vital](#update-custom-host-vital) - [Delete custom host vital](#delete-custom-host-vital) - [Update host's custom host vital value](#update-hosts-custom-host-vital-value) - [Replace all custom host vitals](#replace-all-custom-host-vitals) ### List custom host vitals Lists all [custom host vitals](https://fleetdm.com/guides/custom-host-vitals), which can be referenced as `$FLEET_HOST_VITAL_` in scripts and configuration profiles, or as `custom_host_vital_id` in a Host vitals label's [`criteria`](#criteria). `GET /api/v1/fleet/custom_host_vitals` #### Parameters | Name | Type | In | Description | |:--------------- |:------- |:----- |:------------------------------------------------------------| | query | string | query | Search query. Matches against the vital's name or its `$FLEET_HOST_VITAL_` variable. | | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Allowed fields are `name`, `id`, and `updated_at`. Default is `name`. | | order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. | | after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. | #### Example `GET /api/v1/fleet/custom_host_vitals` ##### Default response `Status: 200` ```json { "custom_host_vitals": [ { "id": 1, "name": "Asset tag", "created_at": "2026-06-04T15:22:36Z", "updated_at": "2026-06-04T15:22:36Z" } ], "meta": { "has_next_results": false, "has_previous_results": false }, "count": 1 } ``` ### Create custom host vital Creates a custom host vital. `POST /api/v1/fleet/custom_host_vitals` #### Parameters | Name | Type | In | Description | |:---- |:------ |:---- |:--------------------------------------------| | name | string | body | **Required.** The vital's name, without the `FLEET_HOST_VITAL_` prefix. Must be unique across all custom host vitals (case-insensitive), and 255 characters or fewer. | Fails with a `409` if a custom host vital with this name already exists. #### Example `POST /api/v1/fleet/custom_host_vitals` ##### Request body ```json { "name": "Asset tag" } ``` ##### Default response `Status: 200` ```json { "custom_host_vital": { "id": 1, "name": "Asset tag", "created_at": "2026-06-04T15:22:36Z", "updated_at": "2026-06-04T15:22:36Z" } } ``` ### Update custom host vital Renames a custom host vital. The vital's ID, its `$FLEET_HOST_VITAL_` variable, and any host values already set for it, are unaffected. `PATCH /api/v1/fleet/custom_host_vitals/:id` #### Parameters | Name | Type | In | Description | |:---- |:------- |:---- |:----------------------------------------| | id | integer | path | **Required.** The custom host vital's ID. | | name | string | body | **Required.** The vital's new name. | Fails with a `409` if another custom host vital already has this name. #### Example `PATCH /api/v1/fleet/custom_host_vitals/1` ##### Request body ```json { "name": "Asset tag number" } ``` ##### Default response `Status: 200` ```json { "custom_host_vital": { "id": 1, "name": "Asset tag number", "created_at": "2026-06-04T15:22:36Z", "updated_at": "2026-06-05T09:03:11Z" } } ``` ### Delete custom host vital Deletes a custom host vital, along with any per-host values set for it. `DELETE /api/v1/fleet/custom_host_vitals/:id` #### Parameters | Name | Type | In | Description | |:---- |:------- |:---- |:----------------------------------------| | id | integer | path | **Required.** The custom host vital's ID. | Fails with a `409` if the vital is still referenced by a script, configuration profile, or Host vitals label. Remove the reference first. #### Example `DELETE /api/v1/fleet/custom_host_vitals/1` ##### Default response `Status: 200` ### Update host's custom host vital value Sets a host's value for a custom host vital. `PUT /api/v1/fleet/hosts/:host_id/custom_host_vitals/:id` #### Parameters | Name | Type | In | Description | |:------- |:------- |:---- |:---------------------------------------------------| | host_id | integer | path | **Required.** The host's ID. | | id | integer | path | **Required.** The custom host vital's ID. | | value | string | body | **Required.** The value to set for this host. | #### Example `PUT /api/v1/fleet/hosts/123/custom_host_vitals/1` ##### Request body ```json { "value": "C02XL0Zerato" } ``` ##### Default response `Status: 200` ### Replace all custom host vitals Replaces all existing custom host vital definitions with the provided list. Existing vitals not included in the list are deleted, which fails if one of them is still referenced by a script, configuration profile, or Host vitals label. `PUT /api/v1/fleet/spec/custom_host_vitals` #### Parameters | Name | Type | In | Description | |:------------------ |:------- |:---- |:---------------------------------------------------| | custom_host_vitals | array | body | The full list of custom host vitals. Each item is an object with a `name`. | | dry_run | boolean | body | If `true`, validates the request without applying changes. Default is `false`. | > Omitting `custom_host_vitals` from the request, or sending an empty list, deletes every existing custom host vital. This is the endpoint `fleetctl gitops` uses to apply the `custom_host_vitals:` key in `default.yml`. #### Example `PUT /api/v1/fleet/spec/custom_host_vitals` ##### Request body ```json { "custom_host_vitals": [ { "name": "Asset tag" }, { "name": "Function" }, { "name": "ITAM device ID" } ] } ``` ##### Default response `Status: 200` ## API errors Fleet returns API errors as a JSON document with the following fields: - `message`: This field contains the kind of error (bad request error, authorization error, etc.). - `errors`: List of errors with `name` and `reason` keys. - `uuid`: Unique identifier for the error. This identifier can be matched to Fleet logs which might contain more information about the cause of the error. Sample of an error when trying to send an empty body on a request that expects a JSON body: ```sh $ curl -k -H "Authorization: Bearer $TOKEN" -H 'Content-Type:application/json' "https://localhost:8080/api/v1/fleet/sso" -d '' ``` Response: ```json { "message": "Bad request", "errors": [ { "name": "base", "reason": "Expected JSON Body" } ], "uuid": "c0532a64-bec2-4cf9-aa37-96fe47ead814" } ``` ---