Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-04-21 13:37:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 91

Document after and related API params. (#42844)

Browse source 
<!-- Add the related story/sub-task/bug number, like Resolves #123, or
remove if NA -->
**Related issue:** Resolves #41249
This commit is contained in:
Victor Lyuboslavsky 2026-04-03 18:03:25 -05:00 committed by GitHub
parent 39a6e22d8f
commit 48a2a159aa
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 45 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
docs/REST API/rest-api.md
View file

@ -523,6 +523,7 @@ Returns a list of the activities that have been performed in Fleet. For a compre
| 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.
@ -930,6 +931,9 @@ List certificate added to Fleet. Currently, they can only be added via GitOps.
| fleet | 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. 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
@ -4770,6 +4774,7 @@ A `fleet_id` of `0` returns the statistics for hosts that are "Unassigned". A `n
| 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`. |
| 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.
@ -5084,6 +5089,7 @@ Retrieves the certificates installed on a host.
| 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
@ -5292,6 +5298,9 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
| 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
@ -5909,6 +5918,7 @@ Returns a list of labels.
| 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.
@ -6265,6 +6275,9 @@ results (i.e., only profiles that are associated with "Unassigned" are listed).
| 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
@ -7275,6 +7288,8 @@ List software that can be automatically installed during setup. If `install_duri
| 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
@ -7619,6 +7634,7 @@ This endpoint returns the list of custom MDM commands that have been executed.
| host_identifier | string | query | The host's `hostname`, `uuid`, or `hardware_serial`. Returns only commands that target the specified host. |
| 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`.
>
@ -7893,7 +7909,10 @@ For example, a policy might ask “Is Gatekeeper enabled on macOS devices?“ Th
| Name | Type | In | Description |
| ----------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | integer | query | Page number of the results to fetch. |
| per_page | integer | query | Results per page.
| 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. |
#### Example
@ -7965,6 +7984,9 @@ _Available in Fleet Premium_
| 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". |
@ -8766,6 +8788,7 @@ Returns a list of reports. To see each report's data, use the [get report data](
| 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
@ -9780,6 +9803,9 @@ Returns a list hosts targeted in a batch script run, along with their script exe
| status | string | query | 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
@ -9926,6 +9952,9 @@ Deletes an existing script.
| 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
@ -9972,6 +10001,9 @@ Deletes an existing script.
| 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
@ -10178,6 +10210,7 @@ Get a list of all software.
| 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
@ -10375,6 +10408,7 @@ Get a list of all software versions.
| 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.
@ -10467,6 +10501,7 @@ Returns a list of all operating systems.
| 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
@ -11824,6 +11859,7 @@ Retrieves a list of all CVEs affecting software and/or OS versions.
| 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
@ -12113,6 +12149,7 @@ _Available in Fleet Premium_
| 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
@ -13128,6 +13165,7 @@ Returns a list of all enabled users
| 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
@ -13777,6 +13815,9 @@ Returns a list of the active invitations in Fleet.
| 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
@ -14067,6 +14108,9 @@ Lists all custom variables that can be used in scripts and profiles prefixed wit
|:--------------- |:------- |:----- |:------------------------------------------------------------|
| 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