- Packs
- Mobile device management (MDM)
- Get or apply configuration files
- Live query
- Trigger cron schedule
- Device-authenticated routes
- Downloadable installers
- Setup
- Scripts
This document includes the internal Fleet API routes that are helpful when developing or contributing to Fleet.
These endpoints are used by the Fleet UI, Fleet Desktop, and fleetctl
clients and will frequently change to reflect current functionality.
If you are interested in gathering information from Fleet in a production environment, please see the public Fleet REST API documentation.
Scheduling queries in Fleet is the best practice for collecting data from hosts. To learn how to schedule queries, check out the docs here.
The API routes to control packs are supported for backwards compatibility.
- Create pack
- Modify pack
- Get pack
- List packs
- Delete pack
- Delete pack by ID
- Get scheduled queries in a pack
- Add scheduled query to a pack
- Get scheduled query
- Modify scheduled query
- Delete scheduled query
POST /api/v1/fleet/packs
Name | Type | In | Description |
---|---|---|---|
name | string | body | Required. The pack's name. |
description | string | body | The pack's description. |
host_ids | list | body | A list containing the targeted host IDs. |
label_ids | list | body | A list containing the targeted label's IDs. |
team_ids | list | body | Available in Fleet Premium A list containing the targeted teams' IDs. |
POST /api/v1/fleet/packs
{
"description": "Collects osquery data.",
"host_ids": [],
"label_ids": [6],
"name": "query_pack_1"
}
Status: 200
{
"pack": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 17,
"name": "query_pack_1",
"description": "Collects osquery data.",
"query_count": 0,
"total_hosts_count": 223,
"host_ids": [],
"label_ids": [
6
],
"team_ids": []
}
}
PATCH /api/v1/fleet/packs/{id}
Name | Type | In | Description |
---|---|---|---|
id | integer | path | Required. The pack's id. |
name | string | body | The pack's name. |
description | string | body | The pack's description. |
host_ids | list | body | A list containing the targeted host IDs. |
label_ids | list | body | A list containing the targeted label's IDs. |
team_ids | list | body | Available in Fleet Premium A list containing the targeted teams' IDs. |
PATCH /api/v1/fleet/packs/{id}
{
"description": "MacOS hosts are targeted",
"host_ids": [],
"label_ids": [7]
}
Status: 200
{
"pack": {
"created_at": "2021-01-25T22:32:45Z",
"updated_at": "2021-01-25T22:32:45Z",
"id": 17,
"name": "Title2",
"description": "MacOS hosts are targeted",
"query_count": 0,
"total_hosts_count": 110,
"host_ids": [],
"label_ids": [
7
],
"team_ids": []
}
}
GET /api/v1/fleet/packs/{id}
Name | Type | In | Description |
---|---|---|---|
id | integer | path | Required. The pack's id. |
GET /api/v1/fleet/packs/17
Status: 200
{
"pack": {
"created_at": "2021-01-25T22:32:45Z",
"updated_at": "2021-01-25T22:32:45Z",
"id": 17,
"name": "Title2",
"description": "MacOS hosts are targeted",
"disabled": false,
"type": null,
"query_count": 0,
"total_hosts_count": 110,
"host_ids": [],
"label_ids": [
7
],
"team_ids": []
}
}
GET /api/v1/fleet/packs
Name | Type | In | Description |
---|---|---|---|
order_key | string | query | What to order results by. Can be any column in the packs 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 . |
GET /api/v1/fleet/packs
Status: 200
{
"packs": [
{
"created_at": "2021-01-05T21:13:04Z",
"updated_at": "2021-01-07T19:12:54Z",
"id": 1,
"name": "pack_number_one",
"description": "This pack has a description",
"disabled": true,
"query_count": 1,
"total_hosts_count": 53,
"host_ids": [],
"label_ids": [
8
],
"team_ids": []
},
{
"created_at": "2021-01-19T17:08:31Z",
"updated_at": "2021-01-19T17:08:31Z",
"id": 2,
"name": "query_pack_2",
"query_count": 5,
"total_hosts_count": 223,
"host_ids": [],
"label_ids": [
6
],
"team_ids": []
}
]
}
Delete pack by name.
DELETE /api/v1/fleet/packs/{name}
Name | Type | In | Description |
---|---|---|---|
name | string | path | Required. The pack's name. |
DELETE /api/v1/fleet/packs/pack_number_one
Status: 200
DELETE /api/v1/fleet/packs/id/{id}
Name | Type | In | Description |
---|---|---|---|
id | integer | path | Required. The pack's ID. |
DELETE /api/v1/fleet/packs/id/1
Status: 200
GET /api/v1/fleet/packs/{id}/scheduled
Name | Type | In | Description |
---|---|---|---|
id | integer | path | Required. The pack's ID. |
GET /api/v1/fleet/packs/1/scheduled
Status: 200
{
"scheduled": [
{
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 49,
"pack_id": 15,
"name": "new_query",
"query_id": 289,
"query_name": "new_query",
"query": "SELECT * FROM osquery_info",
"interval": 456,
"snapshot": false,
"removed": true,
"platform": "windows",
"version": "4.6.0",
"shard": null,
"denylist": null
},
{
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 50,
"pack_id": 15,
"name": "new_title_for_my_query",
"query_id": 288,
"query_name": "new_title_for_my_query",
"query": "SELECT * FROM osquery_info",
"interval": 677,
"snapshot": true,
"removed": false,
"platform": "windows",
"version": "4.6.0",
"shard": null,
"denylist": null
},
{
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 51,
"pack_id": 15,
"name": "osquery_info",
"query_id": 22,
"query_name": "osquery_info",
"query": "SELECT i.*, p.resident_size, p.user_time, p.system_time, time.minutes AS counter FROM osquery_info i, processes p, time WHERE p.pid = i.pid;",
"interval": 6667,
"snapshot": true,
"removed": false,
"platform": "windows",
"version": "4.6.0",
"shard": null,
"denylist": null
}
]
}
POST /api/v1/fleet/schedule
Name | Type | In | Description |
---|---|---|---|
pack_id | integer | body | Required. The pack's ID. |
query_id | integer | body | Required. The query's ID. |
interval | integer | body | Required. The amount of time, in seconds, the query waits before running. |
snapshot | boolean | body | Required. Whether the queries logs show everything in its current state. |
removed | boolean | body | Required. Whether "removed" actions should be logged. |
platform | string | body | The computer platform where this query will run (other platforms ignored). Empty value runs on all platforms. |
shard | integer | body | Restrict this query to a percentage (1-100) of target hosts. |
version | string | body | The minimum required osqueryd version installed on a host. |
POST /api/v1/fleet/schedule
{
"interval": 120,
"pack_id": 15,
"query_id": 23,
"removed": true,
"shard": null,
"snapshot": false,
"version": "4.5.0",
"platform": "windows"
}
Status: 200
{
"scheduled": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 56,
"pack_id": 17,
"name": "osquery_events",
"query_id": 23,
"query_name": "osquery_events",
"query": "SELECT name, publisher, type, subscriptions, events, active FROM osquery_events;",
"interval": 120,
"snapshot": false,
"removed": true,
"platform": "windows",
"version": "4.5.0",
"shard": 10
}
}
GET /api/v1/fleet/schedule/{id}
Name | Type | In | Description |
---|---|---|---|
id | integer | path | Required. The scheduled query's ID. |
GET /api/v1/fleet/schedule/56
Status: 200
{
"scheduled": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 56,
"pack_id": 17,
"name": "osquery_events",
"query_id": 23,
"query_name": "osquery_events",
"query": "SELECT name, publisher, type, subscriptions, events, active FROM osquery_events;",
"interval": 120,
"snapshot": false,
"removed": true,
"platform": "windows",
"version": "4.5.0",
"shard": 10,
"denylist": null
}
}
PATCH /api/v1/fleet/schedule/{id}
Name | Type | In | Description |
---|---|---|---|
id | integer | path | Required. The scheduled query's ID. |
interval | integer | body | The amount of time, in seconds, the query waits before running. |
snapshot | boolean | body | Whether the queries logs show everything in its current state. |
removed | boolean | body | Whether "removed" actions should be logged. |
platform | string | body | The computer platform where this query will run (other platforms ignored). Empty value runs on all platforms. |
shard | integer | body | Restrict this query to a percentage (1-100) of target hosts. |
version | string | body | The minimum required osqueryd version installed on a host. |
PATCH /api/v1/fleet/schedule/56
{
"platform": ""
}
Status: 200
{
"scheduled": {
"created_at": "2021-01-28T19:40:04Z",
"updated_at": "2021-01-28T19:40:04Z",
"id": 56,
"pack_id": 17,
"name": "osquery_events",
"query_id": 23,
"query_name": "osquery_events",
"query": "SELECT name, publisher, type, subscriptions, events, active FROM osquery_events;",
"interval": 120,
"snapshot": false,
"removed": true,
"platform": "",
"version": "4.5.0",
"shard": 10
}
}
DELETE /api/v1/fleet/schedule/{id}
Name | Type | In | Description |
---|---|---|---|
id | integer | path | Required. The scheduled query's ID. |
DELETE /api/v1/fleet/schedule/56
Status: 200
Only Fleet MDM specific endpoints are located within the root /mdm/ path.
The MDM endpoints exist to support the related command-line interface sub-commands of fleetctl
, such as fleetctl generate mdm-apple
and fleetctl get mdm-apple
, as well as the Fleet UI.
- Generate Apple DEP Key Pair
- Request Certificate Signing Request (CSR)
- Batch-apply Apple MDM custom settings
- Initiate SSO during DEP enrollment
- Complete SSO during DEP enrollment
- Preassign profiles to devices
- Match preassigned profiles
- Get FileVault statistics
None.
POST /api/v1/fleet/mdm/apple/dep/key_pair
{
"public_key": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNzVENDQVptZ0F3SUJBZ0lCQVRBTkJna3Foa2lHOXcwQkFRc0ZBREFTTVJBd0RnWURWUVFERXdkR2JHVmwKZEVSTk1CNFhEVEl5TVRJeE16RTFNREl6TmxvWERUSXpNREV4TWpFMU1USXpObG93RWpFUU1BNEdBMVVFQXhNSApSbXhsWlhSRVRUQ0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQ0FRb0NnZ0VCQU1jbXIxOVNiQUhaCnVZNnJBa254dVBCV0tkSFlrSXpJY2JGMHErZ0ZKZVU3cUlwU0FQWFhmeUpFTXpyQXhpZStPSi9QSXhkTHZTZVoKdXA2Qzg5VHM1VEwrWjhKZmR3T2ZLQVFIUWpyQVpGZkxkdUh0SjNRZnk3di9rbmZ3VzNNSU9XZ00zcDQ3a0xzOAowZnJzNmVuTlpXZElsNUMyV1NpOXVGVVVQcFJTbm1Ha1AvK2QydmNCaWdIOHQ0K3RuV3NYdjhpekxqcHhhanV6CjN0Vlp3SFA0cjBQZTdIM0I0eDZINmlKZmxRZzI4Z3owbDZWa0c2NjVKT2NMLzlDSmNtOWpWRmpxb0RmZTVjUFAKMVFNbFpyb1FCaFhOUHN3bEhRWTkzekJFK3VSRUVNL1N1d0dZcGZLYjQwSDM0S1B1U3Y5SXZHTjIzTXdNM01FMwppNEFBWGJQOGZNTUNBd0VBQWFNU01CQXdEZ1lEVlIwUEFRSC9CQVFEQWdXZ01BMEdDU3FHU0liM0RRRUJDd1VBCkE0SUJBUUM5ZFcyRXBxemp1VWhhbk1CSXJpK09VWVhrekR2eVB6bGxTMXd0UVdQQ0s4cFJ5Rk5TM3RkakVXT2kKSTcyOVh2UmtpNjhNZStqRlpxSkxFWHpWUlkwb29aSWhhcG5lNUZoNzlCbkIrWGl6TFQ0TStDNHJ5RVQwOXg4SQpaWHJuY1BKME9ueUdVemlFK0szWEI2dVNLeWN1a3pZci9sRVBBMGlQRTZpM0dNYjljenJFL2NOQURrRXZwcjU2CjN1SFdMU3hwK1U5QmJyaTNDSXBoR1NvSWxnTVBEaUE1RkpiOXc0SnlMK0crZ3Q4c1BlcUZkZDYyRDRpV3U5a0wKMVZBUjRSU2xPcWt1cTVXREZVcUxsVGJFMS9oY1lqcVVUczRrSWhENmN6MkcxQlBnMUU2WVpRZWp6U0ZpeGR1MApYUy9UTTByUFBKNithUC82V1BNRWpJcGVRcmNvCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K",
"private_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBeHlhdlgxSnNBZG01anFzQ1NmRzQ4RllwMGRpUWpNaHhzWFNyNkFVbDVUdW9pbElBCjlkZC9Ja1F6T3NER0o3NDRuODhqRjB1OUo1bTZub0x6MU96bE12NW53bDkzQTU4b0JBZENPc0JrVjh0MjRlMG4KZEIvTHUvK1NkL0JiY3dnNWFBemVuanVRdXp6Uit1enA2YzFsWjBpWGtMWlpLTDI0VlJRK2xGS2VZYVEvLzUzYQo5d0dLQWZ5M2o2MmRheGUveUxNdU9uRnFPN1BlMVZuQWMvaXZROTdzZmNIakhvZnFJbCtWQ0RieURQU1hwV1FiCnJya2s1d3YvMElseWIyTlVXT3FnTjk3bHc4L1ZBeVZtdWhBR0ZjMCt6Q1VkQmozZk1FVDY1RVFRejlLN0FaaWwKOHB2alFmZmdvKzVLLzBpOFkzYmN6QXpjd1RlTGdBQmRzL3g4d3dJREFRQUJBb0lCQUZRMUFFeGU3bnB0MUc4RgowZ2J3SlpIQjdSYms2bUlNMHo0RXBqZUtEYmI2M2MzMjFKOGV5b3Z6cUhHOFYwMHd1b0tnTkNkQ2lDMjVhOVpnCmFyZHFuNU5MVFJZOEJYZkxrVUQ2ekw5STRHVGJERjZGUjN4cmdWcnh1cjNxTE5EYjltSVBwd1hqQzlTUDUvMmcKdFZ0OTFOV3lOUndrYmxpeXQ4R0p1TmhBZ3VXbnJLQmw5b3o1QkpCU3JLZTJPUE5ERm5mbUs1NFM1VzRKakZZMApFTUV3Z2ZiL2xQZjluWFZwRG9QeEl3QnJmRU5oU3oxcVI0bzJPbVFyRGNOQUNZU05razRjbXVIMHpxc3J5aFg4CkNhajhCcllOemxaeGNPTmpmK1NxUkdvVndjdzZKbzNKazBEREZHeEVaOHBEUThJTXgzRUQ1SE4rbW1SaGRMQmoKT0pRZVhVRUNnWUVBeWZDaFArSVNzMGNtcEM3WUFrK1UrVHNTTElnY3BTTHdReFF2RGFmRWFtMHJoWDJQdDk1ZgpJN1NCTlM3TmlNR0xCVk4rWHg0RHlsT3RYaGNzTm5YUU5qU3J3ZFNHTGxFbU5wWDJXR0x4Znp4REVVbFFSS3FEClY2RHBDaHdmY2tCTFRUNkVaRDlnV21DOGZIYUNPc0JDUHR1VStLQUpFa1FRaVk1VlRLSjYrMkVDZ1lFQS9IYnQKKzIvWFJzSW84VkE4QmhjMitDYyt4YUNrK3dvTVByZ0d4OWxrMTR2R0hDcCtDY2ZGZThqU2NHMDhzU3RKTnJCVgp0cHgvbm1yYklyMzUxVkxlMFNLQ2R2aHF5ajBXQWlWVDhDL0VjcUxGV0VwNG5mY1ZnVHIxRjBGMUptR0Y4WVNYCk41VEh4Tnc4VjZLUDVmWEM2dVVFMkNpZnR1bkxqSGFSNXZCakxxTUNnWUVBdlNjTE0zYUVRNjlTejVrZE5sVHEKMnVUczZnOTRuV256bVRGdnZaKzJ5R1dIelp0R0lsbEZ6b0VHUWhXYjZndzROdjMxTWcxQVNhVkZrQXV1bXppUgpsaVNSK1pZak5ZRkhoUHZFNnhlSzA3NVRwLzUvRkVLUGttWWp3eGVDa1JjT01jVnNaeVpDRDRYcko3NHR6L0JFClhQSjdRTU5PbS9CcmVSMThZck1TOVNFQ2dZQjhqZnhaV1ZNL1FKbE1mTVl3UnhIQ21qSVk5R21ReE9OSHFpa0cKUGhYSFZkazJtaXcyalEyOFJWYTFTdDl2bFNoNHg4Ung1SUg5MlVBbHdzNVlWWnRDV0tFL0tzNGMyc2haNUtxbAp6QnRDWjFXdmVvWkpnTlptUEgwZ3JSV3NDdDgzU2JBRkp1enNEYS9qbUhzZi9BRGZQSUFJV1BwN0ZwdHF3REM1ClhBM0N1d0tCZ0c0QVVmMUZralNYRFBlL2JoVjhtZG4rZCtzN2g2RjZkRWttNnEya1dyS1B4V2lFdlN3QlZEQWoKQjhIRlNtNW1pcHNTTXhQbFVEZDRPSXRSUzVUM1AwcStRZENZNkwzemhmSFBCUzdhTlZaRUJXdVNlY2lDRk0wSQo3MjFSK081TitMTlFwN1N6VWUxRll1WWdhandFSE9KMW82d1ArZWloMmQyVVQyQ09Ed1NrCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg=="
}
Note that the public_key
and private_key
are base64 encoded and should be decoded before writing them to files.
POST /api/v1/fleet/mdm/apple/request_csr
Name | Type | In | Description |
---|---|---|---|
email_address | string | body | Required. The email that will be associated with the Apple APNs certificate. |
organization | string | body | Required. The name of the organization associated with the Apple APNs certificate. |
POST /api/v1/fleet/mdm/apple/request_csr
{
"apns_key": "aGV5LCBJJ20gc2VjcmV0Cg==",
"scep_cert": "bHR5LCBJJ20gc2VjcmV0Cg=",
"scep_key": "lKT5LCBJJ20gc2VjcmV0Cg="
}
Note that the response fields are base64 encoded and should be decoded before writing them to files. Once base64-decoded, they are PEM-encoded certificate and keys.
POST /api/v1/fleet/mdm/apple/profiles/batch
Name | Type | In | Description |
---|---|---|---|
team_id | number | query | Available in Fleet Premium The team ID to apply the custom settings to. Only one of team_name/team_id can be provided. |
team_name | string | query | Available in Fleet Premium The name of the team to apply the custom settings to. Only one of team_name/team_id can be provided. |
dry_run | bool | query | Validate the provided profiles and return any validation errors, but do not apply the changes. |
profiles | json | body | An array of strings, the base64-encoded .mobileconfig files to apply. |
If no team (id or name) is provided, the profiles are applied for all hosts (for Fleet Free) or for hosts that are not part of a team (for Fleet Premium). After the call, the provided list of profiles
will be the active profiles for that team (or no team) - that is, any existing profile that is not part of that list will be removed, and an existing profile with the same payload identifier as a new profile will be edited. If the list of provided profiles
is empty, all profiles are removed for that team (or no team).
POST /api/v1/fleet/mdm/apple/profiles/batch
204
This endpoint initiates the SSO flow, the response contains an URL that the client can use to redirect the user to initiate the SSO flow in the configured IdP.
POST /api/v1/fleet/mdm/sso
None.
POST /api/v1/fleet/mdm/sso
{
"url": "https://idp-provider.com/saml?SAMLRequest=...",
}
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/mdm/sso/callback
Name | Type | In | Description |
---|---|---|---|
SAMLResponse | string | body | Required. The SAML response from the identity provider. |
POST /api/v1/fleet/mdm/sso/callback
{
"SAMLResponse": "<SAML response from IdP>"
}
Status: 302
If the credentials are valid, the server redirects the client to the Fleet UI. The URL contains the following query parameters that can be used to complete the DEP enrollment flow:
enrollment_reference
a reference that must be passed along withprofile_token
to the endpoint to download an enrollment profile.profile_token
is a token that can be used to download an enrollment profile (.mobileconfig).eula_token
(optional) if an EULA was uploaded, this contains a token that can be used to view the EULA document.
Available in Fleet Premium
This endpoint stores a profile to be assigned to a host at some point in the future. The actual assignment happens when the Match preassigned profiles endpoint is called. The reason for this "pre-assign" step is to collect all profiles that are meant to be assigned to a host, and match the list of profiles to an existing team (or create one with that set of profiles if none exist) so that the host can be assigned to that team and inherit its list of profiles.
POST /api/v1/fleet/mdm/apple/profiles/preassign
Name | Type | In | Description |
---|---|---|---|
external_host_identifier | string | body | Required. The identifier of the host as generated by the external service (e.g. Puppet). |
host_uuid | string | body | Required. The UUID of the host. |
profile | string | body | Required. The base64-encoded .mobileconfig content of the MDM profile. |
group | string | body | The group label associated with that profile. This information is used to generate team names if they need to be created. |
exclude | boolean | body | Whether to skip delivering the profile to this host. |
POST /api/v1/fleet/mdm/apple/profiles/preassign
{
"external_host_identifier": "id-01234",
"host_uuid": "c0532a64-bec2-4cf9-aa37-96fe47ead814",
"profile": "<base64-encoded profile>",
"group": "Workstations",
"exclude": false
}
Status: 204
Available in Fleet Premium
Get aggregate status counts of disk encryption enforced on macOS hosts.
The summary can optionally be filtered by team id.
GET /api/v1/fleet/mdm/apple/filevault/summary
Name | Type | In | Description |
---|---|---|---|
team_id | string | query | Available in Fleet Premium The team id to filter the summary. |
Get aggregate status counts of Apple disk encryption profiles applying to macOS hosts enrolled to Fleet's MDM that are not assigned to any team.
GET /api/v1/fleet/mdm/apple/filevault/summary
Status: 200
{
"verified": 123,
"verifying": 123,
"action_required": 123,
"enforcing": 123,
"failed": 123,
"removing_enforcement": 123
}
Available in Fleet Premium
This endpoint uses the profiles stored by the Preassign profiles to devices endpoint to match the set of profiles to an existing team if possible, creating one if none exists. It then assigns the host to that team so that it receives the associated profiles. It is meant to be called only once all desired profiles have been pre-assigned to the host.
POST /api/v1/fleet/mdm/apple/profiles/match
Name | Type | In | Description |
---|---|---|---|
external_host_identifier | string | body | Required. The identifier of the host as generated by the external service (e.g. Puppet). |
POST /api/v1/fleet/mdm/apple/profiles/match
{
"external_host_identifier": "id-01234"
}
Status: 204
These API routes are used by the fleetctl
CLI tool. Users can manage Fleet with fleetctl
and configuration files in YAML syntax.
- Get queries
- Get query
- Apply queries
- Apply policies
- Get packs
- Apply packs
- Get pack by name
- Apply team
- Apply labels
- Get labels
- Get label
- Get enroll secrets
- Modify enroll secrets
Returns a list of all queries in the Fleet instance. Each item returned includes the name, description, and SQL of the query.
GET /api/v1/fleet/spec/queries
None.
GET /api/v1/fleet/spec/queries
Status: 200
{
"specs": [
{
"name": "query1",
"description": "query",
"query": "SELECT * FROM osquery_info"
},
{
"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;"
}
]
}
Returns the name, description, and SQL of the query specified by name.
GET /api/v1/fleet/spec/queries/{name}
Name | Type | In | Description |
---|---|---|---|
name | string | path | Required. The name of the query. |
GET /api/v1/fleet/spec/queries/query1
Status: 200
{
"specs": {
"name": "query1",
"description": "query",
"query": "SELECT * FROM osquery_info"
}
}
Creates and/or modifies the queries included in the list. To modify an existing query, the name of the query must already be used by an existing query. If a query with the specified name doesn't exist in Fleet, a new query will be created.
If a query field is not specified in the "spec" then its default value depending on its type will be assumed, e.g. if interval
is not set then 0
will be assumed, if discard_data
is omitted then false
will be assumed, etc.
POST /api/v1/fleet/spec/queries
Name | Type | In | Description |
---|---|---|---|
specs | list | body | Required. The list of the queries to be created or modified. |
For more information about the query fields, please refer to the Create query endpoint.
POST /api/v1/fleet/spec/queries
{
"specs": [
{
"name": "new_query",
"description": "This will be a new query because a query with the name 'new_query' doesn't exist in Fleet.",
"query": "SELECT * FROM osquery_info"
},
{
"name": "osquery_schedule",
"description": "This queries description and SQL will be modified because a query with the name 'osquery_schedule' exists in Fleet.",
"query": "SELECT * FROM osquery_info"
}
]
}
Status: 200
Returns all packs in the Fleet instance.
GET /api/v1/fleet/spec/packs
GET /api/v1/fleet/spec/packs
Status: 200
{
"specs": [
{
"id": 1,
"name": "pack_1",
"description": "Description",
"disabled": false,
"targets": {
"labels": ["All Hosts"],
"teams": null
},
"queries": [
{
"query": "new_query",
"name": "new_query",
"description": "",
"interval": 456,
"snapshot": false,
"removed": true,
"platform": "windows",
"version": "4.5.0"
},
{
"query": "new_title_for_my_query",
"name": "new_title_for_my_query",
"description": "",
"interval": 677,
"snapshot": true,
"removed": false,
"platform": "",
"version": ""
},
{
"query": "osquery_info",
"name": "osquery_info",
"description": "",
"interval": 6667,
"snapshot": true,
"removed": false,
"platform": "",
"version": ""
},
{
"query": "query1",
"name": "query1",
"description": "",
"interval": 7767,
"snapshot": false,
"removed": true,
"platform": "",
"version": ""
},
{
"query": "osquery_events",
"name": "osquery_events",
"description": "",
"interval": 454,
"snapshot": false,
"removed": true,
"platform": "",
"version": ""
},
{
"query": "osquery_events",
"name": "osquery_events-1",
"description": "",
"interval": 120,
"snapshot": false,
"removed": true,
"platform": "",
"version": ""
}
]
},
{
"id": 2,
"name": "pack_2",
"disabled": false,
"targets": {
"labels": null,
"teams": null
},
"queries": [
{
"query": "new_query",
"name": "new_query",
"description": "",
"interval": 333,
"snapshot": false,
"removed": true,
"platform": "windows",
"version": "4.5.0",
"shard": 10,
"denylist": null
}
]
}
]
}
Creates and/or modifies the policies included in the list. To modify an existing policy, the name of the policy included in the list must already be used by an existing policy. If a policy with the specified name doesn't exist in Fleet, a new policy will be created.
NOTE: when updating a policy, team and platform will be ignored.
POST /api/v1/fleet/spec/policies
Name | Type | In | Description |
---|---|---|---|
specs | list | body | Required. The list of the policies to be created or modified. |
POST /api/v1/fleet/spec/policies
{
"specs": [
{
"name": "new policy",
"description": "This will be a new policy because a policy with the name 'new policy' doesn't exist in Fleet.",
"query": "SELECT * FROM osquery_info",
"resolution": "some resolution steps here",
"critical": false
},
{
"name": "Is FileVault enabled on macOS devices?",
"query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT “” AND filevault_status = ‘on’ LIMIT 1;",
"description": "Checks to make sure that the FileVault feature is enabled on macOS devices.",
"resolution": "Choose Apple menu > System Preferences, then click Security & Privacy. Click the FileVault tab. Click the Lock icon, then enter an administrator name and password. Click Turn On FileVault.",
"platform": "darwin",
"critical": true
}
]
}
The field critical
is available in Fleet Premium.
Status: 200
Creates and/or modifies the packs included in the list.
POST /api/v1/fleet/spec/packs
Name | Type | In | Description |
---|---|---|---|
specs | list | body | Required. A list that includes the specs for each pack to be added to the Fleet instance. |
POST /api/v1/fleet/spec/packs
{
"specs": [
{
"id": 1,
"name": "pack_1",
"description": "Description",
"disabled": false,
"targets": {
"labels": ["All Hosts"],
"teams": null
},
"queries": [
{
"query": "new_query",
"name": "new_query",
"description": "",
"interval": 456,
"snapshot": false,
"removed": true
},
{
"query": "new_title_for_my_query",
"name": "new_title_for_my_query",
"description": "",
"interval": 677,
"snapshot": true,
"removed": false
},
{
"query": "osquery_info",
"name": "osquery_info",
"description": "",
"interval": 6667,
"snapshot": true,
"removed": false
},
{
"query": "query1",
"name": "query1",
"description": "",
"interval": 7767,
"snapshot": false,
"removed": true
},
{
"query": "osquery_events",
"name": "osquery_events",
"description": "",
"interval": 454,
"snapshot": false,
"removed": true
},
{
"query": "osquery_events",
"name": "osquery_events-1",
"description": "",
"interval": 120,
"snapshot": false,
"removed": true
}
]
},
{
"id": 2,
"name": "pack_2",
"disabled": false,
"targets": {
"labels": null,
"teams": null
},
"queries": [
{
"query": "new_query",
"name": "new_query",
"description": "",
"interval": 333,
"snapshot": false,
"removed": true,
"platform": "windows"
}
]
}
]
}
Status: 200
Returns a pack.
GET /api/v1/fleet/spec/packs/{name}
Name | Type | In | Description |
---|---|---|---|
name | string | path | Required. The pack's name. |
GET /api/v1/fleet/spec/packs/pack_1
Status: 200
{
"specs": {
"id": 15,
"name": "pack_1",
"description": "Description",
"disabled": false,
"targets": {
"labels": ["All Hosts"],
"teams": null
},
"queries": [
{
"query": "new_title_for_my_query",
"name": "new_title_for_my_query",
"description": "",
"interval": 677,
"snapshot": true,
"removed": false,
"platform": "",
"version": ""
},
{
"query": "osquery_info",
"name": "osquery_info",
"description": "",
"interval": 6667,
"snapshot": true,
"removed": false,
"platform": "",
"version": ""
},
{
"query": "query1",
"name": "query1",
"description": "",
"interval": 7767,
"snapshot": false,
"removed": true,
"platform": "",
"version": ""
},
{
"query": "osquery_events",
"name": "osquery_events",
"description": "",
"interval": 454,
"snapshot": false,
"removed": true,
"platform": "",
"version": ""
},
{
"query": "osquery_events",
"name": "osquery_events-1",
"description": "",
"interval": 120,
"snapshot": false,
"removed": true,
"platform": "",
"version": ""
}
]
}
}
Available in Fleet Premium
If the name
specified is associated with an existing team, this API route, completely replaces this team's existing agent_options
and secrets
with those that are specified.
If the name
is not already associated with an existing team, this API route creates a new team with the specified name
, agent_options
, and secrets
.
POST /api/v1/fleet/spec/teams
Name | Type | In | Description |
---|---|---|---|
name | string | body | Required. The team's name. |
agent_options | object | body | The agent options spec that is applied to the hosts assigned to the specified to team. These agent options completely override the global agent options specified in the GET /api/v1/fleet/config API route |
features | object | body | The features that are applied to the hosts assigned to the specified to team. These features completely override the global features specified in the GET /api/v1/fleet/config API route |
secrets | list | body | A list of plain text strings is used as the enroll secrets. Existing secrets are replaced with this list, or left unmodified if this list is empty. Note that there is a limit of 50 secrets allowed. |
mdm | object | body | The team's MDM configuration options. |
mdm.macos_updates | object | body | The OS updates macOS configuration options for Nudge. |
mdm.macos_updates.minimum_version | string | body | The required minimum operating system version. |
mdm.macos_updates.deadline | string | body | The required installation date for Nudge to enforce the operating system version. |
mdm.macos_settings | object | body | The macOS-specific MDM settings. |
mdm.macos_settings.custom_settings | list | body | The list of .mobileconfig files to apply to hosts that belong to this team. |
scripts | list | body | A list of script files to add to this team so they can be executed at a later time. |
mdm.macos_settings.enable_disk_encryption | bool | body | Whether disk encryption should be enabled for hosts that belong to this team. |
mdm.windows_settings | object | body | The Windows-specific MDM settings. |
mdm.windows_settings.custom_settings | list | body | The list of .xml files to apply to hosts that belong to this team. |
force | bool | query | Force apply the spec even if there are (ignorable) validation errors. Those are unknown keys and agent options-related validations. |
dry_run | bool | query | Validate the provided JSON for unknown keys and invalid value types and return any validation errors, but do not apply the changes. |
POST /api/v1/fleet/spec/teams
{
"specs": [
{
"name": "Client Platform Engineering",
"features": {
"enable_host_users": false,
"enable_software_inventory": true,
"additional_queries": {
"foo": "SELECT * FROM bar;"
}
},
"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": {}
}
},
"secrets": [
{
"secret": "fTp52/twaxBU6gIi0J6PHp8o5Sm1k1kn"
},
{
"secret": "bhD5kiX2J+KBgZSk118qO61ZIdX/v8On"
}
],
"mdm": {
"macos_updates": {
"minimum_version": "12.3.1",
"deadline": "2023-12-01"
},
"macos_settings": {
"custom_settings": ["path/to/profile1.mobileconfig"],
"enable_disk_encryption": true
},
"windows_settings": {
"custom_settings": ["path/to/profile2.xml"],
}
},
"scripts": ["path/to/script.sh"],
}
]
}
Status: 200
{
"team_ids_by_name": {
"Client Platform Engineering": 123
}
}
Adds the supplied labels to Fleet. Each label requires the name
, and label_membership_type
properties.
If the label_membership_type
is set to dynamic
, the query
property must also be specified with the value set to a query in SQL syntax.
If the label_membership_type
is set to manual
, the hosts
property must also be specified with the value set to a list of hostnames.
POST /api/v1/fleet/spec/labels
Name | Type | In | Description |
---|---|---|---|
specs | list | path | A list of the label to apply. Each label requires the name , query , and label_membership_type properties |
POST /api/v1/fleet/spec/labels
{
"specs": [
{
"name": "Ubuntu",
"description": "Filters Ubuntu hosts",
"query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';",
"label_membership_type": "dynamic"
},
{
"name": "local_machine",
"description": "Includes only my local machine",
"label_membership_type": "manual",
"hosts": ["snacbook-pro.local"]
}
]
}
Status: 200
GET /api/v1/fleet/spec/labels
None.
GET /api/v1/fleet/spec/labels
Status: 200
{
"specs": [
{
"id": 6,
"name": "All Hosts",
"description": "All hosts which have enrolled in Fleet",
"query": "SELECT 1;",
"label_type": "builtin",
"label_membership_type": "dynamic"
},
{
"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"
},
{
"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"
},
{
"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"
},
{
"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"
},
{
"id": 11,
"name": "Ubuntu",
"description": "Filters Ubuntu hosts",
"query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';",
"label_membership_type": "dynamic"
}
]
}
Returns the label specified by name.
GET /api/v1/fleet/spec/labels/{name}
None.
GET /api/v1/fleet/spec/labels/local_machine
Status: 200
{
"specs": {
"id": 12,
"name": "local_machine",
"description": "Includes only my local machine",
"query": "",
"label_membership_type": "manual"
}
}
Returns the valid global enroll secrets.
GET /api/v1/fleet/spec/enroll_secret
None.
GET /api/v1/fleet/spec/enroll_secret
Status: 200
{
"spec": {
"secrets": [
{
"secret": "fTp52/twaxBU6gIi0J6PHp8o5Sm1k1kn",
"created_at": "2021-01-07T19:40:04Z"
},
{
"secret": "bhD5kiX2J+KBgZSk118qO61ZIdX/v8On",
"created_at": "2021-01-04T21:18:07Z"
}
]
}
}
This replaces the active global enroll secrets with the secrets specified.
POST /api/v1/fleet/spec/enroll_secret
Name | Type | In | Description |
---|---|---|---|
secrets | list | body | Required. The plain text string used as the enroll secret. Note that there is a limit of 50 secrets allowed. |
{
"spec": {
"secrets": [
{
"secret": "fTp52/twaxBU6gIi0J6PHp8o5Sm1k1kn"
}
]
}
}
POST /api/v1/fleet/spec/enroll_secret
Status: 200
These API routes are used by the Fleet UI.
- Check live query status
- Check result store status
- Search targets
- Count targets
- Run live query
- Run live query by name
- Retrieve live query results (standard WebSocket API)
- Retrieve live query results (SockJS)
This checks the status of Fleet's ability to run a live query. If an error is present in the response, Fleet won't be able to run a live query successfully. The Fleet UI uses this endpoint to make sure that the Fleet instance is correctly configured to run live queries.
GET /api/v1/fleet/status/live_query
None.
GET /api/v1/fleet/status/live_query
Status: 200
This checks Fleet's result store status. If an error is present in the response, Fleet won't be able to run a live query successfully. The Fleet UI uses this endpoint to make sure that the Fleet instance is correctly configured to run live queries.
GET /api/v1/fleet/status/result_store
None.
GET /api/v1/fleet/status/result_store
Status: 200
Accepts a search query and a list of host IDs to omit and returns a set of up to ten matching hosts. If a query ID is provided and the referenced query allows observers to run, targets will include hosts for which the user has an observer role.
POST /api/latest/fleet/hosts/search
Name | Type | In | Description |
---|---|---|---|
query | string | body | The query used to identify hosts to target. Searchable items include a host's hostname or IPv4 address. |
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 affect which targets are included. |
excluded_host_ids | array | body | The list of host ids to omit from the search results. |
POST /api/v1/fleet/hosts/search
{
"query": "foo",
"query_id": 42,
"selected": {
"hosts": [],
"labels": [],
"teams": [1]
}
}
{
"targets": {
"hosts": [
{
"created_at": "2021-02-03T16:11:43Z",
"updated_at": "2021-02-03T21:58:19Z",
"id": 1337,
"detail_updated_at": "2021-02-03T21:58:10Z",
"label_updated_at": "2021-02-03T21:58:10Z",
"last_enrolled_at": "2021-02-03T16:11:43Z",
"seen_time": "2021-02-03T21:58:20Z",
"hostname": "foof41482833",
"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": "foof41482833",
"display_name": "foof41482833",
"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": "foof41482833"
}
]
}
}
Counts the number of online and offline hosts included in a given set of selected targets.
POST /api/latest/fleet/targets/count
Name | Type | In | Description |
---|---|---|---|
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 determine which targets are included. |
selected | object | body | The object includes lists of selected host IDs (selected.hosts ), label IDs (selected.labels ), and team IDs (selected.teams ). When provided, builtin label IDs, custom label IDs and team IDs become AND filters. Within each selector, selecting two or more teams, two or more builtin labels, or two or more custom labels, behave as OR filters. There's one special case for the builtin label "All hosts", if such label is selected, then all other label and team selectors are ignored (and all hosts will be selected). If a host ID is explicitly included in selected.hosts , then it is assured that the query will be selected to run on it (no matter the contents of selected.labels and selected.teams ). See examples below. |
POST /api/latest/fleet/targets/count
{
"query_id": 1337,
"selected": {
"hosts": [],
"labels": [42],
"teams": []
}
}
{
"targets_count": 813,
"targets_offline": 813,
"targets_online": 0
}
Runs the specified query as a live query on the specified hosts or group of hosts and returns a new live query campaign. Individual hosts must be specified with the host's ID. Label IDs also specify groups of hosts.
After you initiate the query, get results via WebSocket.
POST /api/v1/fleet/queries/run
Name | Type | In | Description |
---|---|---|---|
query | string | body | The SQL if using a custom query. |
query_id | integer | body | The saved query (if any) that will be run. Required if running query as an observer. The observer_can_run property on the query effects which targets are included. |
selected | object | body | Required. The object includes lists of selected host IDs (selected.hosts ), label IDs (selected.labels ), and team IDs (selected.teams ). When provided, builtin label IDs, custom label IDs and team IDs become AND filters. Within each selector, selecting two or more teams, two or more builtin labels, or two or more custom labels, behave as OR filters. There's one special case for the builtin label "All hosts", if such label is selected, then all other label and team selectors are ignored (and all hosts will be selected). If a host ID is explicitly included in selected.hosts , then it is assured that the query will be selected to run on it (no matter the contents of selected.labels and selected.teams ). See examples below. |
One of query
and query_id
must be specified.
POST /api/v1/fleet/queries/run
{
"query": "SELECT instance_id FROM system_info",
"selected": {
"hosts": [171]
}
}
Status: 200
{
"campaign": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"Metrics": {
"TotalHosts": 1,
"OnlineHosts": 0,
"OfflineHosts": 1,
"MissingInActionHosts": 0,
"NewHosts": 1
},
"id": 1,
"query_id": 3,
"status": 0,
"user_id": 1
}
}
POST /api/v1/fleet/queries/run
{
"query": "SELECT instance_id FROM system_info;",
"selected": {
"labels": [7]
}
}
Status: 200
{
"campaign": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"Metrics": {
"TotalHosts": 102,
"OnlineHosts": 0,
"OfflineHosts": 24,
"MissingInActionHosts": 0,
"NewHosts": 0
},
"id": 2,
"query_id": 3,
"status": 0,
"user_id": 1
}
}
Runs the specified saved query as a live query on the specified targets. Returns a new live query campaign. Individual hosts must be specified with the host's hostname. Groups of hosts are specified by label name.
After the query has been initiated, get results via WebSocket.
POST /api/v1/fleet/queries/run_by_names
Name | Type | In | Description |
---|---|---|---|
query | string | body | The SQL of the query. |
query_id | integer | body | The saved query (if any) that will be run. The observer_can_run property on the query effects which targets are included. |
selected | object | body | Required. The object includes lists of selected hostnames (selected.hosts ), label names (labels ). When provided, builtin label names and custom label names become AND filters. Within each selector, selecting two or more builtin labels, or two or more custom labels, behave as OR filters. There's one special case for the builtin label "All hosts" , if such label is selected, then all other label and team selectors are ignored (and all hosts will be selected). If a host's hostname is explicitly included in selected.hosts , then it is assured that the query will be selected to run on it (no matter the contents of selected.labels ). See examples below. |
One of query
and query_id
must be specified.
POST /api/v1/fleet/queries/run_by_names
{
"query_id": 1,
"selected": {
"hosts": ["macbook-pro.local"]
}
}
Status: 200
{
"campaign": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"Metrics": {
"TotalHosts": 1,
"OnlineHosts": 0,
"OfflineHosts": 1,
"MissingInActionHosts": 0,
"NewHosts": 1
},
"id": 1,
"query_id": 3,
"status": 0,
"user_id": 1
}
}
POST /api/v1/fleet/queries/run_by_names
{
"query": "SELECT instance_id FROM system_info",
"selected": {
"labels": ["All Hosts"]
}
}
Status: 200
{
"campaign": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"Metrics": {
"TotalHosts": 102,
"OnlineHosts": 0,
"OfflineHosts": 24,
"MissingInActionHosts": 0,
"NewHosts": 1
},
"id": 2,
"query_id": 3,
"status": 0,
"user_id": 1
}
}
You can retrieve the results of a live query using the standard WebSocket API.
Before you retrieve the live query results, you must create a live query campaign by running the live query. Use the Run live query or Run live query by name endpoints to create a live query campaign.
Note that live queries are automatically cancelled if this method is not called to start retrieving the results within 60 seconds of initiating the query.
/api/v1/fleet/results/websocket
Name | Type | In | Description |
---|---|---|---|
token | string | Required. The token used to authenticate with the Fleet API. | |
campaignID | integer | Required. The ID of the live query campaign. |
const socket = new WebSocket('wss://<your-base-url>/api/v1/fleet/results/websocket');
socket.onopen = () => {
socket.send(JSON.stringify({ type: 'auth', data: { token: <auth-token> } }));
socket.send(JSON.stringify({ type: 'select_campaign', data: { campaign_id: <campaign-id> } }));
};
socket.onmessage = ({ data }) => {
console.log(data);
const message = JSON.parse(data);
if (message.type === 'status' && message.data.status === 'finished') {
socket.close();
}
}
o
[
{
"type": "auth",
"data": { "token": <insert_token_here> }
}
]
[
{
"type": "select_campaign",
"data": { "campaign_id": 12 }
}
]
// Sends the total number of hosts targeted and segments them by status
[
{
"type": "totals",
"data": {
"count": 24,
"online": 6,
"offline": 18,
"missing_in_action": 0
}
}
]
// Sends the expected results, actual results so far, and the status of the live query
[
{
"type": "status",
"data": {
"expected_results": 6,
"actual_results": 0,
"status": "pending"
}
}
]
// Sends the result for a given host
[
{
"type": "result",
"data": {
"distributed_query_execution_id": 39,
"host": {
"id": 42,
"hostname": "foobar",
"display_name": "foobar"
},
"rows": [
// query results data for the given host
],
"error": null
}
}
]
// Sends the status of "finished" when messages with the results for all expected hosts have been sent
[
{
"type": "status",
"data": {
"expected_results": 6,
"actual_results": 6,
"status": "finished"
}
}
]
You can also retrieve live query results with a SockJS client. The script to handle the request and response messages will look similar to the standard WebSocket API script with slight variations. For example, the constructor used for SockJS is SockJS
while the constructor used for the standard WebSocket API is WebSocket
.
Note that SockJS has been found to be substantially less reliable than the standard WebSockets approach.
/api/v1/fleet/results/
Name | Type | In | Description |
---|---|---|---|
token | string | Required. The token used to authenticate with the Fleet API. | |
campaignID | integer | Required. The ID of the live query campaign. |
const socket = new SockJS(`<your-base-url>/api/v1/fleet/results`, undefined, {});
socket.onopen = () => {
socket.send(JSON.stringify({ type: 'auth', data: { token: <token> } }));
socket.send(JSON.stringify({ type: 'select_campaign', data: { campaign_id: <campaignID> } }));
};
socket.onmessage = ({ data }) => {
console.log(data);
const message = JSON.parse(data);
if (message.type === 'status' && message.data.status === 'finished') {
socket.close();
}
}
o
[
{
"type": "auth",
"data": { "token": <insert_token_here> }
}
]
[
{
"type": "select_campaign",
"data": { "campaign_id": 12 }
}
]
// Sends the total number of hosts targeted and segments them by status
[
{
"type": "totals",
"data": {
"count": 24,
"online": 6,
"offline": 18,
"missing_in_action": 0
}
}
]
// Sends the expected results, actual results so far, and the status of the live query
[
{
"type": "status",
"data": {
"expected_results": 6,
"actual_results": 0,
"status": "pending"
}
}
]
// Sends the result for a given host
[
{
"type": "result",
"data": {
"distributed_query_execution_id": 39,
"host": {
"id": 42,
"hostname": "foobar",
"display_name": "foobar"
},
"rows": [
// query results data for the given host
],
"error": null
}
}
]
// Sends the status of "finished" when messages with the results for all expected hosts have been sent
[
{
"type": "status",
"data": {
"expected_results": 6,
"actual_results": 6,
"status": "finished"
}
}
]
This API is used by the fleetctl
CLI tool to make requests to trigger an ad hoc run of all jobs in
a specified cron schedule.
This makes a request to trigger the specified cron schedule. Upon receiving the request, the Fleet server first checks the current status of the schedule, and it returns an error if a run is currently pending.
POST /api/latest/fleet/trigger
Name | Type | In | Description |
---|---|---|---|
name | string | query | The name of the cron schedule to trigger. Supported trigger names are apple_mdm_dep_profile_assigner , automations , cleanups_then_aggregation , integrations , mdm_apple_profile_manager , usage_statistics , and vulnerabilities |
POST /api/latest/fleet/trigger?name=automations
Status: 200
Device-authenticated routes are routes used by the Fleet Desktop application. Unlike most other routes, Fleet user's API token does not authenticate them. They use a device-specific token.
- Refetch device's host
- Get device's Google Chrome profiles
- Get device's mobile device management (MDM) and Munki information
- Get device's policies
- Get device's API features
- Get device's transparency URL
- Download device's MDM manual enrollment profile
- Migrate device to Fleet from another MDM solution
- Trigger FileVault key escrow
- Report an agent error
Same as Refetch host route for the current device.
POST /api/v1/fleet/device/{token}/refetch
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
Same as Get host's Google Chrome profiles for the current device.
GET /api/v1/fleet/device/{token}/device_mapping
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
Same as Get host's mobile device management and Munki information for the current device.
GET /api/v1/fleet/device/{token}/macadmins
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
Available in Fleet Premium
Gets all information required by Fleet Desktop, this includes things like the number of failed policies or notifications to show/hide menu items.
GET /api/v1/fleet/device/{token}/desktop
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
GET /api/v1/fleet/device/abcdef012456789/desktop
Status: 200
{
"failing_policies_count": 3,
"notifications": {
"needs_mdm_migration": true,
"renew_enrollment_profile": false,
"enforce_bitlocker_encryption": false,
},
"config": {
"org_info": {
"org_name": "Fleet",
"org_logo_url": "https://example.com/logo.jpg",
"org_logo_url_light_background": "https://example.com/logo-light.jpg",
"contact_url": "https://fleetdm.com/company/contact"
},
"mdm": {
"macos_migration": {
"mode": "forced"
}
}
}
}
In regards to the notifications
key:
needs_mdm_migration
means that the device fits all the requirements to allow the user to initiate an MDM migration to Fleet.renew_enrollment_profile
means that the device is currently unmanaged from MDM but should be DEP enrolled into Fleet.enforce_bitlocker_encryption
applies only to Windows devices and means that it should encrypt the disk and report the encryption key back to Fleet.
Available in Fleet Premium
Lists the policies applied to the current device.
GET /api/v1/fleet/device/{token}/policies
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
GET /api/v1/fleet/device/abcdef012456789/policies
Status: 200
{
"policies": [
{
"id": 1,
"name": "SomeQuery",
"query": "SELECT * FROM foo;",
"description": "this is a query",
"resolution": "fix with these steps...",
"platform": "windows,linux",
"response": "pass"
},
{
"id": 2,
"name": "SomeQuery2",
"query": "SELECT * FROM bar;",
"description": "this is another query",
"resolution": "fix with these other steps...",
"platform": "darwin",
"response": "fail"
},
{
"id": 3,
"name": "SomeQuery3",
"query": "SELECT * FROM baz;",
"description": "",
"resolution": "",
"platform": "",
"response": ""
}
]
}
This supports the dynamic discovery of API features supported by the server for device-authenticated routes. This allows supporting different versions of Fleet Desktop and Fleet server instances (older or newer) while supporting the evolution of the API features. With this mechanism, an older Fleet Desktop can ignore features it doesn't know about, and a newer one can avoid requesting features about which the server doesn't know.
GET /api/v1/fleet/device/{token}/api_features
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
GET /api/v1/fleet/device/abcdef012456789/api_features
Status: 200
{
"features": {}
}
Returns the URL to open when clicking the "Transparency" menu item in Fleet Desktop. Note that Fleet Premium is required to configure a custom transparency URL.
GET /api/v1/fleet/device/{token}/transparency
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
GET /api/v1/fleet/device/abcdef012456789/transparency
Status: 307
Redirects to the transparency URL.
Downloads the Mobile Device Management (MDM) enrollment profile to install on the device for a manual enrollment into Fleet MDM.
GET /api/v1/fleet/device/{token}/mdm/apple/manual_enrollment_profile
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
GET /api/v1/fleet/device/abcdef012456789/mdm/apple/manual_enrollment_profile
Status: 200
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<!-- ... -->
</plist>
Signals the Fleet server to send a webbook request with the device UUID and serial number to the webhook URL configured for MDM migration. Requires Fleet Premium license
POST /api/v1/fleet/device/{token}/migrate_mdm
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
POST /api/v1/fleet/device/abcdef012456789/migrate_mdm
Status: 204
Sends a signal to Fleet Desktop to initiate a FileVault key escrow. This is useful for setting the escrow key initially as well as in scenarios where a token rotation is required. Requires Fleet Premium license
POST /api/v1/fleet/device/{token}/rotate_encryption_key
Name | Type | In | Description |
---|---|---|---|
token | string | path | The device's authentication token. |
POST /api/v1/fleet/device/abcdef012456789/rotate_encryption_key
Status: 204
Notifies the server about an agent error, resulting in two outcomes:
- The error gets saved in Redis and can later be accessed using
fleetctl debug archive
. - The server consistently replies with a
500
status code, which can serve as a signal to activate an alarm through a monitoring tool.
Note: to allow
fleetd
agents to use this endpoint, you need to set a custom environment variable
POST /api/v1/fleet/device/{token}/debug/errors
Name | Type | Description |
---|---|---|
error_source | string | Process name that error originated from ex. orbit, fleet-desktop |
error_source_version | string | version of error_source |
error_timestamp | datetime | Time in UTC that error occured |
error_message | string | error message |
error_additional_info | obj | Any additional identifiers to assist debugging |
Status: 500
These API routes are used by the UI in Fleet Sandbox.
Downloads a pre-built fleet-osquery installer with the given parameters.
POST /api/v1/fleet/download_installer/{kind}
Name | Type | In | Description |
---|---|---|---|
kind | string | path | The installer kind: pkg, msi, deb or rpm. |
enroll_secret | string | x-www-form-urlencoded | The global enroll secret. |
token | string | x-www-form-urlencoded | The authentication token. |
desktop | boolean | x-www-form-urlencoded | Set to true to ask for an installer that includes Fleet Desktop. |
Status: 200
Content-Type: application/octet-stream
Content-Disposition: attachment
Content-Length: <length>
Body: <blob>
If an installer with the provided parameters is found, the installer is returned as a binary blob in the body of the response.
Status: 400
This error occurs if an installer with the provided parameters doesn't exist.
Checks if a pre-built fleet-osquery installer with the given parameters exists.
HEAD /api/v1/fleet/download_installer/{kind}
Name | Type | In | Description |
---|---|---|---|
kind | string | path | The installer kind: pkg, msi, deb or rpm. |
enroll_secret | string | query | The global enroll secret. |
desktop | boolean | query | Set to true to ask for an installer that includes Fleet Desktop. |
Status: 200
If an installer with the provided parameters is found.
Status: 400
If an installer with the provided parameters doesn't exist.
Sets up a new Fleet instance with the given parameters.
POST /api/v1/setup
Name | Type | In | Description |
---|---|---|---|
admin | object | body | Required. Contains the following admin user details: admin , email , name , password , and password_confirmation . |
org_info | object | body | Required. Contains the following organizational details: org_name . |
server_url | string | body | Required. The URL of the Fleet instance. |
{
"admin": {
"admin": true,
"email": "janedoe@example.com",
"name": "Jane Doe",
"password": "password!234",
"password_confirmation": "password!234"
},
"org_info": {
"org_name": "Fleet Device Management"
},
"server_url": "https://localhost:8080"
}
Status: 200
If the Fleet instance is provided required parameters to complete setup.
{
"admin": {
"created_at": "2021-01-07T19:40:04Z",
"updated_at": "2021-01-07T19:40:04Z",
"id": 1,
"name": "Jane Doe",
"email": "janedoe@example.com",
"force_password_reset": false,
"gravatar_url": "",
"sso_enabled": false,
"global_role": "admin",
"api_only": false,
"teams": []
},
"org_info": {
"org_name": "Fleet Device Management",
"org_logo_url": "https://fleetdm.com/logo.png"
},
"server_url": "https://localhost:8080",
"osquery_enroll_secret": null,
"token": "ur4RWGBeiNmNzer/dnGzgUQ+jxrJe19xuHg/LhLkbhuZMQu35scyBHUHs68+RJxZynxQnuTz4WTHXayAJJaGgg=="
}
Available in Fleet Premium
POST /api/v1/fleet/scripts/batch
Name | Type | In | Description |
---|---|---|---|
team_id | number | query | The ID of the team to add the scripts to. Only one team identifier (team_id or team_name ) can be included in the request, omit this parameter if using team_name . |
team_name | string | query | The name of the team to add the scripts to. Only one team identifier (team_id or team_name ) can be included in the request, omit this parameter if using team_id . |
dry_run | bool | query | Validate the provided scripts and return any validation errors, but do not apply the changes. |
scripts | array | body | An array of objects with the scripts payloads. Each item must contain name with the script name and script_contents with the script contents encoded in base64 |
If both team_id
and team_name
parameters are included, this endpoint will respond with an error. If no team_name
or team_id
is provided, the scripts will be applied for all hosts.
Note that this endpoint replaces all the active scripts for the specified team (or no team). Any existing script that is not included in the list will be removed, and existing scripts with the same name as a new script will be edited. Providing an empty list of scripts will remove existing scripts.
POST /api/v1/fleet/mdm/scripts/batch
204