From 2d0b6ae1d1c6965e9b8715a3fc96ea52da7a652e Mon Sep 17 00:00:00 2001 From: Victor Lyuboslavsky <2685025+getvictor@users.noreply.github.com> Date: Wed, 29 Apr 2026 10:41:29 -0500 Subject: [PATCH 1/4] Deprecate unscoped `host_identifier` calls in /commands REST API, update example response, and emphasize required parameter for new integrations. --- docs/REST API/rest-api.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 1996aa8d1ea..47306559cae 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -7689,7 +7689,7 @@ This endpoint returns the list of custom MDM commands that have been executed. | per_page | integer | query | Results per page. Default is `10`. | | order_key | string | query | What to order results by. Can be any field listed in the `results` array example below. 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"`. | -| host_identifier | string | query | The host's `hostname`, `uuid`, or `hardware_serial`. Returns only commands that target the specified host. | +| host_identifier | string | query | **Required for new integrations.** 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) and will be rejected in a future Fleet release. | | 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. | @@ -7699,10 +7699,12 @@ This endpoint returns the list of custom MDM commands that have been executed. > 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. +> +> **Deprecated:** calling this endpoint without `host_identifier` is deprecated and will be required in a future Fleet release. Always provide `host_identifier` to scope the response to a single host. Unscoped calls 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. New integrations must pass `host_identifier`. #### Example -`GET /api/v1/fleet/commands?per_page=5` +`GET /api/v1/fleet/commands?host_identifier=A1B2C3D4-E5F6-7890-1234-567890ABCDEF&per_page=5` ##### Default response @@ -7710,27 +7712,31 @@ This endpoint returns the list of custom MDM commands that have been executed. ```json { + "meta": { + "has_next_results": true, + "has_previous_results": false + }, "count": null, "results": [ { - "host_uuid": "145cafeb-87c7-4869-84d5-e4118a927746", - "command_uuid": "a2064cef-0000-1234-afb9-283e3c1d487e", + "host_uuid": "A1B2C3D4-E5F6-7890-1234-567890ABCDEF", + "command_uuid": "a3650ec9-6dd0-40e9-b5d8-feffe9939461", "status": "Acknowledged", "command_status": "ran", - "updated_at": "2023-04-04:00:00Z", - "request_type": "ProfileList", + "updated_at": "2026-03-20T19:45:27Z", + "request_type": "DeclarativeManagement", "name": null, - "hostname": "mycomputer" + "hostname": "Mac-mini.local" }, { - "host_uuid": "322vghee-12c7-8976-83a1-e2118a927342", - "command_uuid": "d76d69b7-d806-45a9-8e49-9d6dc533485c", - "status": "200", - "command_status": "ran", - "updated_at": "2023-05-04:00:00Z", - "request_type": "./Device/Vendor/MSFT/Reboot/RebootNow", + "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": "myhost" + "hostname": "Mac-mini.local" } ] } From 4090dc50071f123b6a5047e48148ad6b32cdcc68 Mon Sep 17 00:00:00 2001 From: Marko Lisica <83164494+marko-lisica@users.noreply.github.com> Date: Fri, 1 May 2026 18:42:07 +0200 Subject: [PATCH 2/4] added new endpoint to get host's mdm command --- docs/REST API/rest-api.md | 71 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 47306559cae..9612dbdbf8a 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -2934,6 +2934,7 @@ None. - [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) +- [Get host's MDM commands](#get-hosts-mdm-commands) - [Lock host](#lock-host) - [Unlock host](#unlock-host) - [Wipe host](#wipe-host) @@ -5172,6 +5173,71 @@ Retrieves the certificates installed on a host. } ``` +### Get host's MDM commands + +This endpoint returns the upcoming and past MDM commands for the host. + +`GET /api/v1/fleet/hosts/:id/mdm_commands` + +#### Parameters + +| Name | Type | In | Description | +| ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | +| id | string | path | **Required for new integrations.** 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) and will be rejected in a future Fleet release. | +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. Default is `10`. | +| order_key | string | query | What to order results by. Can be any field listed in the `results` array example below. 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`. + + +#### Example + +`GET /api/v1/fleet/hosts/123/mdm_commands` + +##### 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" + } + ] +} +``` + + ### Get host's OS settings (configuration profile) Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup). @@ -7675,6 +7741,8 @@ Example VPP `InstallApplication` command result metadata: ### List MDM commands +> This API endpoint is **deprecated** as of Fleet 4.86. It is maintained for backward compatibility. Please use the [Get host's MDM commands](#get-hosts-mdm-commands) endpoint instead. + > `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. @@ -7694,13 +7762,14 @@ This endpoint returns the list of custom MDM commands that have been executed. | 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. | +> **Warning:** Calling this endpoint without ⁠`host_identifier` is **not recommended**. The underlying query is not performant at scale and may time out. + > 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. > -> **Deprecated:** calling this endpoint without `host_identifier` is deprecated and will be required in a future Fleet release. Always provide `host_identifier` to scope the response to a single host. Unscoped calls 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. New integrations must pass `host_identifier`. #### Example From 062de470979b23c62d9fa956ec645139572750cd Mon Sep 17 00:00:00 2001 From: Victor Lyuboslavsky <2685025+getvictor@users.noreply.github.com> Date: Thu, 14 May 2026 09:13:31 -0500 Subject: [PATCH 3/4] Revert "added new endpoint to get host's mdm command" This reverts commit 4090dc50071f123b6a5047e48148ad6b32cdcc68. --- docs/REST API/rest-api.md | 71 +-------------------------------------- 1 file changed, 1 insertion(+), 70 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 9612dbdbf8a..47306559cae 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -2934,7 +2934,6 @@ None. - [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) -- [Get host's MDM commands](#get-hosts-mdm-commands) - [Lock host](#lock-host) - [Unlock host](#unlock-host) - [Wipe host](#wipe-host) @@ -5173,71 +5172,6 @@ Retrieves the certificates installed on a host. } ``` -### Get host's MDM commands - -This endpoint returns the upcoming and past MDM commands for the host. - -`GET /api/v1/fleet/hosts/:id/mdm_commands` - -#### Parameters - -| Name | Type | In | Description | -| ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | -| id | string | path | **Required for new integrations.** 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) and will be rejected in a future Fleet release. | -| page | integer | query | Page number of the results to fetch. | -| per_page | integer | query | Results per page. Default is `10`. | -| order_key | string | query | What to order results by. Can be any field listed in the `results` array example below. 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`. - - -#### Example - -`GET /api/v1/fleet/hosts/123/mdm_commands` - -##### 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" - } - ] -} -``` - - ### Get host's OS settings (configuration profile) Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup). @@ -7741,8 +7675,6 @@ Example VPP `InstallApplication` command result metadata: ### List MDM commands -> This API endpoint is **deprecated** as of Fleet 4.86. It is maintained for backward compatibility. Please use the [Get host's MDM commands](#get-hosts-mdm-commands) endpoint instead. - > `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. @@ -7762,14 +7694,13 @@ This endpoint returns the list of custom MDM commands that have been executed. | 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. | -> **Warning:** Calling this endpoint without ⁠`host_identifier` is **not recommended**. The underlying query is not performant at scale and may time out. - > 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. > +> **Deprecated:** calling this endpoint without `host_identifier` is deprecated and will be required in a future Fleet release. Always provide `host_identifier` to scope the response to a single host. Unscoped calls 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. New integrations must pass `host_identifier`. #### Example From 0c467cab93a32158a369f7de4b8a427a6fea5661 Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Fri, 15 May 2026 09:12:47 -0400 Subject: [PATCH 4/4] Update rest-api.md --- docs/REST API/rest-api.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 47306559cae..838dab62d75 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -7685,11 +7685,11 @@ This endpoint returns the list of custom MDM commands that have been executed. | 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. | | per_page | integer | query | Results per page. Default is `10`. | | order_key | string | query | What to order results by. Can be any field listed in the `results` array example below. 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"`. | -| host_identifier | string | query | **Required for new integrations.** 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) and will be rejected in a future Fleet release. | | 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. | @@ -7699,8 +7699,6 @@ This endpoint returns the list of custom MDM commands that have been executed. > 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. -> -> **Deprecated:** calling this endpoint without `host_identifier` is deprecated and will be required in a future Fleet release. Always provide `host_identifier` to scope the response to a single host. Unscoped calls 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. New integrations must pass `host_identifier`. #### Example