Deprecate using `GET /api/v1/fleet/commands` w/o host_identifier by getvictor · Pull Request #44392 · fleetdm/fleet

getvictor · 2026-04-29T15:42:30Z

Related issue: Resolves #44170

Immediately deprecate unscoped calls to this endpoint as discussed in 2026/04/29 g-power-to-pc standup.

…ate example response, and emphasize required parameter for new integrations.

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

qodo-code-review · 2026-04-29T15:43:13Z

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

Copilot

Copilot wasn't able to review any files in this pull request.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

getvictor · 2026-04-29T15:43:33Z

@marko-lisica as discussed in standup

marko-lisica · 2026-04-30T08:17:36Z

 >
 > 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`.


Suggested change

> **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`.

> **Deprecated:** This endpoint will be replaced in the next major release. Calling this endpoint without ⁠`host_identifier` is **not recommended**. The underlying query is not performant at scale and may time out.

getvictor · 2026-04-30T12:51:18Z

@marko-lisica Why can't we just call it deprecated? Simply calling it deprecated doesn't break backward compatibility, and it sends a clearer signal to users of this API.

marko-lisica · 2026-05-01T16:46:57Z

@rachaelshaw This current /commands endpoint is very bad at large scale, and we want to deprecate it.
Initially, @getvictor added a callout that we're deprecating usage without the host_identifier filter. I think it's worth adding a new endpoint, because we usually add this kind of endpoint under the "Hosts" section. Wdyt?

I set this to draft because if we want a new endpoint, we should define a milestone and open a new PR against the docs branch.

@JordanMontgomery @noahtalerman FYI

JordanMontgomery · 2026-05-01T16:52:59Z

@rachaelshaw This current /commands endpoint is very bad at large scale, and we want to deprecate it. Initially, @getvictor added a callout that we're deprecating usage without the host_identifier filter. I think it's worth adding a new endpoint, because we usually add this kind of endpoint under the "Hosts" section. Wdyt?

I set this to draft because if we want a new endpoint, we should define a milestone and open a new PR against the docs branch.

@JordanMontgomery @noahtalerman FYI

I think adding this endpoint under the hosts section is good and I am fully in support of deprecating and removing the multi-host version which has been a problem for quite some time. We only have a few customers who actually use it AFAIK, and most or all with the single-host filter so we could ask them about their usage if we need mroe information. I believe the customers are customer-starchik and customer-deebradel

The only concern I have about adding it only under hosts is if a user has a workflow that depends on the host's UUID or serial they might have to do two requests now to get host-by-identifier then commands-by-host whereas now they can put that serial or UUID right into the single request

noahtalerman · 2026-05-01T18:41:20Z

@marko-lisica @getvictor instead, can we just document that using GET /apple/commands w/o a host_identifier flag is deprecated? And the requirement will be enforced in Fleet 5.

No new endpoint.

Why?

I think deprecating the entire GET /apple/commands is going to create more alarm than necessary.
And to @JordanMontgomery's point this endpoint already supports filtering by UUID or serial (very common to use serial)
It's a smaller change (#iterate)

This way, customers using the endpoint w/ the host_identifier flag can keep using the existing endpoint. They don't need to worry today about it getting pulled out from under them later.

Ultimately up to @rachaelshaw.

Heads up that we'll also want to add a deprecation warning to fleetctl get mdm-commands if you don't use --host

getvictor · 2026-05-01T19:38:51Z

@noahtalerman Why not make --host required for fleetctl get mdm-commands ?

noahtalerman · 2026-05-01T19:56:00Z

Why not make --host required for fleetctl get mdm-commands ?

@getvictor oh good point. I was thinking this could be a breaking change but I can't think of any automated workflows that would use this fleetctl command.

cc @marko-lisica

getvictor · 2026-05-04T16:41:58Z

@marko-lisica Can you update this docs PR?

getvictor · 2026-05-11T19:00:54Z

@marko-lisica Can you update this docs PR?

This reverts commit 4090dc5.

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

rachaelshaw · 2026-05-14T22:43:33Z

 | 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. |


What does "required for new integrations" mean? Does it error now if not included, or is this just saying it will error in the next major release?

Next major release.

I think we can just saw Required and mention that it will be removed in Fleet 5. I also moved all the important info to the top (along w/ the required key): https://github.com/fleetdm/fleet/pull/44392/changes#diff-7246bc304b15c8865ed8eaa205e9c244d0a0314e4bae60cf553dc06147c38b64R7688

What do y'all think?

Stale

Deprecate unscoped host_identifier calls in /commands REST API, upd…

2d0b6ae

…ate example response, and emphasize required parameter for new integrations.

getvictor temporarily deployed to Docker Hub April 29, 2026 15:42 — with GitHub Actions Inactive

getvictor marked this pull request as ready for review April 29, 2026 15:43

getvictor requested a review from rachaelshaw as a code owner April 29, 2026 15:43

Copilot AI review requested due to automatic review settings April 29, 2026 15:43

claude Bot reviewed Apr 29, 2026

View reviewed changes

Copilot AI reviewed Apr 29, 2026

View reviewed changes

getvictor assigned marko-lisica and rachaelshaw Apr 29, 2026

marko-lisica reviewed Apr 30, 2026

View reviewed changes

marko-lisica previously requested changes Apr 30, 2026

View reviewed changes

getvictor mentioned this pull request Apr 30, 2026

List MDM commands (unscoped) still queries nano_view_queue VIEW with baked-in ORDER BY #44509

Closed

2 tasks

marko-lisica marked this pull request as draft May 1, 2026 16:34

added new endpoint to get host's mdm command

4090dc5

marko-lisica temporarily deployed to Docker Hub May 1, 2026 16:42 — with GitHub Actions Inactive

marko-lisica changed the title ~~Deprecate unscoped host_identifier calls in /commands REST API, update example response, and emphasize required parameter for new integrations.~~ Deprecate GET /api/v1/fleet/commands endpoint May 1, 2026

getvictor changed the title ~~Deprecate GET /api/v1/fleet/commands endpoint~~ Deprecate using GET /api/v1/fleet/commands w/o host_identifier May 14, 2026

Revert "added new endpoint to get host's mdm command"

062de47

This reverts commit 4090dc5.

getvictor temporarily deployed to Docker Hub May 14, 2026 14:15 — with GitHub Actions Inactive

getvictor requested a review from marko-lisica May 14, 2026 14:16

getvictor marked this pull request as ready for review May 14, 2026 14:16

claude Bot reviewed May 14, 2026

View reviewed changes

noahtalerman requested review from noahtalerman and removed request for marko-lisica May 14, 2026 18:35

noahtalerman unassigned rachaelshaw and marko-lisica May 14, 2026

rachaelshaw reviewed May 14, 2026

View reviewed changes

Update rest-api.md

0c467ca

fleet-release approved these changes May 15, 2026

View reviewed changes

noahtalerman temporarily deployed to Docker Hub May 15, 2026 13:12 — with GitHub Actions Inactive

noahtalerman requested a review from rachaelshaw May 15, 2026 13:14

noahtalerman approved these changes May 15, 2026

View reviewed changes

getvictor assigned rachaelshaw May 15, 2026

rachaelshaw approved these changes May 20, 2026

View reviewed changes

rachaelshaw merged commit 48b32e6 into main May 20, 2026
11 checks passed

rachaelshaw deleted the victor/44170-deprecation branch May 20, 2026 23:39

Uh oh!

Conversation

getvictor commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

qodo-code-review Bot commented Apr 29, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

getvictor commented Apr 29, 2026

Uh oh!

marko-lisica Apr 30, 2026 • edited by rachaelshaw Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

getvictor commented Apr 30, 2026

Uh oh!

marko-lisica commented May 1, 2026

Uh oh!

JordanMontgomery commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

noahtalerman commented May 1, 2026

Uh oh!

getvictor commented May 1, 2026

Uh oh!

noahtalerman commented May 1, 2026

Uh oh!

getvictor commented May 4, 2026

Uh oh!

getvictor commented May 11, 2026

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

rachaelshaw May 14, 2026

Choose a reason for hiding this comment

Uh oh!

getvictor May 15, 2026

Choose a reason for hiding this comment

Uh oh!

noahtalerman May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

getvictor commented Apr 29, 2026 •

edited

Loading

marko-lisica Apr 30, 2026 •

edited by rachaelshaw

Loading

JordanMontgomery commented May 1, 2026 •

edited

Loading

noahtalerman May 15, 2026 •

edited

Loading