REST API

• Authentication
• Activities
• Fleet configuration
• File carving
• Hosts
• Labels
• Mobile device management (MDM)
• Policies
• Queries
• Schedule (deprecated)
• Scripts
• Sessions
• Software
• Targets
• Teams
• Translator
• Users
• API errors

Use the Fleet APIs to automate Fleet.

This page includes a list of available resources and their API routes.

Authentication

• Retrieve your API token
• Log in
• Log out
• Forgot password
• Change password
• Reset password
• Me
• SSO config
• Initiate SSO
• SSO callback

Retrieve your API token

All API requests to the Fleet server require API token authentication unless noted in the documentation. API tokens are tied to your Fleet user account.

To get an API token, retrieve it from "My account" > "Get API token" in the Fleet UI (/profile). Or, you can send a request to the login API endpoint to get your token.

Then, use that API token to authenticate all subsequent API requests by sending it in the "Authorization" request header, prefixed with "Bearer ":

Authorization: Bearer <your token>

For SSO users, email/password login is disabled. The API token can instead be retrieved from the "My account" page in the UI (/profile). On this page, choose "Get API token".

Log in

Authenticates the user with the specified credentials. Use the token returned from this endpoint to authenticate further API requests.

POST /api/v1/fleet/login

This API endpoint is not available to SSO users, since email/password login is disabled for SSO users. To get an API token for an SSO user, you can use the Fleet UI.

Parameters

Example

POST /api/v1/fleet/login

Request body

{
  "email": "[email protected]",
  "password": "VArCjNW7CfsxGp67"
}

Default response

Status: 200

{
  "user": {
    "created_at": "2020-11-13T22:57:12Z",
    "updated_at": "2020-11-13T22:57:12Z",
    "id": 1,
    "name": "Jane Doe",
    "email": "[email protected]",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "global_role": "admin",
    "teams": []
  },
  "token": "{your token}"
}

Authentication failed

Status: 401 Unauthorized

{
  "message": "Authentication failed",
  "errors": [
    {
      "name": "base",
      "reason": "Authentication failed"
    }
  ],
  "uuid": "1272014b-902b-4b36-bcdb-75fde5eac1fc"
}

Too many requests / Rate limiting

Status: 429 Too Many Requests Header: retry-after: N

This response includes a header retry-after that indicates how many more seconds you are blocked before you can try again.

{
  "message": "limit exceeded, retry after: Ns",
  "errors": [
    {
      "name": "base",
      "reason": "limit exceeded, retry after: Ns"
    }
  ]
}

---

Log out

Logs out the authenticated user.

POST /api/v1/fleet/logout

Example

POST /api/v1/fleet/logout

Default response

Status: 200

---

Forgot password

Sends a password reset email to the specified email. Requires that SMTP or SES is configured for your Fleet server.

POST /api/v1/fleet/forgot_password

Parameters

Example

POST /api/v1/fleet/forgot_password

Request body

{
  "email": "[email protected]"
}

Default response

Status: 200

Unknown error

Status: 500

{
  "message": "Unknown Error",
  "errors": [
    {
      "name": "base",
      "reason": "email not configured"
    }
  ]
}

---

Change password

POST /api/v1/fleet/change_password

Changes the password for the authenticated user.

Parameters

Example

POST /api/v1/fleet/change_password

Request body

{
  "old_password": "VArCjNW7CfsxGp67",
  "new_password": "zGq7mCLA6z4PzArC"
}

Default response

Status: 200

Validation failed

Status: 422 Unprocessable entity

{
  "message": "Validation Failed",
  "errors": [
    {
      "name": "old_password",
      "reason": "old password does not match"
    }
  ]
}

Reset password

Resets a user's password. Which user is determined by the password reset token used. The password reset token can be found in the password reset email sent to the desired user.

POST /api/v1/fleet/reset_password

Parameters

Example

POST /api/v1/fleet/reset_password

Request body

{
  "new_password": "abc123",
  "new_password_confirmation": "abc123",
  "password_reset_token": "UU5EK0JhcVpsRkY3NTdsaVliMEZDbHJ6TWdhK3oxQ1Q="
}

Default response

Status: 200

---

Me

Retrieves the user data for the authenticated user.

GET /api/v1/fleet/me

Example

GET /api/v1/fleet/me

Default response

Status: 200

{
  "user": {
    "created_at": "2020-11-13T22:57:12Z",
    "updated_at": "2020-11-16T23:49:41Z",
    "id": 1,
    "name": "Jane Doe",
    "email": "[email protected]",
    "global_role": "admin",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "teams": []
  }
}

---

Perform required password reset

Resets the password of the authenticated user. Requires that force_password_reset is set to true prior to the request.

POST /api/v1/fleet/perform_required_password_reset

Example

POST /api/v1/fleet/perform_required_password_reset

Request body

{
  "new_password": "sdPz8CV5YhzH47nK"
}

Default response

Status: 200

{
  "user": {
    "created_at": "2020-11-13T22:57:12Z",
    "updated_at": "2020-11-17T00:09:23Z",
    "id": 1,
    "name": "Jane Doe",
    "email": "[email protected]",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "global_role": "admin",
    "teams": []
  }
}

---

SSO config

Gets the current SSO configuration.

GET /api/v1/fleet/sso

Example

GET /api/v1/fleet/sso

Default response

Status: 200

{
  "settings": {
    "idp_name": "IDP Vendor 1",
    "idp_image_url": "",
    "sso_enabled": false
  }
}

---

Initiate SSO

POST /api/v1/fleet/sso

Parameters

Example

POST /api/v1/fleet/sso

Request body

{
  "relay_url": "/hosts/manage"
}

Default response

Status: 200

Unknown error

Status: 500

{
  "message": "Unknown Error",
  "errors": [
    {
      "name": "base",
      "reason": "InitiateSSO getting metadata: Get \"https://idp.example.org/idp-meta.xml\": dial tcp: lookup idp.example.org on [2001:558:feed::1]:53: no such host"
    }
  ]
}

SSO callback

This is the callback endpoint that the identity provider will use to send security assertions to Fleet. This is where Fleet receives and processes the response from the identify provider.

POST /api/v1/fleet/sso/callback

Parameters

Example

POST /api/v1/fleet/sso/callback

Request body

{
  "SAMLResponse": "<SAML response from IdP>"
}

Default response

Status: 200

---

Activities

List activities

Returns a list of the activities that have been performed in Fleet as well as additional metadata. for pagination. For a comprehensive list of activity types and detailed information, please see the audit logs page.

GET /api/v1/fleet/activities

Parameters

Example

GET /api/v1/fleet/activities?page=0&per_page=10&order_key=created_at&order_direction=desc

Default response

{
  "activities": [
    {
      "created_at": "2021-07-30T13:41:07Z",
      "id": 24,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "live_query",
      "details": {
        "targets_count": 231
      }
    },
    {
      "created_at": "2021-07-29T15:35:33Z",
      "id": 23,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "deleted_multiple_saved_query",
      "details": {
        "query_ids": [
          2,
          24,
          25
        ]
      }
    },
    {
      "created_at": "2021-07-29T14:40:30Z",
      "id": 22,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "created_team",
      "details": {
        "team_id": 3,
        "team_name": "Oranges"
      }
    },
    {
      "created_at": "2021-07-29T14:40:27Z",
      "id": 21,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "created_team",
      "details": {
        "team_id": 2,
        "team_name": "Apples"
      }
    },
    {
      "created_at": "2021-07-27T14:35:08Z",
      "id": 20,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "created_pack",
      "details": {
        "pack_id": 2,
        "pack_name": "New pack"
      }
    },
    {
      "created_at": "2021-07-27T13:25:21Z",
      "id": 19,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "live_query",
      "details": {
        "targets_count": 14
      }
    },
    {
      "created_at": "2021-07-27T13:25:14Z",
      "id": 18,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "live_query",
      "details": {
        "targets_count": 14
      }
    },
    {
      "created_at": "2021-07-26T19:28:24Z",
      "id": 17,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "live_query",
      "details": {
        "target_counts": 1
      }
    },
    {
      "created_at": "2021-07-26T17:27:37Z",
      "id": 16,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "live_query",
      "details": {
        "target_counts": 14
      }
    },
    {
      "created_at": "2021-07-26T17:27:08Z",
      "id": 15,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "live_query",
      "details": {
        "target_counts": 14
      }
    }
  ],
  "meta": {
    "has_next_results": true,
    "has_previous_results": false
  }
}

---

File carving

• List carves
• Get carve
• Get carve block

Fleet supports osquery's file carving functionality as of Fleet 3.3.0. This allows the Fleet server to request files (and sets of files) from osquery agents, returning the full contents to Fleet.

To initiate a file carve using the Fleet API, you can use the live query endpoint to run a query against the carves table.

For more information on executing a file carve in Fleet, go to the File carving with Fleet docs.

List carves

Retrieves a list of the non expired carves. Carve contents remain available for 24 hours after the first data is provided from the osquery client.

GET /api/v1/fleet/carves

Parameters

Example

GET /api/v1/fleet/carves

Default response

Status: 200

{
  "carves": [
    {
      "id": 1,
      "created_at": "2021-02-23T22:52:01Z",
      "host_id": 7,
      "name": "macbook-pro.local-2021-02-23T22:52:01Z-fleet_distributed_query_30",
      "block_count": 1,
      "block_size": 2000000,
      "carve_size": 2048,
      "carve_id": "c6958b5f-4c10-4dc8-bc10-60aad5b20dc8",
      "request_id": "fleet_distributed_query_30",
      "session_id": "065a1dc3-40ad-441c-afff-80c2ad7dac28",
      "expired": false,
      "max_block": 0
    },
    {
      "id": 2,
      "created_at": "2021-02-23T22:53:03Z",
      "host_id": 7,
      "name": "macbook-pro.local-2021-02-23T22:53:03Z-fleet_distributed_query_31",
      "block_count": 2,
      "block_size": 2000000,
      "carve_size": 3400704,
      "carve_id": "2b9170b9-4e11-4569-a97c-2f18d18bec7a",
      "request_id": "fleet_distributed_query_31",
      "session_id": "f73922ed-40a4-4e98-a50a-ccda9d3eb755",
      "expired": false,
      "max_block": 1,
      "error": "S3 multipart carve upload: EntityTooSmall: Your proposed upload is smaller than the minimum allowed object size"
    }
  ]
}

Get carve

Retrieves the specified carve.

GET /api/v1/fleet/carves/:id

Parameters

Example

GET /api/v1/fleet/carves/1

Default response

Status: 200

{
  "carve": {
    "id": 1,
    "created_at": "2021-02-23T22:52:01Z",
    "host_id": 7,
    "name": "macbook-pro.local-2021-02-23T22:52:01Z-fleet_distributed_query_30",
    "block_count": 1,
    "block_size": 2000000,
    "carve_size": 2048,
    "carve_id": "c6958b5f-4c10-4dc8-bc10-60aad5b20dc8",
    "request_id": "fleet_distributed_query_30",
    "session_id": "065a1dc3-40ad-441c-afff-80c2ad7dac28",
    "expired": false,
    "max_block": 0
  }
}

Get carve block

Retrieves the specified carve block. This endpoint retrieves the data that was carved.

GET /api/v1/fleet/carves/:id/block/:block_id

Parameters

Example

GET /api/v1/fleet/carves/1/block/0

Default response

Status: 200

{
    "data": "aG9zdHMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."
}

---

Fleet configuration

• Get certificate
• Get configuration
• Modify configuration
• Get global enroll secrets
• Modify global enroll secrets
• Get team enroll secrets
• Modify team enroll secrets
• Create invite
• List invites
• Delete invite
• Verify invite
• Update invite
• Version

The Fleet server exposes a handful of API endpoints that handle the configuration of Fleet as well as endpoints that manage invitation and enroll secret operations. All the following endpoints require prior authentication meaning you must first log in successfully before calling any of the endpoints documented below.

Get certificate

Returns the Fleet certificate.

GET /api/v1/fleet/config/certificate

Parameters

None.

Example

GET /api/v1/fleet/config/certificate

Default response

Status: 200

{
  "certificate_chain": <certificate_chain>
}

Get configuration

Returns all information about the Fleet's configuration.

NOTE: The agent_options, sso_settings and smtp_settings fields are only returned to Global Admin users.

GET /api/v1/fleet/config

Parameters

None.

Example

GET /api/v1/fleet/config

Default response

Status: 200

{
  "org_info": {
    "org_name": "fleet",
    "org_logo_url": "",
    "contact_url": "https://fleetdm.com/company/contact"
  },
  "server_settings": {
    "server_url": "https://localhost:8080",
    "live_query_disabled": false,
    "query_reports_disabled": false,
    "enable_analytics": true
  },
  "smtp_settings": {
    "enable_smtp": false,
    "configured": false,
    "sender_address": "",
    "server": "",
    "port": 587,
    "authentication_type": "authtype_username_password",
    "user_name": "",
    "password": "********",
    "enable_ssl_tls": true,
    "authentication_method": "authmethod_plain",
    "domain": "",
    "verify_ssl_certs": true,
    "enable_start_tls": true
  },
  "sso_settings": {
    "entity_id": "",
    "issuer_uri": "",
    "idp_image_url": "",
    "metadata": "",
    "metadata_url": "",
    "idp_name": "",
    "enable_sso": false,
    "enable_sso_idp_login": false,
    "enable_jit_provisioning": false
  },
  "host_expiry_settings": {
    "host_expiry_enabled": false,
    "host_expiry_window": 0
  },
  "features": {
    "additional_queries": null
  },
  "mdm": {
    "apple_bm_default_team": "",
    "apple_bm_terms_expired": false,
    "enabled_and_configured": true,
    "windows_enabled_and_configured": true,
    "macos_updates": {
      "minimum_version": "12.3.1",
      "deadline": "2022-01-01"
    },
    "windows_updates": {
      "deadline_days": 5,
      "grace_period_days": 1
    },
    "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"],
    "end_user_authentication": {
      "entity_id": "",
      "issuer_uri": "",
      "metadata": "",
      "metadata_url": "",
      "idp_name": ""
    },
    "macos_migration": {
      "enable": false,
      "mode": "voluntary",
      "webhook_url": "https://webhook.example.com"
    },
    "macos_setup": {
      "bootstrap_package": "",
      "enable_end_user_authentication": false,
      "macos_setup_assistant": "path/to/config.json",
      "enable_release_device_manually": true
    }
  },
  "agent_options": {
    "spec": {
      "config": {
        "options": {
          "pack_delimiter": "/",
          "logger_tls_period": 10,
          "distributed_plugin": "tls",
          "disable_distributed": false,
          "logger_tls_endpoint": "/api/v1/osquery/log",
          "distributed_interval": 10,
          "distributed_tls_max_attempts": 3
        },
        "decorators": {
          "load": [
            "SELECT uuid AS host_uuid FROM system_info;",
            "SELECT hostname AS hostname FROM system_info;"
          ]
        }
      },
      "overrides": {},
      "command_line_flags": {}
    }
  },
  "license": {
     "tier": "free",
     "expiration": "0001-01-01T00:00:00Z"
   },
  "logging": {
      "debug": false,
      "json": false,
      "result": {
          "plugin": "firehose",
          "config": {
              "region": "us-east-1",
              "status_stream": "",
              "result_stream": "result-topic"
          }
      },
      "status": {
          "plugin": "filesystem",
          "config": {
              "status_log_file": "foo_status",
              "result_log_file": "",
              "enable_log_rotation": false,
              "enable_log_compression": false
          }
      }
  },
  "vulnerability_settings": {
    "databases_path": ""
  },
  "webhook_settings": {
    "host_status_webhook": {
      "enable_host_status_webhook": true,
      "destination_url": "https://server.com",
      "host_percentage": 5,
      "days_count": 7
    },
    "failing_policies_webhook":{
      "enable_failing_policies_webhook":true,
      "destination_url": "https://server.com",
      "policy_ids": [1, 2, 3],
      "host_batch_size": 1000
    },
    "vulnerabilities_webhook":{
      "enable_vulnerabilities_webhook":true,
      "destination_url": "https://server.com",
      "host_batch_size": 1000
    }
  },
  "integrations": {
    "jira": null,
    "google_calendar": [
      {
        "domain": "example.com",
        "api_key_json": {
           "type": "service_account",
           "project_id": "fleet-in-your-calendar",
           "private_key_id": "<private key id>",
           "private_key": "-----BEGIN PRIVATE KEY-----\n<private key>\n-----END PRIVATE KEY-----\n",
           "client_email": "fleet-calendar-events@fleet-in-your-calendar.iam.gserviceaccount.com",
           "client_id": "<client id>",
           "auth_uri": "https://accounts.google.com/o/oauth2/auth",
           "token_uri": "https://oauth2.googleapis.com/token",
           "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
           "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/fleet-calendar-events%40fleet-in-your-calendar.iam.gserviceaccount.com",
           "universe_domain": "googleapis.com"
         }
      }
    ]
  },
  "logging": {
    "debug": false,
    "json": false,
    "result": {
        "plugin": "filesystem",
        "config": {
          "status_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_status",
          "result_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_result",
          "enable_log_rotation": false,
          "enable_log_compression": false
        }
      },
    "status": {
      "plugin": "filesystem",
      "config": {
        "status_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_status",
        "result_log_file": "/var/folders/xh/bxm1d2615tv3vrg4zrxq540h0000gn/T/osquery_result",
        "enable_log_rotation": false,
        "enable_log_compression": false
      }
    }
  },
  "update_interval": {
    "osquery_detail": 3600000000000,
    "osquery_policy": 3600000000000
  },
  "vulnerabilities": {
    "cpe_database_url": "",
    "disable_schedule": false,
    "cve_feed_prefix_url": "",
    "databases_path": "",
    "disable_data_sync": false,
    "periodicity": 3600000000000,
    "recent_vulnerability_max_age": 2592000000000000
  }
}

Modify configuration

Modifies the Fleet's configuration with the supplied information.

PATCH /api/v1/fleet/config

Parameters

Note that when making changes to the integrations object, all integrations must be provided (not just the one being modified). This is because the endpoint will consider missing integrations as deleted.

Example

PATCH /api/v1/fleet/config

Request body

{
  "org_info": {
    "org_name": "Fleet Device Management",
    "org_logo_url": "https://fleetdm.com/logo.png"
  },
  "smtp_settings": {
    "enable_smtp": true,
    "server": "localhost",
    "port": "1025"
  }
}

Default response

Status: 200

{
  "org_info": {
    "org_name": "Fleet Device Management",
    "org_logo_url": "https://fleetdm.com/logo.png",
    "org_logo_url_light_background": "https://fleetdm.com/logo-light.png",
    "contact_url": "https://fleetdm.com/company/contact"
  },
  "server_settings": {
    "server_url": "https://localhost:8080",
    "live_query_disabled": false,
    "query_reports_disabled": false
  },
  "smtp_settings": {
    "enable_smtp": true,
    "configured": true,
    "sender_address": "",
    "server": "localhost",
    "port": 1025,
    "authentication_type": "authtype_username_none",
    "user_name": "",
    "password": "********",
    "enable_ssl_tls": true,
    "authentication_method": "authmethod_plain",
    "domain": "",
    "verify_ssl_certs": true,
    "enable_start_tls": true
  },
  "sso_settings": {
    "entity_id": "",
    "issuer_uri": "",
    "idp_image_url": "",
    "metadata": "",
    "metadata_url": "",
    "idp_name": "",
    "enable_sso": false
  },
  "host_expiry_settings": {
    "host_expiry_enabled": false,
    "host_expiry_window": 0
  },
  "features": {
    "additional_queries": null
  },
  "license": {
    "tier": "free",
    "expiration": "0001-01-01T00:00:00Z"
  },
  "mdm": {
    "apple_bm_default_team": "",
    "apple_bm_terms_expired": false,
    "apple_bm_enabled_and_configured": false,
    "enabled_and_configured": false,
    "windows_enabled_and_configured": false,
    "macos_updates": {
      "minimum_version": "12.3.1",
      "deadline": "2022-01-01"
    },
    "windows_updates": {
      "deadline_days": 5,
      "grace_period_days": 1
    },
    "macos_settings": {
      "custom_settings": {
        "path": "path/to/profile1.mobileconfig",
        "labels": ["Label 1", "Label 2"]
      },
      "enable_disk_encryption": true
    },
    "windows_settings": {
      "custom_settings": {
        "path": "path/to/profile1.xml",
        "labels": ["Label 1", "Label 2"]
      }      
    },
    "end_user_authentication": {
      "entity_id": "",
      "issuer_uri": "",
      "metadata": "",
      "metadata_url": "",
      "idp_name": ""
    },
    "macos_migration": {
      "enable": false,
      "mode": "voluntary",
      "webhook_url": "https://webhook.example.com"
    },
    "macos_setup": {
      "bootstrap_package": "",
      "enable_end_user_authentication": false,
      "macos_setup_assistant": "path/to/config.json"
    }
  },
  "agent_options": {
    "config": {
      "options": {
        "pack_delimiter": "/",
        "logger_tls_period": 10,
        "distributed_plugin": "tls",
        "disable_distributed": false,
        "logger_tls_endpoint": "/api/v1/osquery/log",
        "distributed_interval": 10,
        "distributed_tls_max_attempts": 3
      },
      "decorators": {
        "load": [
          "SELECT uuid AS host_uuid FROM system_info;",
          "SELECT hostname AS hostname FROM system_info;"
        ]
      }
    },
    "overrides": {},
    "command_line_flags": {}
  },
  "vulnerability_settings": {
    "databases_path": ""
  },
  "webhook_settings": {
    "host_status_webhook": {
      "enable_host_status_webhook": true,
      "destination_url": "https://server.com",
      "host_percentage": 5,
      "days_count": 7
    },
    "failing_policies_webhook":{
      "enable_failing_policies_webhook":true,
      "destination_url": "https://server.com",
      "policy_ids": [1, 2, 3],
      "host_batch_size": 1000
    },
    "vulnerabilities_webhook":{
      "enable_vulnerabilities_webhook":true,
      "destination_url": "https://server.com",
      "host_batch_size": 1000
    }
  },
  "integrations": {
    "jira": [
      {
        "url": "https://jiraserver.com",
        "username": "some_user",
        "password": "sec4et!",
        "project_key": "jira_project",
        "enable_software_vulnerabilities": false
      }
    ],
    "google_calendar": [
      {
        "domain": "",
        "api_key_json": null
      }
    ]
  },
  "logging": {
      "debug": false,
      "json": false,
      "result": {
          "plugin": "firehose",
          "config": {
              "region": "us-east-1",
              "status_stream": "",
              "result_stream": "result-topic"
          }
      },
      "status": {
          "plugin": "filesystem",
          "config": {
              "status_log_file": "foo_status",
              "result_log_file": "",
              "enable_log_rotation": false,
              "enable_log_compression": false
          }
      }
  }
}

Get global enroll secrets

Returns the valid global enroll secrets.

GET /api/v1/fleet/spec/enroll_secret

Parameters

None.

Example

GET /api/v1/fleet/spec/enroll_secret

Default response

Status: 200

{
    "spec": {
        "secrets": [
            {
                "secret": "vhPzPOnCMOMoqSrLxKxzSADyqncayacB",
                "created_at": "2021-11-12T20:24:57Z"
            },
            {
                "secret": "jZpexWGiXmXaFAKdrdttFHdJBqEnqlVF",
                "created_at": "2021-11-12T20:24:57Z"
            }
        ]
    }
}

Modify global enroll secrets

Replaces all existing global enroll secrets.

POST /api/v1/fleet/spec/enroll_secret

Parameters

Example

Replace all global enroll secrets with a new enroll secret.

POST /api/v1/fleet/spec/enroll_secret

Request body

{
    "spec": {
        "secrets": [
            {
                "secret": "KuSkYFsHBQVlaFtqOLwoUIWniHhpvEhP"
            }
        ]
    }
}

Default response

Status: 200

{}

Example

Delete all global enroll secrets.

POST /api/v1/fleet/spec/enroll_secret

Request body

{
    "spec": {
        "secrets": []
    }
}

Default response

Status: 200

{}

Get team enroll secrets

Returns the valid team enroll secrets.

GET /api/v1/fleet/teams/:id/secrets

Parameters

None.

Example

GET /api/v1/fleet/teams/1/secrets

Default response

Status: 200

{
  "secrets": [
    {
      "created_at": "2021-06-16T22:05:49Z",
      "secret": "aFtH2Nq09hrvi73ErlWNQfa7M53D3rPR",
      "team_id": 1
    }
  ]
}

Modify team enroll secrets

Replaces all existing team enroll secrets.

PATCH /api/v1/fleet/teams/:id/secrets

Parameters

Example

Replace all of a team's existing enroll secrets with a new enroll secret

PATCH /api/v1/fleet/teams/2/secrets

Request body

{
  "secrets": [
    {
      "secret": "n07v32y53c237734m3n201153c237"
    }
  ]
}

Default response

Status: 200

{
  "secrets": [
    {
      "secret": "n07v32y53c237734m3n201153c237",
      "created_at": "0001-01-01T00:00:00Z"
    }
  ]
}

Example

Delete all of a team's existing enroll secrets

PATCH /api/v1/fleet/teams/2/secrets

Request body

{
  "secrets": []
}

Default response

Status: 200

{
  "secrets": null
}

Create invite

POST /api/v1/fleet/invites

Parameters

Example

Request body

{
  "email": "[email protected]",
  "name": "John",
  "sso_enabled": false,
  "global_role": null,
  "teams": [
    {
      "id": 2,
      "role": "observer"
    },
    {
      "id": 3,
      "role": "maintainer"
    }
  ]
}

POST /api/v1/fleet/invites

Default response

Status: 200

{
  "invite": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 3,
    "invited_by": 1,
    "email": "[email protected]",
    "name": "John",
    "sso_enabled": false,
    "teams": [
      {
        "id": 10,
        "created_at": "0001-01-01T00:00:00Z",
        "name": "Apples",
        "description": "",
        "agent_options": null,
        "user_count": 0,
        "host_count": 0,
        "role": "observer"
      },
      {
        "id": 14,
        "created_at": "0001-01-01T00:00:00Z",
        "name": "Best of the Best Engineering",
        "description": "",
        "agent_options": null,
        "user_count": 0,
        "host_count": 0,
        "role": "maintainer"
      }
    ]
  }
}

List invites

Returns a list of the active invitations in Fleet.

GET /api/v1/fleet/invites

Parameters

Example

GET /api/v1/fleet/invites

Default response

Status: 200

{
  "invites": [
    {
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "id": 3,
      "email": "[email protected]",
      "name": "John",
      "sso_enabled": false,
      "global_role": "admin",
      "teams": []
    },
    {
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "id": 4,
      "email": "[email protected]",
      "name": "Bob",
      "sso_enabled": false,
      "global_role": "admin",
      "teams": []
    }
  ]
}

Delete invite

Delete the specified invite from Fleet.

DELETE /api/v1/fleet/invites/:id

Parameters

Example

DELETE /api/v1/fleet/invites/123

Default response

Status: 200

Verify invite

Verify the specified invite.

GET /api/v1/fleet/invites/:token

Parameters

Example

GET /api/v1/fleet/invites/abcdef012456789

Default response

Status: 200

{
    "invite": {
        "created_at": "2021-01-15T00:58:33Z",
        "updated_at": "2021-01-15T00:58:33Z",
        "id": 4,
        "email": "[email protected]",
        "name": "Steve",
        "sso_enabled": false,
        "global_role": "admin",
        "teams": []
    }
}

Not found

Status: 404

{
    "message": "Resource Not Found",
    "errors": [
        {
            "name": "base",
            "reason": "Invite with token <token> was not found in the datastore"
        }
    ]
}

Update invite

PATCH /api/v1/fleet/invites/:id

Parameters

Example

PATCH /api/v1/fleet/invites/123

Request body

{
  "email": "[email protected]",
  "name": "John",
  "sso_enabled": false,
  "global_role": null,
  "teams": [
    {
      "id": 2,
      "role": "observer"
    },
    {
      "id": 3,
      "role": "maintainer"
    }
  ]
}

Default response

Status: 200

{
  "invite": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 3,
    "invited_by": 1,
    "email": "[email protected]",
    "name": "John",
    "sso_enabled": false,
    "teams": [
      {
        "id": 10,
        "created_at": "0001-01-01T00:00:00Z",
        "name": "Apples",
        "description": "",
        "agent_options": null,
        "user_count": 0,
        "host_count": 0,
        "role": "observer"
      },
      {
        "id": 14,
        "created_at": "0001-01-01T00:00:00Z",
        "name": "Best of the Best Engineering",
        "description": "",
        "agent_options": null,
        "user_count": 0,
        "host_count": 0,
        "role": "maintainer"
      }
    ]
  }
}

Version

Get version and build information from the Fleet server.

GET /api/v1/fleet/version

Parameters

None.

Example

GET /api/v1/fleet/version

Default response

Status: 200

{
  "version": "3.9.0-93-g1b67826f-dirty",
  "branch": "version",
  "revision": "1b67826fe4bf40b2f45ec53e01db9bf467752e74",
  "go_version": "go1.15.7",
  "build_date": "2021-03-27T00:28:48Z",
  "build_user": "zwass"
}

---

Hosts

• On the different timestamps in the host data structure
• List hosts
• Count hosts
• Get hosts summary
• Get host
• Get host by identifier
• Get host by device token
• Delete host
• Refetch host
• Transfer hosts to a team
• Transfer hosts to a team by filter
• Bulk delete hosts by filter or ids
• Get human-device mapping
• Update custom human-device mapping
• Get host's device health report
• Get host's mobile device management (MDM) information
• Get mobile device management (MDM) summary
• Get host's mobile device management (MDM) and Munki information
• Get aggregated host's mobile device management (MDM) and Munki information
• List host OS versions
• Get host OS version
• Get host's scripts
• Get hosts report in CSV
• Get host's disk encryption key
• Lock host
• Unlock host
• Wipe host
• Get host's past activity
• Get host's upcoming activity
• Live query one host (ad-hoc)
• Live query host by identifier (ad-hoc)

On the different timestamps in the host data structure

Hosts have a set of timestamps usually named with an "_at" suffix, such as created_at, enrolled_at, etc. Before we go through each of them and what they mean, we need to understand a bit more about how the host data structure is represented in the database.

The table hosts is the main one. It holds the core data for a host. A host doesn't exist if there is no row for it in this table. This table also holds most of the timestamps, but it doesn't hold all of the host data. This is an important detail as we'll see below.

There's adjacent tables to this one that usually follow the name convention host_<extra data descriptor>. Examples of this are: host_additional that holds additional query results, host_software that links a host with many rows from the software table.

• created_at: the time the row in the database was created, which usually corresponds to the first enrollment of the host.
• updated_at: the last time the row in the database for the hosts table was updated.
• detail_updated_at: the last time Fleet updated host data, based on the results from the detail queries (this includes updates to host associated tables, e.g. host_users).
• label_updated_at: the last time Fleet updated the label membership for the host based on the results from the queries ran.
• last_enrolled_at: the last time the host enrolled to Fleet.
• policy_updated_at: the last time we updated the policy results for the host based on the queries ran.
• seen_time: the last time the host contacted the fleet server, regardless of what operation it was for.
• software_updated_at: the last time software changed for the host in any way.
• last_restarted_at: the last time that the host was restarted.

List hosts

GET /api/v1/fleet/hosts

Parameters

software_id is deprecated as of Fleet 4.42. It is maintained for backwards compatibility. Please use the software_version_id instead.

If software_title_id is specified, an additional top-level key "software_title" is returned with the software title object corresponding to the software_title_id. See List software response payload for details about this object.

If software_version_id is specified, an additional top-level key "software" is returned with the software object corresponding to the software_version_id. See List software versions response payload for details about this object.

If additional_info_filters is not specified, no additional information will be returned.

If mdm_id is specified, an additional top-level key "mobile_device_management_solution" is returned with the information corresponding to the mdm_id.

If mdm_id, mdm_name, mdm_enrollment_status, os_settings, or os_settings_disk_encryption is specified, then Windows Servers are excluded from the results.

If munki_issue_id is specified, an additional top-level key munki_issue is returned with the information corresponding to the munki_issue_id.

If after is being used with created_at or updated_at, the table must be specified in order_key. Those columns become h.created_at and h.updated_at.

Example

GET /api/v1/fleet/hosts?page=0&per_page=100&order_key=hostname&query=2ce&populate_software=true&populate_policies=true

Request query parameters

{
  "page": 0,
  "per_page": 100,
  "order_key": "hostname"
}

Default response

Status: 200

{
  "hosts": [
    {
      "created_at": "2020-11-05T05:09:44Z",
      "updated_at": "2020-11-05T06:03:39Z",
      "id": 1,
      "detail_updated_at": "2020-11-05T05:09:45Z",
      "last_restarted_at": "2020-11-01T03:01:45Z",
      "software_updated_at": "2020-11-05T05:09:44Z",
      "label_updated_at": "2020-11-05T05:14:51Z",
      "policy_updated_at": "2023-06-26T18:33:15Z",
      "last_enrolled_at": "2023-02-26T22:33:12Z",
      "seen_time": "2020-11-05T06:03:39Z",
      "hostname": "2ceca32fe484",
      "uuid": "392547dc-0000-0000-a87a-d701ff75bc65",
      "platform": "centos",
      "osquery_version": "2.7.0",
      "os_version": "CentOS Linux 7",
      "build": "",
      "platform_like": "rhel fedora",
      "code_name": "",
      "uptime": 8305000000000,
      "memory": 2084032512,
      "cpu_type": "6",
      "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": "2ceca32fe484",
      "display_name": "2ceca32fe484",
      "public_ip": "",
      "primary_ip": "",
      "primary_mac": "",
      "distributed_interval": 10,
      "config_tls_refresh": 10,
      "logger_tls_period": 8,
      "additional": {},
      "status": "offline",
      "display_text": "2ceca32fe484",
      "team_id": null,
      "team_name": null,
      "gigs_disk_space_available": 174.98,
      "percent_disk_space_available": 71,
      "gigs_total_disk_space": 246,
      "pack_stats": [
        {
          "pack_id": 0,
          "pack_name": "Global",
          "type": "global",
          "query_stats": [
            {
            "scheduled_query_name": "Get recently added or removed USB drives",
            "scheduled_query_id": 5535,
            "query_name": "Get recently added or removed USB drives",
            "discard_data": false,
            "last_fetched": null,
            "automations_enabled": false,
            "description": "Returns a record every time a USB device is plugged in or removed",
            "pack_name": "Global",
            "average_memory": 434176,
            "denylisted": false,
            "executions": 2,
            "interval": 86400,
            "last_executed": "2023-11-28T00:02:07Z",
            "output_size": 891,
            "system_time": 10,
            "user_time": 6,
            "wall_time": 0
            }
          ]
        }
      ],
      "issues": {
        "failing_policies_count": 2,
        "total_issues_count": 2
      },
      "geolocation": {
        "country_iso": "US",
        "city_name": "New York",
        "geometry": {
          "type": "point",
          "coordinates": [40.6799, -74.0028]
        }
      },
      "mdm": {
        "encryption_key_available": false,
        "enrollment_status": "Pending",
        "dep_profile_error": true,
        "name": "Fleet",
        "server_url": "https://example.fleetdm.com/mdm/apple/mdm"
      },
      "software": [
        {
          "id": 1,
          "name": "glibc",
          "version": "2.12",
          "source": "rpm_packages",
          "generated_cpe": "cpe:2.3:a:gnu:glibc:2.12:*:*:*:*:*:*:*",
          "vulnerabilities": [
            {
              "cve": "CVE-2009-5155",
              "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2009-5155",
              "cvss_score": 7.5, // Fleet Premium only
              "epss_probability": 0.01537, // Fleet Premium only
              "cisa_known_exploit": false, // Fleet Premium only
              "cve_published": "2022-01-01 12:32:00", // Fleet Premium only
              "cve_description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.", // Fleet Premium only
              "resolved_in_version": "2.28" // Fleet Premium only
            }
          ],
          "installed_paths": ["/usr/lib/some-path-1"]
        }
      ],
      "policies": [
        {
          "id": 1,
          "name": "Gatekeeper enabled",
          "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
          "description": "Checks if gatekeeper is enabled on macOS devices",
          "resolution": "Fix with these steps...",
          "platform": "darwin",
          "response": "fail",
          "critical": false
        }
      ]
    }
  ]
}

Note: the response above assumes a GeoIP database is configured, otherwise the geolocation object won't be included.

Response payload with the mdm_id filter provided:

{
  "hosts": [...],
  "mobile_device_management_solution": {
    "server_url": "http://some.url/mdm",
    "name": "MDM Vendor Name",
    "id": 999
  }
}

Response payload with the munki_issue_id filter provided:

{
  "hosts": [...],
  "munki_issue": {
    "id": 1,
    "name": "Could not retrieve managed install primary manifest",
    "type": "error"
  }
}

Count hosts

GET /api/v1/fleet/hosts/count

Parameters

If additional_info_filters is not specified, no additional information will be returned.

If mdm_id, mdm_name or mdm_enrollment_status is specified, then Windows Servers are excluded from the results.

Example

GET /api/v1/fleet/hosts/count?page=0&per_page=100&order_key=hostname&query=2ce

Request query parameters

{
  "page": 0,
  "per_page": 100,
  "order_key": "hostname"
}

Default response

Status: 200

{
  "count": 123
}

Get hosts summary

Returns the count of all hosts organized by status. online_count includes all hosts currently enrolled in Fleet. offline_count includes all hosts that haven't checked into Fleet recently. mia_count includes all hosts that haven't been seen by Fleet in more than 30 days. new_count includes the hosts that have been enrolled to Fleet in the last 24 hours.

GET /api/v1/fleet/host_summary

Parameters

Example

GET /api/v1/fleet/host_summary?team_id=1&low_disk_space=32

Default response

Status: 200

{
  "team_id": 1,
  "totals_hosts_count": 2408,
  "online_count": 2267,
  "offline_count": 141,
  "mia_count": 0,
  "missing_30_days_count": 0,
  "new_count": 0,
  "all_linux_count": 1204,
  "low_disk_space_count": 12,
  "builtin_labels": [
    {
      "id": 6,
      "name": "All Hosts",
      "description": "All hosts which have enrolled in Fleet",
      "label_type": "builtin"
    },
    {
      "id": 7,
      "name": "macOS",
      "description": "All macOS hosts",
      "label_type": "builtin"
    },
    {
      "id": 8,
      "name": "Ubuntu Linux",
      "description": "All Ubuntu hosts",
      "label_type": "builtin"
    },
    {
      "id": 9,
      "name": "CentOS Linux",
      "description": "All CentOS hosts",
      "label_type": "builtin"
    },
    {
      "id": 10,
      "name": "MS Windows",
      "description": "All Windows hosts",
      "label_type": "builtin"
    },
    {
      "id": 11,
      "name": "Red Hat Linux",
      "description": "All Red Hat Enterprise Linux hosts",
      "label_type": "builtin"
    },
    {
      "id": 12,
      "name": "All Linux",
      "description": "All Linux distributions",
      "label_type": "builtin"
    }
  ],
  "platforms": [
    {
      "platform": "chrome",
      "hosts_count": 1234
    },
    {
      "platform": "darwin",
      "hosts_count": 1234
    },
    {
      "platform": "rhel",
      "hosts_count": 1234
    },
    {
      "platform": "ubuntu",
      "hosts_count": 12044
    },
    {
      "platform": "windows",
      "hosts_count": 12044
    }

  ]
}

Get host

Returns the information of the specified host.

GET /api/v1/fleet/hosts/:id

Parameters

Example

GET /api/v1/fleet/hosts/121

Default response

Status: 200

{
  "host": {
    "created_at": "2021-08-19T02:02:22Z",
    "updated_at": "2021-08-19T21:14:58Z",
    "software": [
      {
        "id": 408,
        "name": "osquery",
        "version": "4.5.1",
        "source": "rpm_packages",
        "browser": "",
        "generated_cpe": "",
        "vulnerabilities": null,
        "installed_paths": ["/usr/lib/some-path-1"]
      },
      {
        "id": 1146,
        "name": "tar",
        "version": "1.30",
        "source": "rpm_packages",
        "browser": "",
        "generated_cpe": "",
        "vulnerabilities": null
      },
      {
        "id": 321,
        "name": "SomeApp.app",
        "version": "1.0",
        "source": "apps",
        "browser": "",
        "bundle_identifier": "com.some.app",
        "last_opened_at": "2021-08-18T21:14:00Z",
        "generated_cpe": "",
        "vulnerabilities": null,
        "installed_paths": ["/usr/lib/some-path-2"]
      }
    ],
    "id": 1,
    "detail_updated_at": "2021-08-19T21:07:53Z",
    "last_restarted_at": "2020-11-01T03:01:45Z",
    "software_updated_at": "2020-11-05T05:09:44Z",
    "label_updated_at": "2021-08-19T21:07:53Z",
    "policy_updated_at": "2023-06-26T18:33:15Z",
    "last_enrolled_at": "2021-08-19T02:02:22Z",
    "seen_time": "2021-08-19T21:14:58Z",
    "refetch_requested": false,
    "hostname": "23cfc9caacf0",
    "uuid": "309a4b7d-0000-0000-8e7f-26ae0815ede8",
    "platform": "rhel",
    "osquery_version": "4.5.1",
    "os_version": "CentOS Linux 8.3.2011",
    "build": "",
    "platform_like": "rhel",
    "code_name": "",
    "uptime": 210671000000000,
    "memory": 16788398080,
    "cpu_type": "x86_64",
    "cpu_subtype": "158",
    "cpu_brand": "Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz",
    "cpu_physical_cores": 12,
    "cpu_logical_cores": 12,
    "hardware_vendor": "",
    "hardware_model": "",
    "hardware_version": "",
    "hardware_serial": "",
    "computer_name": "23cfc9caacf0",
    "display_name": "23cfc9caacf0",
    "public_ip": "",
    "primary_ip": "172.27.0.6",
    "primary_mac": "02:42:ac:1b:00:06",
    "distributed_interval": 10,
    "config_tls_refresh": 10,
    "logger_tls_period": 10,
    "team_id": null,
    "pack_stats": null,
    "team_name": null,
    "additional": {},
    "gigs_disk_space_available": 46.1,
    "percent_disk_space_available": 74,
    "gigs_total_disk_space": 160,
    "disk_encryption_enabled": true,
    "users": [
      {
        "uid": 0,
        "username": "root",
        "type": "",
        "groupname": "root",
        "shell": "/bin/bash"
      },
      {
        "uid": 1,
        "username": "bin",
        "type": "",
        "groupname": "bin",
        "shell": "/sbin/nologin"
      }
    ],
    "labels": [
      {
        "created_at": "2021-08-19T02:02:17Z",
        "updated_at": "2021-08-19T02:02:17Z",
        "id": 6,
        "name": "All Hosts",
        "description": "All hosts which have enrolled in Fleet",
        "query": "SELECT 1;",
        "platform": "",
        "label_type": "builtin",
        "label_membership_type": "dynamic"
      },
      {
        "created_at": "2021-08-19T02:02:17Z",
        "updated_at": "2021-08-19T02:02:17Z",
        "id": 9,
        "name": "CentOS Linux",
        "description": "All CentOS hosts",
        "query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'",
        "platform": "",
        "label_type": "builtin",
        "label_membership_type": "dynamic"
      },
      {
        "created_at": "2021-08-19T02:02:17Z",
        "updated_at": "2021-08-19T02:02:17Z",
        "id": 12,
        "name": "All Linux",
        "description": "All Linux distributions",
        "query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';",
        "platform": "",
        "label_type": "builtin",
        "label_membership_type": "dynamic"
      }
    ],
    "packs": [],
    "status": "online",
    "display_text": "23cfc9caacf0",
    "policies": [
      {
        "id": 2,
        "name": "SomeQuery2",
        "query": "SELECT * FROM bar;",
        "description": "this is another query",
        "resolution": "fix with these other steps...",
        "platform": "darwin",
        "response": "fail",
        "critical": false
      },
      {
        "id": 3,
        "name": "SomeQuery3",
        "query": "SELECT * FROM baz;",
        "description": "",
        "resolution": "",
        "platform": "",
        "response": "",
        "critical": false
      },
      {
        "id": 1,
        "name": "SomeQuery",
        "query": "SELECT * FROM foo;",
        "description": "this is a query",
        "resolution": "fix with these steps...",
        "platform": "windows,linux",
        "response": "pass",
        "critical": false
      }
    ],
    "issues": {
      "failing_policies_count": 2,
      "total_issues_count": 2
    },
    "batteries": [
      {
        "cycle_count": 999,
        "health": "Normal"
      }
    ],
    "geolocation": {
      "country_iso": "US",
      "city_name": "New York",
      "geometry": {
        "type": "point",
        "coordinates": [40.6799, -74.0028]
      }
    },
    "mdm": {
      "encryption_key_available": false,
      "enrollment_status": null,
      "name": "",
      "server_url": null,
      "device_status": "unlocked",
      "pending_action": "",
      "macos_settings": {
        "disk_encryption": null,
        "action_required": null
      },
      "macos_setup": {
        "bootstrap_package_status": "installed",
        "detail": "",
        "bootstrap_package_name": "test.pkg"
      },
      "os_settings": {
        "disk_encryption": {
          "status": null,
          "detail": ""
        }
      },
      "profiles": [
        {
          "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24",
          "name": "profile1",
          "status": "verifying",
          "operation_type": "install",
          "detail": ""
        }
      ]
    }
  }
}

Note: the response above assumes a GeoIP database is configured, otherwise the geolocation object won't be included.

Note: installed_paths may be blank depending on installer package. For example, on Linux, RPM-installed packages do not provide installed path information.

Get host by identifier

Returns the information of the host specified using the uuid, hardware_serial, osquery_host_id, hostname, or node_key as an identifier.

If hostname is specified when there is more than one host with the same hostname, the endpoint returns the first matching host. In Fleet, hostnames are fully qualified domain names (FQDNs).

GET /api/v1/fleet/hosts/identifier/:identifier

Parameters

Example

GET /api/v1/fleet/hosts/identifier/392547dc-0000-0000-a87a-d701ff75bc65

Default response

Status: 200

{
  "host": {
    "created_at": "2022-02-10T02:29:13Z",
    "updated_at": "2022-10-14T17:07:11Z",
    "software": [
      {
        "id": 16923,
        "name": "Automat",
        "version": "0.8.0",
        "source": "python_packages",
        "browser": "",
        "generated_cpe": "",
        "vulnerabilities": null,
        "installed_paths": ["/usr/lib/some_path/"]
      }
    ],
    "id": 33,
    "detail_updated_at": "2022-10-14T17:07:12Z",
    "label_updated_at": "2022-10-14T17:07:12Z",
    "policy_updated_at": "2022-10-14T17:07:12Z",
    "last_enrolled_at": "2022-02-10T02:29:13Z",
    "software_updated_at": "2020-11-05T05:09:44Z",
    "seen_time": "2022-10-14T17:45:41Z",
    "refetch_requested": false,
    "hostname": "23cfc9caacf0",
    "uuid": "392547dc-0000-0000-a87a-d701ff75bc65",
    "platform": "ubuntu",
    "osquery_version": "5.5.1",
    "os_version": "Ubuntu 20.04.3 LTS",
    "build": "",
    "platform_like": "debian",
    "code_name": "focal",
    "uptime": 20807520000000000,
    "memory": 1024360448,
    "cpu_type": "x86_64",
    "cpu_subtype": "63",
    "cpu_brand": "DO-Regular",
    "cpu_physical_cores": 1,
    "cpu_logical_cores": 1,
    "hardware_vendor": "",
    "hardware_model": "",
    "hardware_version": "",
    "hardware_serial": "",
    "computer_name": "23cfc9caacf0",
    "public_ip": "",
    "primary_ip": "172.27.0.6",
    "primary_mac": "02:42:ac:1b:00:06",
    "distributed_interval": 10,
    "config_tls_refresh": 60,
    "logger_tls_period": 10,
    "team_id": 2,
    "pack_stats": [
      {
        "pack_id": 1,
        "pack_name": "Global",
        "type": "global",
        "query_stats": [
          {
            "scheduled_query_name": "Get running processes (with user_name)",
            "scheduled_query_id": 49,
            "query_name": "Get running processes (with user_name)",
            "pack_name": "Global",
            "pack_id": 1,
            "average_memory": 260000,
            "denylisted": false,
            "executions": 1,
            "interval": 86400,
            "last_executed": "2022-10-14T10:00:01Z",
            "output_size": 198,
            "system_time": 20,
            "user_time": 80,
            "wall_time": 0
          }
        ]
      }
    ],
    "team_name": null,
    "gigs_disk_space_available": 19.29,
    "percent_disk_space_available": 74,
    "gigs_total_disk_space": 192,
    "issues": {
        "total_issues_count": 0,
        "failing_policies_count": 0
    },
    "labels": [
      {
        "created_at": "2021-09-14T05:11:02Z",
        "updated_at": "2021-09-14T05:11:02Z",
        "id": 12,
        "name": "All Linux",
        "description": "All Linux distributions",
        "query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';",
        "platform": "",
        "label_type": "builtin",
        "label_membership_type": "dynamic"
      }
    ],
    "packs": [
      {
        "created_at": "2021-09-17T05:28:54Z",
        "updated_at": "2021-09-17T05:28:54Z",
        "id": 1,
        "name": "Global",
        "description": "Global pack",
        "disabled": false,
        "type": "global",
        "labels": null,
        "label_ids": null,
        "hosts": null,
        "host_ids": null,
        "teams": null,
        "team_ids": null
      }
    ],
    "policies": [
      {
        "id": 142,
        "name": "Full disk encryption enabled (macOS)",
        "query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT '' AND filevault_status = 'on' LIMIT 1;",
        "description": "Checks to make sure that full disk encryption (FileVault) is enabled on macOS devices.",
        "author_id": 31,
        "author_name": "",
        "author_email": "",
        "team_id": null,
        "resolution": "To enable full disk encryption, on the failing device, select System Preferences > Security & Privacy > FileVault > Turn On FileVault.",
        "platform": "darwin,linux",
        "created_at": "2022-09-02T18:52:19Z",
        "updated_at": "2022-09-02T18:52:19Z",
        "response": "fail",
        "critical": false
      }
    ],
    "batteries": [
      {
        "cycle_count": 999,
        "health": "Normal"
      }
    ],
    "geolocation": {
      "country_iso": "US",
      "city_name": "New York",
      "geometry": {
        "type": "point",
        "coordinates": [40.6799, -74.0028]
      }
    },
    "status": "online",
    "display_text": "dogfood-ubuntu-box",
    "display_name": "dogfood-ubuntu-box",
    "mdm": {
      "encryption_key_available": false,
      "enrollment_status": null,
      "name": "",
      "server_url": null,
      "device_status": "unlocked",
      "pending_action": "lock",
      "macos_settings": {
        "disk_encryption": null,
        "action_required": null
      },
      "macos_setup": {
        "bootstrap_package_status": "installed",
        "detail": ""
      },
      "os_settings": {
        "disk_encryption": {
          "status": null,
          "detail": ""
        }
      },
      "profiles": [
        {
          "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24",
          "name": "profile1",
          "status": "verifying",
          "operation_type": "install",
          "detail": ""
        }
      ]
    }
  }
}

Note: the response above assumes a GeoIP database is configured, otherwise the geolocation object won't be included.

Note: installed_paths may be blank depending on installer package. For example, on Linux, RPM-installed packages do not provide installed path information.

Get host by device token

Returns a subset of information about the host specified by token. To get all information about a host, use the "Get host" endpoint here.

This is the API route used by the My device page in Fleet desktop to display information about the host to the end user.

GET /api/v1/fleet/device/:token

Parameters

Example

GET /api/v1/fleet/device/abcdef012456789

Default response

Status: 200

{
  "host": {
    "created_at": "2021-08-19T02:02:22Z",
    "updated_at": "2021-08-19T21:14:58Z",
    "software": [
      {
        "id": 408,
        "name": "osquery",
        "version": "4.5.1",
        "source": "rpm_packages",
        "browser": "",
        "generated_cpe": "",
        "vulnerabilities": null
      },
      {
        "id": 1146,
        "name": "tar",
        "version": "1.30",
        "source": "rpm_packages",
        "browser": "",
        "generated_cpe": "",
        "vulnerabilities": null
      },
      {
        "id": 321,
        "name": "SomeApp.app",
        "version": "1.0",
        "source": "apps",
        "browser": "",
        "bundle_identifier": "com.some.app",
        "last_opened_at": "2021-08-18T21:14:00Z",
        "generated_cpe": "",
        "vulnerabilities": null
      }
    ],
    "id": 1,
    "detail_updated_at": "2021-08-19T21:07:53Z",
    "label_updated_at": "2021-08-19T21:07:53Z",
    "last_enrolled_at": "2021-08-19T02:02:22Z",
    "seen_time": "2021-08-19T21:14:58Z",
    "refetch_requested": false,
    "hostname": "23cfc9caacf0",
    "uuid": "309a4b7d-0000-0000-8e7f-26ae0815ede8",
    "platform": "rhel",
    "osquery_version": "4.5.1",
    "os_version": "CentOS Linux 8.3.2011",
    "build": "",
    "platform_like": "rhel",
    "code_name": "",
    "uptime": 210671000000000,
    "memory": 16788398080,
    "cpu_type": "x86_64",
    "cpu_subtype": "158",
    "cpu_brand": "Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz",
    "cpu_physical_cores": 12,
    "cpu_logical_cores": 12,
    "hardware_vendor": "",
    "hardware_model": "",
    "hardware_version": "",
    "hardware_serial": "",
    "computer_name": "23cfc9caacf0",
    "display_name": "23cfc9caacf0",
    "public_ip": "",
    "primary_ip": "172.27.0.6",
    "primary_mac": "02:42:ac:1b:00:06",
    "distributed_interval": 10,
    "config_tls_refresh": 10,
    "logger_tls_period": 10,
    "team_id": null,
    "pack_stats": null,
    "team_name": null,
    "additional": {},
    "gigs_disk_space_available": 46.1,
    "percent_disk_space_available": 74,
    "gigs_total_disk_space": 160,
    "disk_encryption_enabled": true,
    "dep_assigned_to_fleet": false,
    "users": [
      {
        "uid": 0,
        "username": "root",
        "type": "",
        "groupname": "root",
        "shell": "/bin/bash"
      },
      {
        "uid": 1,
        "username": "bin",
        "type": "",
        "groupname": "bin",
        "shell": "/sbin/nologin"
      }
    ],
    "labels": [
      {
        "created_at": "2021-08-19T02:02:17Z",
        "updated_at": "2021-08-19T02:02:17Z",
        "id": 6,
        "name": "All Hosts",
        "description": "All hosts which have enrolled in Fleet",
        "query": "SELECT 1;",
        "platform": "",
        "label_type": "builtin",
        "label_membership_type": "dynamic"
      },
      {
        "created_at": "2021-08-19T02:02:17Z",
        "updated_at": "2021-08-19T02:02:17Z",
        "id": 9,
        "name": "CentOS Linux",
        "description": "All CentOS hosts",
        "query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'",
        "platform": "",
        "label_type": "builtin",
        "label_membership_type": "dynamic"
      },
      {
        "created_at": "2021-08-19T02:02:17Z",
        "updated_at": "2021-08-19T02:02:17Z",
        "id": 12,
        "name": "All Linux",
        "description": "All Linux distributions",
        "query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';",
        "platform": "",
        "label_type": "builtin",
        "label_membership_type": "dynamic"
      }
    ],
    "packs": [],
    "status": "online",
    "display_text": "23cfc9caacf0",
    "batteries": [
      {
        "cycle_count": 999,
        "health": "Good"
      }
    ],
    "mdm": {
      "encryption_key_available": false,
      "enrollment_status": null,
      "name": "",
      "server_url": null,
      "macos_settings": {
        "disk_encryption": null,
        "action_required": null
      },
      "macos_setup": {
        "bootstrap_package_status": "installed",
        "detail": "",
        "bootstrap_package_name": "test.pkg"
      },
      "os_settings": {
        "disk_encryption": {
          "status": null,
          "detail": ""
        }
      },
      "profiles": [
        {
          "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24",
          "name": "profile1",
          "status": "verifying",
          "operation_type": "install",
          "detail": ""
        }
      ]
    }
  },
  "org_logo_url": "https://example.com/logo.jpg",
  "license": {
    "tier": "free",
    "expiration": "2031-01-01T00:00:00Z"
  },
  "global_config": {
    "mdm": {
      "enabled_and_configured": false
    }
  }
}

Delete host

Deletes the specified host from Fleet. Note that a deleted host will fail authentication with the previous node key, and in most osquery configurations will attempt to re-enroll automatically. If the host still has a valid enroll secret, it will re-enroll successfully.

DELETE /api/v1/fleet/hosts/:id

Parameters

Example

DELETE /api/v1/fleet/hosts/121

Default response

Status: 200

Refetch host

Flags the host details, labels and policies to be refetched the next time the host checks in for distributed queries. Note that we cannot be certain when the host will actually check in and update the query results. Further requests to the host APIs will indicate that the refetch has been requested through the refetch_requested field on the host object.

POST /api/v1/fleet/hosts/:id/refetch

Parameters

Example

POST /api/v1/fleet/hosts/121/refetch

Default response

Status: 200

Transfer hosts to a team

Available in Fleet Premium

POST /api/v1/fleet/hosts/transfer

Parameters

Example

POST /api/v1/fleet/hosts/transfer

Request body

{
  "team_id": 1,
  "hosts": [3, 2, 4, 6, 1, 5, 7]
}

Default response

Status: 200

Transfer hosts to a team by filter

Available in Fleet Premium

POST /api/v1/fleet/hosts/transfer/filter

Parameters

Example

POST /api/v1/fleet/hosts/transfer/filter

Request body

{
  "team_id": 1,
  "filters": {
    "status": "online",
    "team_id": 2,
  }
}

Default response

Status: 200

Bulk delete hosts by filter or ids

POST /api/v1/fleet/hosts/delete

Parameters

Either ids or filters are required.

Request (ids is specified):

{
  "ids": [1]
}

Request (filters is specified):

{
  "filters": {
    "status": "online",
    "label_id": 1,
    "team_id": 1,
    "query": "abc"
  }
}

Request (filters is specified and empty, to delete all hosts):

{
  "filters": {}
}

Example

POST /api/v1/fleet/hosts/delete

Request body

{
  "filters": {
    "status": "online",
    "team_id": 1
  }
}

Default response

Status: 200

Get human-device mapping

Returns the end user's email(s) they use to log in to their Identity Provider (IdP) and Google Chrome profile.

Also returns the custom email that's set via the PUT /api/v1/fleet/hosts/:id/device_mapping endpoint (docs here)

Note that IdP email is only supported on macOS hosts. It's collected once, during automatic enrollment (DEP), only if the end user authenticates with the IdP and the DEP profile has await_device_configured set to true.

GET /api/v1/fleet/hosts/:id/device_mapping

Parameters

Example

GET /api/v1/fleet/hosts/1/device_mapping

Default response

Status: 200

{
  "host_id": 1,
  "device_mapping": [
    {
      "email": "[email protected]",
      "source": "identity_provider"
    },
    {
      "email": "[email protected]",
      "source": "google_chrome_profiles"
    },
    {
      "email": "[email protected]",
      "source": "custom"
    }
  ]
}

---

Update custom human-device mapping

PUT /api/v1/fleet/hosts/:id/device_mapping

Updates the email for the custom data source in the human-device mapping. This source can only have one email.

Parameters

Example

PUT /api/v1/fleet/hosts/1/device_mapping

Request body

{
  "email": "[email protected]"
}

Default response

Status: 200

{
  "host_id": 1,
  "device_mapping": [
    {
      "email": "[email protected]",
      "source": "identity_provider"
    },
    {
      "email": "[email protected]",
      "source": "google_chrome_profiles"
    },
    {
      "email": "[email protected]",
      "source": "custom"
    }
  ]
}

Get host's device health report

Retrieves information about a single host's device health.

This report includes a subset of host vitals, and simplified policy and vulnerable software information. Data is cached to preserve performance. To get all up-to-date information about a host, use the "Get host" endpoint here.

GET /api/v1/fleet/hosts/:id/health

Parameters

Example

GET /api/v1/fleet/hosts/1/health

Default response

Status: 200

{
  "host_id": 1,
  "health": {
    "updated_at": "2023-09-16T18:52:19Z",
    "os_version": "CentOS Linux 8.3.2011",
    "disk_encryption_enabled": true,
    "failing_policies": [
      {
        "id": 123,
        "name": "Google Chrome is up to date",
      }
    ],
    "vulnerable_software": [
      {
        "id": 321,
        "name": "Firefox.app",
        "version": "116.0.3",
      }
    ]
  }
}

---

Get host's mobile device management (MDM) information

Currently supports Windows and MacOS. On MacOS this requires the macadmins osquery extension which comes bundled in Fleet's osquery installers.

Retrieves a host's MDM enrollment status and MDM server URL.

If the host exists but is not enrolled to an MDM server, then this API returns null.

GET /api/v1/fleet/hosts/:id/mdm

Parameters

Example

GET /api/v1/fleet/hosts/32/mdm

Default response

Status: 200

{
  "enrollment_status": "On (automatic)",
  "server_url": "some.mdm.com",
  "name": "Some MDM",
  "id": 3
}

---

Get mobile device management (MDM) summary

Currently supports Windows and MacOS. On MacOS this requires the macadmins osquery extension which comes bundled in Fleet's osquery installers.

Retrieves MDM enrollment summary. Windows servers are excluded from the aggregated data.

GET /api/v1/fleet/hosts/summary/mdm

Parameters

A team_id of 0 returns the statistics for hosts that are not part of any team. A null or missing team_id returns statistics for all hosts regardless of the team.

Example

GET /api/v1/fleet/hosts/summary/mdm?team_id=1&platform=windows

Default response

Status: 200

{
  "counts_updated_at": "2021-03-21T12:32:44Z",
  "mobile_device_management_enrollment_status": {
    "enrolled_manual_hosts_count": 0,
    "enrolled_automated_hosts_count": 2,
    "unenrolled_hosts_count": 0,
    "hosts_count": 2
  },
  "mobile_device_management_solution": [
    {
      "id": 2,
      "name": "Solution1",
      "server_url": "solution1.com",
      "hosts_count": 1
    },
    {
      "id": 3,
      "name": "Solution2",
      "server_url": "solution2.com",
      "hosts_count": 1
    }
  ]
}

---

Get host's mobile device management (MDM) and Munki information

Retrieves a host's MDM enrollment status, MDM server URL, and Munki version.

GET /api/v1/fleet/hosts/:id/macadmins

Parameters

Example

GET /api/v1/fleet/hosts/32/macadmins

Default response

Status: 200

{
  "macadmins": {
    "munki": {
      "version": "1.2.3"
    },
    "munki_issues": [
      {
        "id": 1,
        "name": "Could not retrieve managed install primary manifest",
        "type": "error",
        "created_at": "2022-08-01T05:09:44Z"
      },
      {
        "id": 2,
        "name": "Could not process item Figma for optional install. No pkginfo found in catalogs: release",
        "type": "warning",
        "created_at": "2022-08-01T05:09:44Z"
      }
    ],
    "mobile_device_management": {
      "enrollment_status": "On (automatic)",
      "server_url": "http://some.url/mdm",
      "name": "MDM Vendor Name",
      "id": 999
    }
  }
}

---

Get aggregated host's macadmin mobile device management (MDM) and Munki information

Requires the macadmins osquery extension which comes bundled in Fleet's osquery installers. Currently supported only on macOS.

Retrieves aggregated host's MDM enrollment status and Munki versions.

GET /api/v1/fleet/macadmins

Parameters

A team_id of 0 returns the statistics for hosts that are not part of any team. A null or missing team_id returns statistics for all hosts regardless of the team.

Example

GET /api/v1/fleet/macadmins

Default response

Status: 200

{
  "macadmins": {
    "counts_updated_at": "2021-03-21T12:32:44Z",
    "munki_versions": [
      {
        "version": "5.5",
        "hosts_count": 8360
      },
      {
        "version": "5.4",
        "hosts_count": 1700
      },
      {
        "version": "5.3",
        "hosts_count": 400
      },
      {
        "version": "5.2.3",
        "hosts_count": 112
      },
      {
        "version": "5.2.2",
        "hosts_count": 50
      }
    ],
    "munki_issues": [
      {
        "id": 1,
        "name": "Could not retrieve managed install primary manifest",
        "type": "error",
        "hosts_count": 2851
      },
      {
        "id": 2,
        "name": "Could not process item Figma for optional install. No pkginfo found in catalogs: release",
        "type": "warning",
        "hosts_count": 1983
      }
    ],
    "mobile_device_management_enrollment_status": {
      "enrolled_manual_hosts_count": 124,
      "enrolled_automated_hosts_count": 124,
      "unenrolled_hosts_count": 112
    },
    "mobile_device_management_solution": [
      {
        "id": 1,
        "name": "SimpleMDM",
        "hosts_count": 8360,
        "server_url": "https://a.simplemdm.com/mdm"
      },
      {
        "id": 2,
        "name": "Intune",
        "hosts_count": 1700,
        "server_url": "https://enrollment.manage.microsoft.com"
      }
    ]
  }
}

List host OS versions

Retrieves the aggregated host OS versions information.

GET /api/v1/fleet/os_versions

Parameters

Default response

Status: 200

{
  "count": 1
  "counts_updated_at": "2023-12-06T22:17:30Z",
  "os_versions": [
    {
      "os_version_id": 123,
      "hosts_count": 21,
      "name": "Microsoft Windows 11 Pro 23H2 10.0.22621.1234",
      "name_only": "Microsoft Windows 11 Pro 23H2",
      "version": "10.0.22621.1234",
      "platform": "windows",
      "generated_cpes": [],
      "vulnerabilities": [
        {
          "cve": "CVE-2022-30190",
          "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190",
          "cvss_score": 7.8,// Available in Fleet Premium
          "epss_probability": 0.9729,// Available in Fleet Premium
          "cisa_known_exploit": false,// Available in Fleet Premium
          "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium
          "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability.",// Available in Fleet Premium
          "resolved_in_version": ""// Available in Fleet Premium
        }
      ]
    }
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

OS vulnerability data is currently available for Windows and macOS. For other platforms, vulnerabilities will be an empty array:

{
  "hosts_count": 1,
  "name": "CentOS Linux 7.9.2009",
  "name_only": "CentOS",
  "version": "7.9.2009",
  "platform": "rhel",
  "generated_cpes": [],
  "vulnerabilities": []
}

Get host OS version

Retrieves information about the specified OS version.

GET /api/v1/fleet/os_versions/:id

Parameters

Default response

Status: 200

{
  "counts_updated_at": "2023-12-06T22:17:30Z",
  "os_version": {
    "id": 123,
    "hosts_count": 21,
    "name": "Microsoft Windows 11 Pro 23H2 10.0.22621.1234",
    "name_only": "Microsoft Windows 11 Pro 23H2",
    "version": "10.0.22621.1234",
    "platform": "windows",
    "generated_cpes": [],
    "vulnerabilities": [
      {
        "cve": "CVE-2022-30190",
        "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190",
        "cvss_score": 7.8,// Available in Fleet Premium
        "epss_probability": 0.9729,// Available in Fleet Premium
        "cisa_known_exploit": false,// Available in Fleet Premium
        "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium
        "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability.",// Available in Fleet Premium
        "resolved_in_version": ""// Available in Fleet Premium
      }
    ]
  }
}

OS vulnerability data is currently available for Windows and macOS. For other platforms, vulnerabilities will be an empty array:

{
  "id": 321,
  "hosts_count": 1,
  "name": "CentOS Linux 7.9.2009",
  "name_only": "CentOS",
  "version": "7.9.2009",
  "platform": "rhel",
  "generated_cpes": [],
  "vulnerabilities": []
}

Get host's scripts

GET /api/v1/fleet/hosts/:id/scripts

Parameters

Example

GET /api/v1/fleet/hosts/123/scripts

Default response

Status: 200

  "scripts": [
    {
      "script_id": 3,
      "name": "remove-zoom-artifacts.sh",
      "last_execution": {
        "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002",
        "executed_at": "2021-12-15T15:23:57Z",
        "status": "error"
      }
    },
    {
      "script_id": 5,
      "name": "set-timezone.sh",
      "last_execution": {
        "id": "e797d6c6-3aae-11ee-be56-0242ac120002",
        "executed_at": "2021-12-15T15:23:57Z",
        "status": "pending"
      }
    },
    {
      "script_id": 8,
      "name": "uninstall-zoom.sh",
      "last_execution": {
        "id": "e797d6c6-3aae-11ee-be56-0242ac120002",
        "executed_at": "2021-12-15T15:23:57Z",
        "status": "ran"
      }
    }
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

Get hosts report in CSV

Returns the list of hosts corresponding to the search criteria in CSV format, ready for download when requested by a web browser.

GET /api/v1/fleet/hosts/report

Parameters

If mdm_id, mdm_name or mdm_enrollment_status is specified, then Windows Servers are excluded from the results.

Example

GET /api/v1/fleet/hosts/report?software_id=123&format=csv&columns=hostname,primary_ip,platform

Default response

Status: 200

created_at,updated_at,id,detail_updated_at,label_updated_at,policy_updated_at,last_enrolled_at,seen_time,refetch_requested,hostname,uuid,platform,osquery_version,os_version,build,platform_like,code_name,uptime,memory,cpu_type,cpu_subtype,cpu_brand,cpu_physical_cores,cpu_logical_cores,hardware_vendor,hardware_model,hardware_version,hardware_serial,computer_name,primary_ip_id,primary_ip,primary_mac,distributed_interval,config_tls_refresh,logger_tls_period,team_id,team_name,gigs_disk_space_available,percent_disk_space_available,gigs_total_disk_space,issues,device_mapping,status,display_text
2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,1,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,false,foo.local0,a4fc55a1-b5de-409c-a2f4-441f564680d3,debian,,,,,,0s,0,,,,0,0,,,,,,,,,0,0,0,,,0,0,0,0,,,,
2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:22:56Z,false,foo.local1,689539e5-72f0-4bf7-9cc5-1530d3814660,rhel,,,,,,0s,0,,,,0,0,,,,,,,,,0,0,0,,,0,0,0,0,,,,
2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,3,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:23:56Z,2022-03-15T17:21:56Z,false,foo.local2,48ebe4b0-39c3-4a74-a67f-308f7b5dd171,linux,,,,,,0s,0,,,,0,0,,,,,,,,,0,0,0,,,0,0,0,0,,,,

Get host's disk encryption key

Retrieves the disk encryption key for a host.

Requires that disk encryption is enforced and the host has MDM turned on.

GET /api/v1/fleet/mdm/hosts/:id/encryption_key

Parameters

Example

GET /api/v1/fleet/mdm/hosts/8/encryption_key

Default response

Status: 200

{
  "host_id": 8,
  "encryption_key": {
    "key": "5ADZ-HTZ8-LJJ4-B2F8-JWH3-YPBT",
    "updated_at": "2022-12-01T05:31:43Z"
  }
}

Get configuration profiles assigned to a host

Requires Fleet's MDM properly enabled and configured.

Retrieves a list of the configuration profiles assigned to a host.

GET /api/v1/fleet/mdm/hosts/:id/profiles

Parameters

Example

GET /api/v1/fleet/mdm/hosts/8/profiles

Default response

Status: 200

{
  "host_id": 8,
  "profiles": [
    {
      "profile_uuid": "bc84dae7-396c-4e10-9d45-5768bce8b8bd",
      "team_id": 0,
      "name": "Example profile",
      "identifier": "com.example.profile",
      "created_at": "2023-03-31T00:00:00Z",
      "updated_at": "2023-03-31T00:00:00Z",
      "checksum": "dGVzdAo="
    }
  ]
}

Lock host

Available in Fleet Premium

Sends a command to lock the specified macOS, Linux, or Windows host. The host is locked once it comes online.

To lock a macOS host, the host must have MDM turned on. To lock a Windows or Linux host, the host must have scripts enabled.

POST /api/v1/fleet/hosts/:id/lock

Parameters

Example

POST /api/v1/fleet/hosts/123/lock

Default response

Status: 204

Unlock host

Available in Fleet Premium

Sends a command to unlock the specified Windows or Linux host, or retrieves the unlock PIN for a macOS host.

To unlock a Windows or Linux host, the host must have scripts enabled.

POST /api/v1/fleet/hosts/:id/unlock

Parameters

Example

POST /api/v1/fleet/hosts/:id/unlock

Default response (Windows or Linux hosts)

Status: 204

Default response (macOS hosts)

Status: 200

{
  "host_id": 8,
  "unlock_pin": "123456"
}

Wipe host

Sends a command to wipe the specified macOS, Windows, or Linux host. The host is wiped once it comes online.

To wipe a macOS or Windows host, the host must have MDM turned on. To lock a Linux host, the host must have scripts enabled.

POST /api/v1/fleet/hosts/:id/wipe

Parameters

Example

POST /api/v1/fleet/hosts/123/wipe

Default response

Status: 204

Get host's past activity

GET /api/v1/fleet/hosts/:id/activities

Parameters

Example

GET /api/v1/fleet/hosts/12/activities

Default response

Status: 200

{
  "activities": [
    {
      "created_at": "2023-07-27T14:35:08Z",
      "id": 2,
      "actor_full_name": "Anna",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "ran_script",
      "details": {
        "host_id": 1,
        "host_display_name": "Steve's MacBook Pro",
        "script_name": "set-timezones.sh",
        "script_execution_id": "d6cffa75-b5b5-41ef-9230-15073c8a88cf",
        "async": true
      },
    },
    {
      "created_at": "2021-07-27T13:25:21Z",
      "id": 1,
      "actor_full_name": "Bob",
      "actor_id": 2,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "ran_script",
      "details": {
        "host_id": 1,
        "host_display_name": "Steve's MacBook Pro",
        "script_name": "",
        "script_execution_id": "y3cffa75-b5b5-41ef-9230-15073c8a88cf",
        "async": false
      },
    },
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

Get host's upcoming activity

GET /api/v1/fleet/hosts/:id/activities/upcoming

Parameters

Example

GET /api/v1/fleet/hosts/12/activities/upcoming

Default response

Status: 200

{
  "count": 2,
  "activities": [
    {
      "created_at": "2023-07-27T14:35:08Z",
      "uuid": "d6cffa75-b5b5-41ef-9230-15073c8a88cf",
      "actor_full_name": "Marko",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "ran_script",
      "details": {
        "host_id": 1,
        "host_display_name": "Steve's MacBook Pro",
        "script_name": "set-timezones.sh",
        "script_execution_id": "d6cffa75-b5b5-41ef-9230-15073c8a88cf",
        "async": true
      },
    },
    {
      "created_at": "2021-07-27T13:25:21Z",
      "uuid": "y3cffa75-b5b5-41ef-9230-15073c8a88cf",
      "actor_full_name": "Rachael",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "[email protected]",
      "type": "ran_script",
      "details": {
        "host_id": 1,
        "host_display_name": "Steve's MacBook Pro",
        "script_name": "",
        "script_execution_id": "y3cffa75-b5b5-41ef-9230-15073c8a88cf",
        "async": false
      },
    },
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

Live query one host (ad-hoc)

Runs an ad-hoc live query against the specified host and responds with the results.

The live query will stop if the targeted host is offline, or if the query times out. Timeouts happen if the host hasn't responded after the configured FLEET_LIVE_QUERY_REST_PERIOD (default 25 seconds) or if the distributed_interval agent option (default 10 seconds) is higher than the FLEET_LIVE_QUERY_REST_PERIOD.

POST /api/v1/fleet/hosts/:id/query

Parameters

Example

POST /api/v1/fleet/hosts/123/query

Request body

{
  "query": "SELECT model, vendor FROM usb_devices;"
}

Default response

Status: 200

{
  "host_id": 123,
  "query": "SELECT model, vendor FROM usb_devices;",
  "status": "online", // "online" or "offline"
  "error": null,
  "rows": [
    {
      "model": "USB2.0 Hub",
      "vendor": "VIA Labs, Inc."
    }
  ]
}

Note that if the host is online and the query times out, this endpoint will return an error and rows will be null. If the host is offline, no error will be returned, and rows will benull.

Live query host by identifier (ad-hoc)

Runs an ad-hoc live query against a host identified using uuid and responds with the results.

The live query will stop if the targeted host is offline, or if the query times out. Timeouts happen if the host hasn't responded after the configured FLEET_LIVE_QUERY_REST_PERIOD (default 25 seconds) or if the distributed_interval agent option (default 10 seconds) is higher than the FLEET_LIVE_QUERY_REST_PERIOD.

POST /api/v1/fleet/hosts/identifier/:identifier/query

Parameters

Example

POST /api/v1/fleet/hosts/identifier/392547dc-0000-0000-a87a-d701ff75bc65/query

Request body

{
  "query": "SELECT model, vendor FROM usb_devices;"
}

Default response

Status: 200

{
  "host_id": 123,
  "query": "SELECT model, vendor FROM usb_devices;",
  "status": "online", // "online" or "offline"
  "error": null,
  "rows": [
    {
      "model": "USB2.0 Hub",
      "vendor": "VIA Labs, Inc."
    }
  ]
}

Note that if the host is online and the query times out, this endpoint will return an error and rows will be null. If the host is offline, no error will be returned, and rows will be null.

---

Labels

• Create label
• Modify label
• Get label
• Get labels summary
• List labels
• List hosts in a label
• Delete label
• Delete label by ID

Create label

Creates a dynamic label.

POST /api/v1/fleet/labels

Parameters

Example

POST /api/v1/fleet/labels

Request body

{
  "name": "Ubuntu hosts",
  "description": "Filters ubuntu hosts",
  "query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';",
  "platform": ""
}

Default response

Status: 200

{
  "label": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 1,
    "name": "Ubuntu hosts",
    "description": "Filters ubuntu hosts",
    "query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';",
    "label_type": "regular",
    "label_membership_type": "dynamic",
    "display_text": "Ubuntu hosts",
    "count": 0,
    "host_ids": null
  }
}

Modify label

Modifies the specified label. Note: Label queries and platforms are immutable. To change these, you must delete the label and create a new label.

PATCH /api/v1/fleet/labels/:id

Parameters

Example

PATCH /api/v1/fleet/labels/1

Request body

{
  "name": "macOS label",
  "description": "Now this label only includes macOS machines",
  "platform": "darwin"
}

Default response

Status: 200

{
  "label": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 1,
    "name": "Ubuntu hosts",
    "description": "Filters ubuntu hosts",
    "query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';",
    "platform": "darwin",
    "label_type": "regular",
    "label_membership_type": "dynamic",
    "display_text": "Ubuntu hosts",
    "count": 0,
    "host_ids": null
  }
}

Get label

Returns the specified label.

GET /api/v1/fleet/labels/:id

Parameters

Example

GET /api/v1/fleet/labels/1

Default response

Status: 200

{
  "label": {
    "created_at": "2021-02-09T22:09:43Z",
    "updated_at": "2021-02-09T22:15:58Z",
    "id": 12,
    "name": "Ubuntu",
    "description": "Filters ubuntu hosts",
    "query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';",
    "label_type": "regular",
    "label_membership_type": "dynamic",
    "display_text": "Ubuntu",
    "count": 0,
    "host_ids": null
  }
}

Get labels summary

Returns a list of all the labels in Fleet.

GET /api/v1/fleet/labels/summary

Example

GET /api/v1/fleet/labels/summary

Default response

Status: 200

{
  "labels": [
    {
      "id": 6,
      "name": "All Hosts",
      "description": "All hosts which have enrolled in Fleet",
      "label_type": "builtin"
    },
    {
      "id": 7,
      "name": "macOS",
      "description": "All macOS hosts",
      "label_type": "builtin"
    },
    {
      "id": 8,
      "name": "Ubuntu Linux",
      "description": "All Ubuntu hosts",
      "label_type": "builtin"
    },
    {
      "id": 9,
      "name": "CentOS Linux",
      "description": "All CentOS hosts",
      "label_type": "builtin"
    },
    {
      "id": 10,
      "name": "MS Windows",
      "description": "All Windows hosts",
      "label_type": "builtin"
    }
  ]
}

List labels

Returns a list of all the labels in Fleet.

GET /api/v1/fleet/labels

Parameters

Example

GET /api/v1/fleet/labels

Default response

Status: 200

{
  "labels": [
    {
      "created_at": "2021-02-02T23:55:25Z",
      "updated_at": "2021-02-02T23:55:25Z",
      "id": 6,
      "name": "All Hosts",
      "description": "All hosts which have enrolled in Fleet",
      "query": "SELECT 1;",
      "label_type": "builtin",
      "label_membership_type": "dynamic",
      "host_count": 7,
      "display_text": "All Hosts",
      "count": 7,
      "host_ids": null
    },
    {
      "created_at": "2021-02-02T23:55:25Z",
      "updated_at": "2021-02-02T23:55:25Z",
      "id": 7,
      "name": "macOS",
      "description": "All macOS hosts",
      "query": "SELECT 1 FROM os_version WHERE platform = 'darwin';",
      "platform": "darwin",
      "label_type": "builtin",
      "label_membership_type": "dynamic",
      "host_count": 1,
      "display_text": "macOS",
      "count": 1,
      "host_ids": null
    },
    {
      "created_at": "2021-02-02T23:55:25Z",
      "updated_at": "2021-02-02T23:55:25Z",
      "id": 8,
      "name": "Ubuntu Linux",
      "description": "All Ubuntu hosts",
      "query": "SELECT 1 FROM os_version WHERE platform = 'ubuntu';",
      "platform": "ubuntu",
      "label_type": "builtin",
      "label_membership_type": "dynamic",
      "host_count": 3,
      "display_text": "Ubuntu Linux",
      "count": 3,
      "host_ids": null
    },
    {
      "created_at": "2021-02-02T23:55:25Z",
      "updated_at": "2021-02-02T23:55:25Z",
      "id": 9,
      "name": "CentOS Linux",
      "description": "All CentOS hosts",
      "query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'",
      "label_type": "builtin",
      "label_membership_type": "dynamic",
      "host_count": 3,
      "display_text": "CentOS Linux",
      "count": 3,
      "host_ids": null
    },
    {
      "created_at": "2021-02-02T23:55:25Z",
      "updated_at": "2021-02-02T23:55:25Z",
      "id": 10,
      "name": "MS Windows",
      "description": "All Windows hosts",
      "query": "SELECT 1 FROM os_version WHERE platform = 'windows';",
      "platform": "windows",
      "label_type": "builtin",
      "label_membership_type": "dynamic",
      "display_text": "MS Windows",
      "count": 0,
      "host_ids": null
    }
  ]
}

List hosts in a label

Returns a list of the hosts that belong to the specified label.

GET /api/v1/fleet/labels/:id/hosts

Parameters

If mdm_id, mdm_name, mdm_enrollment_status, os_settings, or os_settings_disk_encryption is specified, then Windows Servers are excluded from the results.

Example

GET /api/v1/fleet/labels/6/hosts&query=floobar

Default response

Status: 200

{
  "hosts": [
    {
      "created_at": "2021-02-03T16:11:43Z",
      "updated_at": "2021-02-03T21:58:19Z",
      "id": 2,
      "detail_updated_at": "2021-02-03T21:58:10Z",
      "label_updated_at": "2021-02-03T21:58:10Z",
      "policy_updated_at": "2023-06-26T18:33:15Z",
      "last_enrolled_at": "2021-02-03T16:11:43Z",
      "software_updated_at": "2020-11-05T05:09:44Z",
      "seen_time": "2021-02-03T21:58:20Z",
      "refetch_requested": false,
      "hostname": "floobar42",
      "uuid": "a2064cef-0000-0000-afb9-283e3c1d487e",
      "platform": "ubuntu",
      "osquery_version": "4.5.1",
      "os_version": "Ubuntu 20.4.0",
      "build": "",
      "platform_like": "debian",
      "code_name": "",
      "uptime": 32688000000000,
      "memory": 2086899712,
      "cpu_type": "x86_64",
      "cpu_subtype": "142",
      "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz",
      "cpu_physical_cores": 4,
      "cpu_logical_cores": 4,
      "hardware_vendor": "",
      "hardware_model": "",
      "hardware_version": "",
      "hardware_serial": "",
      "computer_name": "e2e7f8d8983d",
      "display_name": "e2e7f8d8983d",
      "primary_ip": "172.20.0.2",
      "primary_mac": "02:42:ac:14:00:02",
      "distributed_interval": 10,
      "config_tls_refresh": 10,
      "logger_tls_period": 10,
      "team_id": null,
      "pack_stats": null,
      "team_name": null,
      "status": "offline",
      "display_text": "e2e7f8d8983d",
      "mdm": {
        "encryption_key_available": false,
        "enrollment_status": null,
        "name": "",
        "server_url": null
      }
    }
  ]
}

Delete label

Deletes the label specified by name.

DELETE /api/v1/fleet/labels/:name

Parameters

Example

DELETE /api/v1/fleet/labels/ubuntu_label

Default response

Status: 200

Delete label by ID

Deletes the label specified by ID.

DELETE /api/v1/fleet/labels/id/:id

Parameters

Example

DELETE /api/v1/fleet/labels/id/13

Default response

Status: 200

---

Mobile device management (MDM)

These API endpoints are used to automate MDM features in Fleet. Read more about MDM features in Fleet here.

• Add custom OS setting (configuration profile)
• Get manual enrollment profile
• List custom OS settings (configuration profiles)
• Get or download custom OS setting (configuration profile)
• Delete custom OS setting (configuration profile)
• Update disk encryption enforcement
• Get disk encryption statistics
• Get OS settings status
• Run custom MDM command
• Get custom MDM command results
• List custom MDM commands
• Set custom MDM setup enrollment profile
• Get custom MDM setup enrollment profile
• Delete custom MDM setup enrollment profile
• Get Apple Push Notification service (APNs)
• Get Apple Business Manager (ABM)
• Turn off MDM for a host
• Upload a bootstrap package
• Get metadata about a bootstrap package
• Delete a bootstrap package
• Download a bootstrap package
• Get a summary of bootstrap package status
• Upload an EULA file
• Get metadata about an EULA file
• Delete an EULA file
• Download an EULA file

Add custom OS setting (configuration profile)

Add custom macOS setting (POST /api/v1/fleet/mdm/apple/profiles) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead.

Add a configuration profile to enforce custom settings on macOS and Windows hosts.

POST /api/v1/fleet/mdm/profiles

Parameters

Example

Add a new configuration profile to be applied to macOS hosts assigned to a team. Note that in this example the form data specifiesteam_id in addition to profile.

POST /api/v1/fleet/mdm/profiles

Request headers

Content-Length: 850
Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y

Request body

--------------------------f02md47480und42y
Content-Disposition: form-data; name="team_id"

1
--------------------------f02md47480und42y
Content-Disposition: form-data; name="labels"

Label name 1
--------------------------f02md47480und42y
Content-Disposition: form-data; name="labels"

Label name 2
--------------------------f02md47480und42y
Content-Disposition: form-data; name="profile"; filename="Foo.mobileconfig"
Content-Type: application/octet-stream

<?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">
<dict>
  <key>PayloadContent</key>
  <array/>
  <key>PayloadDisplayName</key>
  <string>Example profile</string>
  <key>PayloadIdentifier</key>
  <string>com.example.profile</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>
--------------------------f02md47480und42y--

Default response

Status: 200

{
  "profile_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24"
}

Additional notes

If the response is Status: 409 Conflict, the body may include additional error details in the case of duplicate payload display name or duplicate payload identifier (macOS profiles).

Get manual enrollment profile

Retrieves the manual enrollment profile for macOS hosts. Install this profile on macOS hosts to turn on MDM features manually.

GET /api/v1/fleet/mdm/manual_enrollment_profile

Example

GET /api/v1/fleet/mdm/manual_enrollment_profile

Default response

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>

List custom OS settings (configuration profiles)

List custom macOS settings (GET /api/v1/fleet/mdm/apple/profiles) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead.

Get a list of the configuration profiles in Fleet.

For Fleet Premium, the list can optionally be filtered by team ID. If no team ID is specified, team profiles are excluded from the results (i.e., only profiles that are associated with "No team" are listed).

GET /api/v1/fleet/mdm/profiles

Parameters

Example

List all configuration profiles for macOS and Windows hosts enrolled to Fleet's MDM that are not assigned to any team.

GET /api/v1/fleet/mdm/profiles

Default response

Status: 200

{
  "profiles": [
    {
      "profile_uuid": "39f6cbbc-fe7b-4adc-b7a9-542d1af89c63",
      "team_id": 0,
      "name": "Example macOS profile",
      "platform": "darwin",
      "identifier": "com.example.profile",
      "created_at": "2023-03-31T00:00:00Z",
      "updated_at": "2023-03-31T00:00:00Z",
      "checksum": "dGVzdAo=",
      "labels": [
       {
        "name": "Label name 1"
       }
      ]
    },
    {
      "profile_uuid": "f5ad01cc-f416-4b5f-88f3-a26da3b56a19",
      "team_id": 0,
      "name": "Example Windows profile",
      "platform": "windows",
      "created_at": "2023-04-31T00:00:00Z",
      "updated_at": "2023-04-31T00:00:00Z",
      "checksum": "aCLemVr)",
      "labels": [
       {
         "name": "Label name 1",
         "broken": true
       },
       {
         "name": "Label name 2"
       }
      ]
    }
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

If one or more assigned labels are deleted the profile is considered broken (broken: true). It won’t be applied to new hosts.

Get or download custom OS setting (configuration profile)

Download custom macOS setting (GET /api/v1/fleet/mdm/apple/profiles/:profile_id) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the API endpoint below instead.

GET /api/v1/fleet/mdm/profiles/:profile_uuid

Parameters

Example (get a profile metadata)

GET /api/v1/fleet/mdm/profiles/f663713f-04ee-40f0-a95a-7af428c351a9

Default response

Status: 200

{
  "profile_uuid": "f663713f-04ee-40f0-a95a-7af428c351a9",
  "team_id": 0,
  "name": "Example profile",
  "platform": "darwin",
  "identifier": "com.example.profile",
  "created_at": "2023-03-31T00:00:00Z",
  "updated_at": "2023-03-31T00:00:00Z",
  "checksum": "dGVzdAo=",
  "labels": [
    {
      "name": "Label name 1",
      "broken": true
    },
    {
      "name": "Label name 2",
    }
  ]
}

Example (download a profile)

GET /api/v1/fleet/mdm/profiles/f663713f-04ee-40f0-a95a-7af428c351a9?alt=media

Default response

Status: 200

Note To confirm success, it is important for clients to match content length with the response header (this is done automatically by most clients, including the browser) rather than relying solely on the response status code returned by this endpoint.

Example response headers

  Content-Length: 542
  Content-Type: application/octet-stream
  Content-Disposition: attachment;filename="2023-03-31 Example profile.mobileconfig"

Example response body

<?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">
<dict>
  <key>PayloadContent</key>
  <array/>
  <key>PayloadDisplayName</key>
  <string>Example profile</string>
  <key>PayloadIdentifier</key>
  <string>com.example.profile</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

Delete custom OS setting (configuration profile)

Delete custom macOS setting (DELETE /api/v1/fleet/mdm/apple/profiles/:profile_id) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead.

DELETE /api/v1/fleet/mdm/profiles/:profile_uuid

Parameters

Example

DELETE /api/v1/fleet/mdm/profiles/f663713f-04ee-40f0-a95a-7af428c351a9

Default response

Status: 200

Update disk encryption enforcement

Available in Fleet Premium

PATCH /api/v1/fleet/mdm/apple/settings

Parameters

Example

PATCH /api/v1/fleet/mdm/apple/settings

Default response

204

Get disk encryption statistics

Available in Fleet Premium

Get aggregate status counts of disk encryption enforced on macOS and Windows hosts.

The summary can optionally be filtered by team ID.

GET /api/v1/fleet/mdm/disk_encryption/summary

Parameters

Example

Get aggregate disk encryption status counts of macOS and Windows hosts enrolled to Fleet's MDM that are not assigned to any team.

GET /api/v1/fleet/mdm/disk_encryption/summary

Default response

Status: 200

{
  "verified": {"macos": 123, "windows": 123},
  "verifying": {"macos": 123, "windows": 0},
  "action_required": {"macos": 123, "windows": 0},
  "enforcing": {"macos": 123, "windows": 123},
  "failed": {"macos": 123, "windows": 123},
  "removing_enforcement": {"macos": 123, "windows": 0},
}

Get OS settings status

Get macOS settings statistics (GET /api/v1/fleet/mdm/apple/profiles/summary) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead.

Get aggregate status counts of all OS settings (configuration profiles and disk encryption) enforced on hosts.

For Fleet Premium users, the counts can optionally be filtered by team_id. If no team_id is specified, team profiles are excluded from the results (i.e., only profiles that are associated with "No team" are listed).

GET /api/v1/fleet/mdm/profiles/summary

Parameters

Example

Get aggregate status counts of profiles for to macOS and Windows hosts that are assigned to "No team".

GET /api/v1/fleet/mdm/profiles/summary

Default response

Status: 200

{
  "verified": 123,
  "verifying": 123,
  "failed": 123,
  "pending": 123
}

Run custom MDM command

POST /api/v1/fleet/mdm/apple/enqueue API endpoint is deprecated as of Fleet 4.40. It is maintained for backward compatibility. Please use the new API endpoint below. See old API endpoint docs here.

This endpoint tells Fleet to run a custom MDM command, on the targeted macOS or Windows hosts, the next time they come online.

POST /api/v1/fleet/mdm/commands/run

Parameters

Note that the EraseDevice and DeviceLock commands are available in Fleet Premium only.

Example

POST /api/v1/fleet/mdm/commands/run

Default response

Status: 200

{
  "command_uuid": "a2064cef-0000-1234-afb9-283e3c1d487e",
  "request_type": "ProfileList"
}

Get custom MDM command results

GET /api/v1/fleet/mdm/apple/commandresults API endpoint is deprecated as of Fleet 4.40. It is maintained for backward compatibility. Please use the new API endpoint below. See old API endpoint docs here.

This endpoint returns the results for a specific custom MDM command.

GET /api/v1/fleet/mdm/commandresults

Parameters

Example

GET /api/v1/fleet/mdm/commandresults?command_uuid=a2064cef-0000-1234-afb9-283e3c1d487e

Default response

Status: 200

{
  "results": [
    {
      "host_uuid": "145cafeb-87c7-4869-84d5-e4118a927746",
      "command_uuid": "a2064cef-0000-1234-afb9-283e3c1d487e",
      "status": "Acknowledged",
      "updated_at": "2023-04-04:00:00Z",
      "request_type": "ProfileList",
      "hostname": "mycomputer",
      "payload": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjwhRE9DVFlQRSBwbGlzdCBQVUJMSUMgIi0vL0FwcGxlLy9EVEQgUExJU1QgMS4wLy9FTiIgImh0dHA6Ly93d3cuYXBwbGUuY29tL0RURHMvUHJvcGVydHlMaXN0LTEuMC5kdGQiPg0KPHBsaXN0IHZlcnNpb249IjEuMCI+DQo8ZGljdD4NCg0KCTxrZXk+UGF5bG9hZERlc2NyaXB0aW9uPC9rZXk+DQoJPHN0cmluZz5UaGlzIHByb2ZpbGUgY29uZmlndXJhdGlvbiBpcyBkZXNpZ25lZCB0byBhcHBseSB0aGUgQ0lTIEJlbmNobWFyayBmb3IgbWFjT1MgMTAuMTQgKHYyLjAuMCksIDEwLjE1ICh2Mi4wLjApLCAxMS4wICh2Mi4wLjApLCBhbmQgMTIuMCAodjEuMC4wKTwvc3RyaW5nPg0KCTxrZXk+UGF5bG9hZERpc3BsYXlOYW1lPC9rZXk+DQoJPHN0cmluZz5EaXNhYmxlIEJsdWV0b290aCBzaGFyaW5nPC9zdHJpbmc+DQoJPGtleT5QYXlsb2FkRW5hYmxlZDwva2V5Pg0KCTx0cnVlLz4NCgk8a2V5PlBheWxvYWRJZGVudGlmaWVyPC9rZXk+DQoJPHN0cmluZz5jaXMubWFjT1NCZW5jaG1hcmsuc2VjdGlvbjIuQmx1ZXRvb3RoU2hhcmluZzwvc3RyaW5nPg0KCTxrZXk+UGF5bG9hZFNjb3BlPC9rZXk+DQoJPHN0cmluZz5TeXN0ZW08L3N0cmluZz4NCgk8a2V5PlBheWxvYWRUeXBlPC9rZXk+DQoJPHN0cmluZz5Db25maWd1cmF0aW9uPC9zdHJpbmc+DQoJPGtleT5QYXlsb2FkVVVJRDwva2V5Pg0KCTxzdHJpbmc+NUNFQkQ3MTItMjhFQi00MzJCLTg0QzctQUEyOEE1QTM4M0Q4PC9zdHJpbmc+DQoJPGtleT5QYXlsb2FkVmVyc2lvbjwva2V5Pg0KCTxpbnRlZ2VyPjE8L2ludGVnZXI+DQogICAgPGtleT5QYXlsb2FkUmVtb3ZhbERpc2FsbG93ZWQ8L2tleT4NCiAgICA8dHJ1ZS8+DQoJPGtleT5QYXlsb2FkQ29udGVudDwva2V5Pg0KCTxhcnJheT4NCgkJPGRpY3Q+DQoJCQk8a2V5PlBheWxvYWRDb250ZW50PC9rZXk+DQoJCQk8ZGljdD4NCgkJCQk8a2V5PmNvbS5hcHBsZS5CbHVldG9vdGg8L2tleT4NCgkJCQk8ZGljdD4NCgkJCQkJPGtleT5Gb3JjZWQ8L2tleT4NCgkJCQkJPGFycmF5Pg0KCQkJCQkJPGRpY3Q+DQoJCQkJCQkJPGtleT5tY3hfcHJlZmVyZW5jZV9zZXR0aW5nczwva2V5Pg0KCQkJCQkJCTxkaWN0Pg0KCQkJCQkJCQk8a2V5PlByZWZLZXlTZXJ2aWNlc0VuYWJsZWQ8L2tleT4NCgkJCQkJCQkJPGZhbHNlLz4NCgkJCQkJCQk8L2RpY3Q+DQoJCQkJCQk8L2RpY3Q+DQoJCQkJCTwvYXJyYXk+DQoJCQkJPC9kaWN0Pg0KCQkJPC9kaWN0Pg0KCQkJPGtleT5QYXlsb2FkRGVzY3JpcHRpb248L2tleT4NCgkJCTxzdHJpbmc+RGlzYWJsZXMgQmx1ZXRvb3RoIFNoYXJpbmc8L3N0cmluZz4NCgkJCTxrZXk+UGF5bG9hZERpc3BsYXlOYW1lPC9rZXk+DQoJCQk8c3RyaW5nPkN1c3RvbTwvc3RyaW5nPg0KCQkJPGtleT5QYXlsb2FkRW5hYmxlZDwva2V5Pg0KCQkJPHRydWUvPg0KCQkJPGtleT5QYXlsb2FkSWRlbnRpZmllcjwva2V5Pg0KCQkJPHN0cmluZz4wMjQwREQxQy03MERDLTQ3NjYtOTAxOC0wNDMyMkJGRUVBRDE8L3N0cmluZz4NCgkJCTxrZXk+UGF5bG9hZFR5cGU8L2tleT4NCgkJCTxzdHJpbmc+Y29tLmFwcGxlLk1hbmFnZWRDbGllbnQucHJlZmVyZW5jZXM8L3N0cmluZz4NCgkJCTxrZXk+UGF5bG9hZFVVSUQ8L2tleT4NCgkJCTxzdHJpbmc+MDI0MEREMUMtNzBEQy00NzY2LTkwMTgtMDQzMjJCRkVFQUQxPC9zdHJpbmc+DQoJCQk8a2V5PlBheWxvYWRWZXJzaW9uPC9rZXk+DQoJCQk8aW50ZWdlcj4xPC9pbnRlZ2VyPg0KCQk8L2RpY3Q+DQoJPC9hcnJheT4NCjwvZGljdD4NCjwvcGxpc3Q+",
      "result": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjwhRE9DVFlQRSBwbGlzdCBQVUJMSUMgIi0vL0FwcGxlLy9EVEQgUExJU1QgMS4wLy9FTiIgImh0dHA6Ly93d3cuYXBwbGUuY29tL0RURHMvUHJvcGVydHlMaXN0LTEuMC5kdGQiPg0KPHBsaXN0IHZlcnNpb249IjEuMCI+DQo8ZGljdD4NCiAgICA8a2V5PkNvbW1hbmRVVUlEPC9rZXk+DQogICAgPHN0cmluZz4wMDAxX0luc3RhbGxQcm9maWxlPC9zdHJpbmc+DQogICAgPGtleT5TdGF0dXM8L2tleT4NCiAgICA8c3RyaW5nPkFja25vd2xlZGdlZDwvc3RyaW5nPg0KICAgIDxrZXk+VURJRDwva2V5Pg0KICAgIDxzdHJpbmc+MDAwMDgwMjAtMDAwOTE1MDgzQzgwMDEyRTwvc3RyaW5nPg0KPC9kaWN0Pg0KPC9wbGlzdD4="
    }
  ]
}

Note: If the server has not yet received a result for a command, it will return an empty object ({}).

List custom MDM commands

GET /api/v1/fleet/mdm/apple/commands API endpoint is deprecated as of Fleet 4.40. It is maintained for backward compatibility. Please use the new API endpoint below. See old API endpoint docs here.

This endpoint returns the list of custom MDM commands that have been executed.

GET /api/v1/fleet/mdm/commands

Parameters

Example

GET /api/v1/fleet/mdm/commands?per_page=5

Default response

Status: 200

{
  "results": [
    {
      "host_uuid": "145cafeb-87c7-4869-84d5-e4118a927746",
      "command_uuid": "a2064cef-0000-1234-afb9-283e3c1d487e",
      "status": "Acknowledged",
      "updated_at": "2023-04-04:00:00Z",
      "request_type": "ProfileList",
      "hostname": "mycomputer"
    },
    {
      "host_uuid": "322vghee-12c7-8976-83a1-e2118a927342",
      "command_uuid": "d76d69b7-d806-45a9-8e49-9d6dc533485c",
      "status": "200",
      "updated_at": "2023-05-04:00:00Z",
      "request_type": "./Device/Vendor/MSFT/Reboot/RebootNow",
      "hostname": "myhost"
    }
  ]
}

Set custom MDM setup enrollment profile

Available in Fleet Premium

Sets the custom MDM setup enrollment profile for a team or no team.

POST /api/v1/fleet/mdm/apple/enrollment_profile

Parameters

Example

POST /api/v1/fleet/mdm/apple/enrollment_profile

Default response

Status: 200

{
  "team_id": 123,
  "name": "dep_profile.json",
  "uploaded_at": "2023-04-04:00:00Z",
  "enrollment_profile": {
    "is_mandatory": true,
    "is_mdm_removable": false
  }
}

Get custom MDM setup enrollment profile

Available in Fleet Premium

Gets the custom MDM setup enrollment profile for a team or no team.

GET /api/v1/fleet/mdm/apple/enrollment_profile

Parameters

Example

GET /api/v1/fleet/mdm/apple/enrollment_profile?team_id=123

Default response

Status: 200

{
  "team_id": 123,
  "name": "dep_profile.json",
  "uploaded_at": "2023-04-04:00:00Z",
  "enrollment_profile": {
    "is_mandatory": true,
    "is_mdm_removable": false
  }
}

Delete custom MDM setup enrollment profile

Available in Fleet Premium

Deletes the custom MDM setup enrollment profile assigned to a team or no team.

DELETE /api/v1/fleet/mdm/apple/enrollment_profile

Parameters

Example

DELETE /api/v1/fleet/mdm/apple/enrollment_profile?team_id=123

Default response

Status: 204

Get Apple Push Notification service (APNs)

GET /api/v1/fleet/mdm/apple

Parameters

None.

Example

GET /api/v1/fleet/mdm/apple

Default response

Status: 200

{
  "common_name": "APSP:04u52i98aewuh-xxxx-xxxx-xxxx-xxxx",
  "serial_number": "1234567890987654321",
  "issuer": "Apple Application Integration 2 Certification Authority",
  "renew_date": "2023-09-30T00:00:00Z"
}

Get Apple Business Manager (ABM)

Available in Fleet Premium

GET /api/v1/fleet/mdm/apple_bm

Parameters

None.

Example

GET /api/v1/fleet/mdm/apple_bm

Default response

Status: 200

{
  "apple_id": "[email protected]",
  "org_name": "Fleet Device Management",
  "mdm_server_url": "https://example.com/mdm/apple/mdm",
  "renew_date": "2023-11-29T00:00:00Z",
  "default_team": ""
}

Turn off MDM for a host

PATCH /api/v1/fleet/mdm/hosts/:id/unenroll

Parameters

Example

PATCH /api/v1/fleet/mdm/hosts/42/unenroll

Default response

Status: 200

Upload a bootstrap package

Available in Fleet Premium

Upload a bootstrap package that will be automatically installed during DEP setup.

POST /api/v1/fleet/mdm/apple/bootstrap

Parameters

Example

Upload a bootstrap package that will be installed to macOS hosts enrolled to MDM that are assigned to a team. Note that in this example the form data specifies team_id in addition to package.

POST /api/v1/fleet/mdm/apple/profiles

Request headers

Content-Length: 850
Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y

Request body

--------------------------f02md47480und42y
Content-Disposition: form-data; name="team_id"
1
--------------------------f02md47480und42y
Content-Disposition: form-data; name="package"; filename="bootstrap-package.pkg"
Content-Type: application/octet-stream
<BINARY_DATA>
--------------------------f02md47480und42y--

Default response

Status: 200

Get metadata about a bootstrap package

Available in Fleet Premium

Get information about a bootstrap package that was uploaded to Fleet.

GET /api/v1/fleet/mdm/apple/bootstrap/:team_id/metadata

Parameters

Example

GET /api/v1/fleet/mdm/apple/bootstrap/0/metadata

Default response

Status: 200

{
  "name": "bootstrap-package.pkg",
  "team_id": 0,
  "sha256": "6bebb4433322fd52837de9e4787de534b4089ac645b0692dfb74d000438da4a3",
  "token": "AA598E2A-7952-46E3-B89D-526D45F7E233",
  "created_at": "2023-04-20T13:02:05Z"
}

In the response above:

• token is the value you can use to download a bootstrap package
• sha256 is the SHA256 digest of the bytes of the bootstrap package file.

Delete a bootstrap package

Available in Fleet Premium

Delete a team's bootstrap package.

DELETE /api/v1/fleet/mdm/apple/bootstrap/:team_id

Parameters

Example

DELETE /api/v1/fleet/mdm/apple/bootstrap/1

Default response

Status: 200

Download a bootstrap package

Available in Fleet Premium

Download a bootstrap package.

GET /api/v1/fleet/mdm/apple/bootstrap

Parameters

Example

GET /api/v1/fleet/mdm/apple/bootstrap?token=AA598E2A-7952-46E3-B89D-526D45F7E233

Default response

Status: 200

Status: 200
Content-Type: application/octet-stream
Content-Disposition: attachment
Content-Length: <length>
Body: <blob>

Get a summary of bootstrap package status

Available in Fleet Premium

Get aggregate status counts of bootstrap packages delivered to DEP enrolled hosts.

The summary can optionally be filtered by team ID.

GET /api/v1/fleet/mdm/apple/bootstrap/summary

Parameters

Example

GET /api/v1/fleet/mdm/apple/bootstrap/summary

Default response

Status: 200

{
  "installed": 10,
  "failed": 1,
  "pending": 4
}

Turn on end user authentication for macOS setup

Available in Fleet Premium

PATCH /api/v1/fleet/mdm/apple/setup

Parameters

Example

PATCH /api/v1/fleet/mdm/apple/setup

Request body

{
  "team_id": 1,
  "enabled_end_user_authentication": true
}

Default response

Status: 204

Upload an EULA file

Available in Fleet Premium

Upload an EULA that will be shown during the DEP flow.

POST /api/v1/fleet/mdm/apple/setup/eula

Parameters

Example

POST /api/v1/fleet/mdm/apple/setup/eula

Request headers

Content-Length: 850
Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y

Request body

--------------------------f02md47480und42y
Content-Disposition: form-data; name="eula"; filename="eula.pdf"
Content-Type: application/octet-stream
<BINARY_DATA>
--------------------------f02md47480und42y--

Default response

Status: 200

Get metadata about an EULA file

Available in Fleet Premium

Get information about the EULA file that was uploaded to Fleet. If no EULA was previously uploaded, this endpoint returns a 404 status code.

GET /api/v1/fleet/mdm/apple/setup/eula/metadata

Example

GET /api/v1/fleet/mdm/apple/setup/eula/metadata

Default response

Status: 200

{
  "name": "eula.pdf",
  "token": "AA598E2A-7952-46E3-B89D-526D45F7E233",
  "created_at": "2023-04-20T13:02:05Z"
}

In the response above:

• token is the value you can use to download an EULA

Delete an EULA file

Available in Fleet Premium

Delete an EULA file.

DELETE /api/v1/fleet/mdm/apple/setup/eula/:token

Parameters

Example

DELETE /api/v1/fleet/mdm/apple/setup/eula/AA598E2A-7952-46E3-B89D-526D45F7E233

Default response

Status: 200

Download an EULA file

Available in Fleet Premium

Download an EULA file

GET /api/v1/fleet/mdm/apple/setup/eula/:token

Parameters

Example

GET /api/v1/fleet/mdm/apple/setup/eula/AA598E2A-7952-46E3-B89D-526D45F7E233

Default response

Status: 200

Status: 200
Content-Type: application/pdf
Content-Disposition: attachment
Content-Length: <length>
Body: <blob>

---

Policies

• List policies
• Count policies
• Get policy by ID
• Add policy
• Remove policies
• Edit policy
• Run automation for all failing hosts of a policy

Policies are yes or no questions you can ask about your hosts.

Policies in Fleet are defined by osquery queries.

A passing host answers "yes" to a policy if the host returns results for a policy's query.

A failing host answers "no" to a policy if the host does not return results for a policy's query.

For example, a policy might ask “Is Gatekeeper enabled on macOS devices?“ This policy's osquery query might look like the following: SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;

List policies

GET /api/v1/fleet/global/policies

Parameters

Example

GET /api/v1/fleet/global/policies

Default response

Status: 200

{
  "policies": [
    {
      "id": 1,
      "name": "Gatekeeper enabled",
      "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
      "description": "Checks if gatekeeper is enabled on macOS devices",
      "critical": false,
      "author_id": 42,
      "author_name": "John",
      "author_email": "[email protected]",
      "team_id": null,
      "resolution": "Resolution steps",
      "platform": "darwin",
      "created_at": "2021-12-15T15:23:57Z",
      "updated_at": "2021-12-15T15:23:57Z",
      "passing_host_count": 2000,
      "failing_host_count": 300,
      "host_count_updated_at": "2023-12-20T15:23:57Z"
    },
    {
      "id": 2,
      "name": "Windows machines with encrypted hard disks",
      "query": "SELECT 1 FROM bitlocker_info WHERE protection_status = 1;",
      "description": "Checks if the hard disk is encrypted on Windows devices",
      "critical": true,
      "author_id": 43,
      "author_name": "Alice",
      "author_email": "[email protected]",
      "team_id": null,
      "resolution": "Resolution steps",
      "platform": "windows",
      "created_at": "2021-12-31T14:52:27Z",
      "updated_at": "2022-02-10T20:59:35Z",
      "passing_host_count": 2300,
      "failing_host_count": 0,
      "host_count_updated_at": "2023-12-20T15:23:57Z"
    }
  ]
}

---

Count policies

GET /api/v1/fleet/policies/count

Parameters

Example

GET /api/v1/fleet/policies/count

Default response

Status: 200

{
  "count": 43
}

---

Get policy by ID

GET /api/v1/fleet/global/policies/:id

Parameters

Example

GET /api/v1/fleet/global/policies/1

Default response

Status: 200

{
  "policy": {
      "id": 1,
      "name": "Gatekeeper enabled",
      "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
      "description": "Checks if gatekeeper is enabled on macOS devices",
      "critical": false,
      "author_id": 42,
      "author_name": "John",
      "author_email": "[email protected]",
      "team_id": null,
      "resolution": "Resolution steps",
      "platform": "darwin",
      "created_at": "2021-12-15T15:23:57Z",
      "updated_at": "2021-12-15T15:23:57Z",
      "passing_host_count": 2000,
      "failing_host_count": 300,
      "host_count_updated_at": "2023-12-20T15:23:57Z"
    }
}

Add policy

There are two ways of adding a policy:

1. Preferred: By setting name, query, and description.
2. Legacy: By setting query_id to reuse the data of an existing query. If query_id is set, then query must not be set, and name and description are ignored.

An error is returned if both query and query_id are set on the request.

POST /api/v1/fleet/global/policies

Parameters

Either query or query_id must be provided.

Example (preferred)

POST /api/v1/fleet/global/policies

Request body

{
  "name": "Gatekeeper enabled",
  "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
  "description": "Checks if gatekeeper is enabled on macOS devices",
  "resolution": "Resolution steps",
  "platform": "darwin",
  "critical": true
}

Default response

Status: 200

{
  "policy": {
    "id": 43,
    "name": "Gatekeeper enabled",
    "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
    "description": "Checks if gatekeeper is enabled on macOS devices",
    "critical": true,
    "author_id": 42,
    "author_name": "John",
    "author_email": "[email protected]",
    "team_id": null,
    "resolution": "Resolution steps",
    "platform": "darwin",
    "created_at": "2022-03-17T20:15:55Z",
    "updated_at": "2022-03-17T20:15:55Z",
    "passing_host_count": 0,
    "failing_host_count": 0,
    "host_count_updated_at": null
  }
}

Example (legacy)

POST /api/v1/fleet/global/policies

Request body

{
  "query_id": 12
}

Where query_id references an existing query.

Default response

Status: 200

{
  "policy": {
    "id": 43,
    "name": "Gatekeeper enabled",
    "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
    "description": "Checks if gatekeeper is enabled on macOS devices",
    "critical": true,
    "author_id": 42,
    "author_name": "John",
    "author_email": "[email protected]",
    "team_id": null,
    "resolution": "Resolution steps",
    "platform": "darwin",
    "created_at": "2022-03-17T20:15:55Z",
    "updated_at": "2022-03-17T20:15:55Z",
    "passing_host_count": 0,
    "failing_host_count": 0,
    "host_count_updated_at": null
  }
}

Remove policies

POST /api/v1/fleet/global/policies/delete

Parameters

Example

POST /api/v1/fleet/global/policies/delete

Request body

{
  "ids": [ 1 ]
}

Default response

Status: 200

{
  "deleted": 1
}

Edit policy

PATCH /api/v1/fleet/global/policies/:id

Parameters

Example

PATCH /api/v1/fleet/global/policies/42

Request body

{
  "name": "Gatekeeper enabled",
  "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
  "description": "Checks if gatekeeper is enabled on macOS devices",
  "critical": true,
  "resolution": "Resolution steps",
  "platform": "darwin"
}

Default response

Status: 200

{
  "policy": {
    "id": 42,
    "name": "Gatekeeper enabled",
    "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
    "description": "Checks if gatekeeper is enabled on macOS devices",
    "critical": true,
    "author_id": 43,
    "author_name": "John",
    "author_email": "[email protected]",
    "team_id": null,
    "resolution": "Resolution steps",
    "platform": "darwin",
    "created_at": "2022-03-17T20:15:55Z",
    "updated_at": "2022-03-17T20:15:55Z",
    "passing_host_count": 0,
    "failing_host_count": 0,
    "host_count_updated_at": null
  }
}

Run automation for all failing hosts of a policy

Triggers automations for all hosts failing the specified policies, regardless of whether the policies were previously failing on those hosts.

POST /api/v1/fleet/automations/reset

Parameters

Example

POST /api/v1/fleet/automations/reset

Request body

{
    "team_ids": [1],
    "policy_ids": [1, 2, 3]
}

Default response

Status: 200

{}

---

Team policies

• List team policies
• Count team policies
• Get team policy by ID
• Add team policy
• Remove team policies
• Edit team policy

Available in Fleet Premium

Team policies work the same as policies, but at the team level.

List team policies

GET /api/v1/fleet/teams/:id/policies

Parameters

Example

GET /api/v1/fleet/teams/1/policies

Default response

Status: 200

{
  "policies": [
    {
      "id": 1,
      "name": "Gatekeeper enabled",
      "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
      "description": "Checks if gatekeeper is enabled on macOS devices",
      "critical": true,
      "author_id": 42,
      "author_name": "John",
      "author_email": "[email protected]",
      "team_id": 1,
      "resolution": "Resolution steps",
      "platform": "darwin",
      "created_at": "2021-12-16T14:37:37Z",
      "updated_at": "2021-12-16T16:39:00Z",
      "passing_host_count": 2000,
      "failing_host_count": 300,
      "host_count_updated_at": "2023-12-20T15:23:57Z",
      "calendar_events_enabled": true
    },
    {
      "id": 2,
      "name": "Windows machines with encrypted hard disks",
      "query": "SELECT 1 FROM bitlocker_info WHERE protection_status = 1;",
      "description": "Checks if the hard disk is encrypted on Windows devices",
      "critical": false,
      "author_id": 43,
      "author_name": "Alice",
      "author_email": "[email protected]",
      "team_id": 1,
      "resolution": "Resolution steps",
      "platform": "windows",
      "created_at": "2021-12-16T14:37:37Z",
      "updated_at": "2021-12-16T16:39:00Z",
      "passing_host_count": 2300,
      "failing_host_count": 0,
      "host_count_updated_at": "2023-12-20T15:23:57Z",
      "calendar_events_enabled": false
    }
  ],
  "inherited_policies": [
    {
      "id": 136,
      "name": "Arbitrary Test Policy (all platforms) (all teams)",
      "query": "SELECT 1 FROM osquery_info WHERE 1=1;",
      "description": "If you're seeing this, mostly likely this is because someone is testing out failing policies in dogfood. You can ignore this.",
      "critical": true,
      "author_id": 77,
      "author_name": "Test Admin",
      "author_email": "[email protected]",
      "team_id": null,
      "resolution": "To make it pass, change \"1=0\" to \"1=1\". To make it fail, change \"1=1\" to \"1=0\".",
      "platform": "darwin,windows,linux",
      "created_at": "2022-08-04T19:30:18Z",
      "updated_at": "2022-08-30T15:08:26Z",
      "passing_host_count": 10,
      "failing_host_count": 9,
      "host_count_updated_at": "2023-12-20T15:23:57Z"
    }
  ]
}

Count team policies

GET /api/v1/fleet/team/:team_id/policies/count

Parameters

Example

GET /api/v1/fleet/team/1/policies/count

Default response

Status: 200

{
  "count": 43
}

---

Get team policy by ID

GET /api/v1/fleet/teams/:team_id/policies/:policy_id

Parameters

Example

GET /api/v1/fleet/teams/1/policies/43

Default response

Status: 200

{
  "policy": {
    "id": 43,
    "name": "Gatekeeper enabled",
    "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
    "description": "Checks if gatekeeper is enabled on macOS devices",
    "critical": true,
    "author_id": 42,
    "author_name": "John",
    "author_email": "[email protected]",
    "team_id": 1,
    "resolution": "Resolution steps",
    "platform": "darwin",
    "created_at": "2021-12-16T14:37:37Z",
    "updated_at": "2021-12-16T16:39:00Z",
    "passing_host_count": 0,
    "failing_host_count": 0,
    "host_count_updated_at": null,
    "calendar_events_enabled": true
  }
}

Add team policy

The semantics for creating a team policy are the same as for global policies, see Add policy.

POST /api/v1/fleet/teams/:id/policies

Parameters

Either query or query_id must be provided.

Example

POST /api/v1/fleet/teams/1/policies

Request body

{
  "name": "Gatekeeper enabled",
  "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
  "description": "Checks if gatekeeper is enabled on macOS devices",
  "critical": true,
  "resolution": "Resolution steps",
  "platform": "darwin"
}

Default response

Status: 200

{
  "policy": {
    "id": 43,
    "name": "Gatekeeper enabled",
    "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
    "description": "Checks if gatekeeper is enabled on macOS devices",
    "critical": true,
    "author_id": 42,
    "author_name": "John",
    "author_email": "[email protected]",
    "team_id": 1,
    "resolution": "Resolution steps",
    "platform": "darwin",
    "created_at": "2021-12-16T14:37:37Z",
    "updated_at": "2021-12-16T16:39:00Z",
    "passing_host_count": 0,
    "failing_host_count": 0,
    "host_count_updated_at": null,
    "calendar_events_enabled": false
  }
}

Remove team policies

POST /api/v1/fleet/teams/:team_id/policies/delete

Parameters

Example

POST /api/v1/fleet/teams/1/policies/delete

Request body

{
  "ids": [ 1 ]
}

Default response

Status: 200

{
  "deleted": 1
}

Edit team policy

PATCH /api/v1/fleet/teams/:team_id/policies/:policy_id

Parameters

Example

PATCH /api/v1/fleet/teams/2/policies/42

Request body

{
  "name": "Gatekeeper enabled",
  "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
  "description": "Checks if gatekeeper is enabled on macOS devices",
  "critical": true,
  "resolution": "Resolution steps",
  "platform": "darwin"
}

Default response

Status: 200

{
  "policy": {
    "id": 42,
    "name": "Gatekeeper enabled",
    "query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
    "description": "Checks if gatekeeper is enabled on macOS devices",
    "critical": true,
    "author_id": 43,
    "author_name": "John",
    "author_email": "[email protected]",
    "resolution": "Resolution steps",
    "platform": "darwin",
    "team_id": 2,
    "created_at": "2021-12-16T14:37:37Z",
    "updated_at": "2021-12-16T16:39:00Z",
    "passing_host_count": 0,
    "failing_host_count": 0,
    "host_count_updated_at": null,
    "calendar_events_enabled": true
  }
}

---

Queries

• List queries
• Get query
• Get query report
• Get query report for one host
• Create query
• Modify query
• Delete query by name
• Delete query by ID
• Delete queries
• Run live query

List queries

Returns a list of global queries or team queries.

GET /api/v1/fleet/queries

Parameters

Example

GET /api/v1/fleet/queries

Default response

Status: 200

{
"queries": [
  {
    "created_at": "2021-01-04T21:19:57Z",
    "updated_at": "2021-01-04T21:19:57Z",
    "id": 1,
    "name": "query1",
    "description": "query",
    "query": "SELECT * FROM osquery_info",
    "team_id": null,
    "interval": 3600,
    "platform": "darwin,windows,linux",
    "min_osquery_version": "",
    "automations_enabled": true,
    "logging": "snapshot",
    "saved": true,
    "observer_can_run": true,
    "discard_data": false,
    "author_id": 1,
    "author_name": "noah",
    "author_email": "[email protected]",
    "packs": [
      {
        "created_at": "2021-01-05T21:13:04Z",
        "updated_at": "2021-01-07T19:12:54Z",
        "id": 1,
        "name": "Pack",
        "description": "Pack",
        "platform": "",
        "disabled": true
      }
    ],
    "stats": {
      "system_time_p50": 1.32,
      "system_time_p95": 4.02,
      "user_time_p50": 3.55,
      "user_time_p95": 3.00,
      "total_executions": 3920
    }
  },
  {
    "created_at": "2021-01-19T17:08:24Z",
    "updated_at": "2021-01-19T17:08:24Z",
    "id": 3,
    "name": "osquery_schedule",
    "description": "Report performance stats for each file in the query schedule.",
    "query": "select name, interval, executions, output_size, wall_time, (user_time/executions) as avg_user_time, (system_time/executions) as avg_system_time, average_memory, last_executed from osquery_schedule;",
    "team_id": null,
    "interval": 3600,
    "platform": "",
    "version": "",
    "automations_enabled": true,
    "logging": "differential",
    "saved": true,
    "observer_can_run": true,
    "discard_data": true,
    "author_id": 1,
    "author_name": "noah",
    "author_email": "[email protected]",
    "packs": [
      {
        "created_at": "2021-01-19T17:08:31Z",
        "updated_at": "2021-01-19T17:08:31Z",
        "id": 14,
        "name": "test_pack",
        "description": "",
        "platform": "",
        "disabled": false
      }
    ],
    "stats": {
      "system_time_p50": null,
      "system_time_p95": null,
      "user_time_p50": null,
      "user_time_p95": null,
      "total_executions": null
    }
  }
]}

Get query

Returns the query specified by ID.

GET /api/v1/fleet/queries/:id

Parameters

Example

GET /api/v1/fleet/queries/31

Default response

Status: 200

{
  "query": {
    "created_at": "2021-01-19T17:08:24Z",
    "updated_at": "2021-01-19T17:08:24Z",
    "id": 31,
    "name": "centos_hosts",
    "description": "",
    "query": "select 1 from os_version where platform = \"centos\";",
    "team_id": null,
    "interval": 3600,
    "platform": "",
    "min_osquery_version": "",
    "automations_enabled": true,
    "logging": "snapshot",
    "saved": true,
    "observer_can_run": true,
    "discard_data": false,
    "author_id": 1,
    "author_name": "John",
    "author_email": "[email protected]",
    "packs": [
      {
        "created_at": "2021-01-19T17:08:31Z",
        "updated_at": "2021-01-19T17:08:31Z",
        "id": 14,
        "name": "test_pack",
        "description": "",
        "platform": "",
        "disabled": false
      }
    ],
    "stats": {
      "system_time_p50": 1.32,
      "system_time_p95": 4.02,
      "user_time_p50": 3.55,
      "user_time_p95": 3.00,
      "total_executions": 3920
    }
  }
}

Get query report

Returns the query report specified by ID.

GET /api/v1/fleet/queries/:id/report

Parameters

Example

GET /api/v1/fleet/queries/31/report

Default response

Status: 200

{
  "query_id": 31,
  "results": [
    {
      "host_id": 1,
      "host_name": "foo",
      "last_fetched": "2021-01-19T17:08:31Z",
      "columns": {
        "model": "USB 2.0 Hub",
        "vendor": "VIA Labs, Inc."
      }
    },
    {
      "host_id": 1,
      "host_name": "foo",
      "last_fetched": "2021-01-19T17:08:31Z",
      "columns": {
        "model": "USB Keyboard",
        "vendor": "VIA Labs, Inc."
      }
    },
    {
      "host_id": 2,
      "host_name": "bar",
      "last_fetched": "2021-01-19T17:20:00Z",
      "columns": {
        "model": "USB Reciever",
        "vendor": "Logitech"
      }
    },
    {
      "host_id": 2,
      "host_name": "bar",
      "last_fetched": "2021-01-19T17:20:00Z",
      "columns": {
        "model": "USB Reciever",
        "vendor": "Logitech"
      }
    },
    {
      "host_id": 2,
      "host_name": "bar",
      "last_fetched": "2021-01-19T17:20:00Z",
      "columns": {
        "model": "Display Audio",
        "vendor": "Apple Inc."
      }
    }
  ]
}

If a query has no results stored, then results will be an empty array:

{
  "query_id": 32,
  "results": []
}

Note: osquery scheduled queries do not return errors, so only non-error results are included in the report. If you suspect a query may be running into errors, you can use the live query endpoint to get diagnostics.

Get query report for one host

Returns a query report for a single host.

GET /api/v1/fleet/hosts/:id/queries/:query_id

Parameters

Example

GET /api/v1/fleet/hosts/123/queries/31

Default response

Status: 200

{
  "query_id": 31,
  "host_id": 1,
  "host_name": "foo",
  "last_fetched": "2021-01-19T17:08:31Z",
  "report_clipped": false,
  "results": [
    {
      "columns": {
        "model": "USB 2.0 Hub",
        "vendor": "VIA Labs, Inc."
      }
    },
    {
      "columns": {
        "model": "USB Keyboard",
        "vendor": "VIA Labs, Inc."
      }
    },
    {
      "columns": {
        "model": "USB Reciever",
        "vendor": "Logitech"
      }
    }
  ]
}

If a query has no results stored for the specified host, then results will be an empty array:

{
  "query_id": 31,
  "host_id": 1,
  "host_name": "foo",
  "last_fetched": "2021-01-19T17:08:31Z",
  "report_clipped": false,
  "results": []
}

Note: osquery scheduled queries do not return errors, so only non-error results are included in the report. If you suspect a query may be running into errors, you can use the live query endpoint to get diagnostics.

Create query

Creates a global query or team query.

POST /api/v1/fleet/queries

Parameters

Example

POST /api/v1/fleet/queries

Request body

{
  "name": "new_query",
  "description": "This is a new query.",
  "query": "SELECT * FROM osquery_info",
  "interval": 3600, // Once per hour
  "platform": "darwin,windows,linux",
  "min_osquery_version": "",
  "automations_enabled": true,
  "logging": "snapshot",
  "discard_data": false
}

Default response

Status: 200

{
  "query": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 288,
    "name": "new_query",
    "query": "SELECT * FROM osquery_info",
    "description": "This is a new query.",
    "team_id": null,
    "interval": 3600,
    "platform": "darwin,windows,linux",
    "min_osquery_version": "",
    "automations_enabled": true,
    "logging": "snapshot",
    "saved": true,
    "author_id": 1,
    "author_name": "",
    "author_email": "",
    "observer_can_run": true,
    "discard_data": false,
    "packs": []
  }
}

Modify query

Modifies the query specified by ID.

PATCH /api/v1/fleet/queries/:id

Parameters

Note that any of the following conditions will cause the existing query report to be deleted:

• Updating the query (SQL) field
• Changing discard_data from false to true
• Changing logging from "snapshot" to "differential" or "differential_ignore_removals"

Example

PATCH /api/v1/fleet/queries/2

Request body

{
  "name": "new_title_for_my_query",
  "interval": 3600, // Once per hour,
  "platform": "",
  "min_osquery_version": "",
  "automations_enabled": false,
  "discard_data": true
}

Default response

Status: 200

{
  "query": {
    "created_at": "2021-01-22T17:23:27Z",
    "updated_at": "2021-01-22T17:23:27Z",
    "id": 288,
    "name": "new_title_for_my_query",
    "description": "This is a new query.",
    "query": "SELECT * FROM osquery_info",
    "team_id": null,
    "interval": 3600,
    "platform": "",
    "min_osquery_version": "",
    "automations_enabled": false,
    "logging": "snapshot",
    "saved": true,
    "author_id": 1,
    "author_name": "noah",
    "observer_can_run": true,
    "discard_data": true,
    "packs": []
  }
}

Delete query by name

Deletes the query specified by name.

DELETE /api/v1/fleet/queries/:name

Parameters

Example

DELETE /api/v1/fleet/queries/foo

Default response

Status: 200

Delete query by ID

Deletes the query specified by ID.

DELETE /api/v1/fleet/queries/id/:id

Parameters

Example

DELETE /api/v1/fleet/queries/id/28

Default response

Status: 200

Delete queries

Deletes the queries specified by ID. Returns the count of queries successfully deleted.

POST /api/v1/fleet/queries/delete

Parameters

Example

POST /api/v1/fleet/queries/delete

Request body

{
  "ids": [
    2, 24, 25
  ]
}

Default response

Status: 200

{
  "deleted": 3
}

Run live query

This updated API endpoint replaced GET /api/v1/fleet/queries/run in Fleet 4.43.0, for improved compatibility with many HTTP clients. The deprecated endpoint is maintained for backwards compatibility.

Runs a live query against the specified hosts and responds with the results.

The live query will stop if the request times out. Timeouts happen if targeted hosts haven't responded after the configured FLEET_LIVE_QUERY_REST_PERIOD (default 25 seconds) or if the distributed_interval agent option (default 10 seconds) is higher than the FLEET_LIVE_QUERY_REST_PERIOD.

POST /api/v1/fleet/queries/:id/run

Parameters

Example

POST /api/v1/fleet/queries/123/run

Request body

{
  "host_ids": [ 1, 4, 34, 27 ]
}

Default response

{
  "query_id": 123,
  "targeted_host_count": 4,
  "responded_host_count": 2,
  "results": [
    {
      "host_id": 1,
      "rows": [
        {
          "build_distro": "10.12",
          "build_platform": "darwin",
          "config_hash": "7bb99fa2c8a998c9459ec71da3a84d66c592d6d3",
          "config_valid": "1",
          "extensions": "active",
          "instance_id": "9a2ec7bf-4946-46ea-93bf-455e0bcbd068",
          "pid": "23413",
          "platform_mask": "21",
          "start_time": "1635194306",
          "uuid": "4C182AC7-75F7-5AF4-A74B-1E165ED35742",
          "version": "4.9.0",
          "watcher": "23412"
        }
      ],
      "error": null
    },
    {
      "host_id": 2,
      "rows": [],
      "error": "no such table: os_version"
    }
  ]
}

---

Schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

• Get schedule (deprecated)
• Add query to schedule (deprecated)
• Edit query in schedule (deprecated)
• Remove query from schedule (deprecated)
• Team schedule

Scheduling queries in Fleet is the best practice for collecting data from hosts.

These API routes let you control your scheduled queries.

Get schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

GET /api/v1/fleet/global/schedule

Parameters

None.

Example

GET /api/v1/fleet/global/schedule

Default response

Status: 200

{
  "global_schedule": [
    {
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "id": 4,
      "pack_id": 1,
      "name": "arp_cache",
      "query_id": 2,
      "query_name": "arp_cache",
      "query": "select * from arp_cache;",
      "interval": 120,
      "snapshot": true,
      "removed": null,
      "platform": "",
      "version": "",
      "shard": null,
      "denylist": null,
      "stats": {
        "system_time_p50": 1.32,
        "system_time_p95": 4.02,
        "user_time_p50": 3.55,
        "user_time_p95": 3.00,
        "total_executions": 3920
      }
    },
    {
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "id": 5,
      "pack_id": 1,
      "name": "disk_encryption",
      "query_id": 7,
      "query_name": "disk_encryption",
      "query": "select * from disk_encryption;",
      "interval": 86400,
      "snapshot": true,
      "removed": null,
      "platform": "",
      "version": "",
      "shard": null,
      "denylist": null,
      "stats": {
        "system_time_p50": 1.32,
        "system_time_p95": 4.02,
        "user_time_p50": 3.55,
        "user_time_p95": 3.00,
        "total_executions": 3920
      }
    }
  ]
}

Add query to schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

POST /api/v1/fleet/global/schedule

Parameters

Example

POST /api/v1/fleet/global/schedule

Request body

{
  "interval": 86400,
  "query_id": 2,
  "snapshot": true
}

Default response

Status: 200

{
  "scheduled": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 1,
    "pack_id": 5,
    "name": "arp_cache",
    "query_id": 2,
    "query_name": "arp_cache",
    "query": "select * from arp_cache;",
    "interval": 86400,
    "snapshot": true,
    "removed": null,
    "platform": "",
    "version": "",
    "shard": null,
    "denylist": null
  }
}

Note that the pack_id is included in the response object because Fleet's Schedule feature uses osquery query packs under the hood.

Edit query in schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

PATCH /api/v1/fleet/global/schedule/:id

Parameters

Example

PATCH /api/v1/fleet/global/schedule/5

Request body

{
  "interval": 604800
}

Default response

Status: 200

{
  "scheduled": {
    "created_at": "2021-07-16T14:40:15Z",
    "updated_at": "2021-07-16T14:40:15Z",
    "id": 5,
    "pack_id": 1,
    "name": "arp_cache",
    "query_id": 2,
    "query_name": "arp_cache",
    "query": "select * from arp_cache;",
    "interval": 604800,
    "snapshot": true,
    "removed": null,
    "platform": "",
    "shard": null,
    "denylist": null
  }
}

Remove query from schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

DELETE /api/v1/fleet/global/schedule/:id

Parameters

None.

Example

DELETE /api/v1/fleet/global/schedule/5

Default response

Status: 200

---

Team schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

• Get team schedule (deprecated)
• Add query to team schedule (deprecated)
• Edit query in team schedule (deprecated)
• Remove query from team schedule (deprecated)

This allows you to easily configure scheduled queries that will impact a whole team of devices.

Get team schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

GET /api/v1/fleet/teams/:id/schedule

Parameters

Example

GET /api/v1/fleet/teams/2/schedule

Default response

Status: 200

{
  "scheduled": [
    {
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "id": 4,
      "pack_id": 2,
      "name": "arp_cache",
      "query_id": 2,
      "query_name": "arp_cache",
      "query": "select * from arp_cache;",
      "interval": 120,
      "snapshot": true,
      "platform": "",
      "version": "",
      "removed": null,
      "shard": null,
      "denylist": null,
      "stats": {
        "system_time_p50": 1.32,
        "system_time_p95": 4.02,
        "user_time_p50": 3.55,
        "user_time_p95": 3.00,
        "total_executions": 3920
      }
    },
    {
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z",
      "id": 5,
      "pack_id": 3,
      "name": "disk_encryption",
      "query_id": 7,
      "query_name": "disk_encryption",
      "query": "select * from disk_encryption;",
      "interval": 86400,
      "snapshot": true,
      "removed": null,
      "platform": "",
      "version": "",
      "shard": null,
      "denylist": null,
      "stats": {
        "system_time_p50": 1.32,
        "system_time_p95": 4.02,
        "user_time_p50": 3.55,
        "user_time_p95": 3.00,
        "total_executions": 3920
      }
    }
  ]
}

Add query to team schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

POST /api/v1/fleet/teams/:id/schedule

Parameters

Example

POST /api/v1/fleet/teams/2/schedule

Request body

{
  "interval": 86400,
  "query_id": 2,
  "snapshot": true
}

Default response

Status: 200

{
  "scheduled": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 1,
    "pack_id": 5,
    "name": "arp_cache",
    "query_id": 2,
    "query_name": "arp_cache",
    "query": "select * from arp_cache;",
    "interval": 86400,
    "snapshot": true,
    "removed": null,
    "shard": null,
    "denylist": null
  }
}

Edit query in team schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

PATCH /api/v1/fleet/teams/:team_id/schedule/:scheduled_query_id

Parameters

Example

PATCH /api/v1/fleet/teams/2/schedule/5

Request body

{
  "interval": 604800
}

Default response

Status: 200

{
  "scheduled": {
    "created_at": "2021-07-16T14:40:15Z",
    "updated_at": "2021-07-16T14:40:15Z",
    "id": 5,
    "pack_id": 1,
    "name": "arp_cache",
    "query_id": 2,
    "query_name": "arp_cache",
    "query": "select * from arp_cache;",
    "interval": 604800,
    "snapshot": true,
    "removed": null,
    "platform": "",
    "shard": null,
    "denylist": null
  }
}

Remove query from team schedule

The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility. Please use the queries endpoints, which as of 4.35 have attributes such as interval and platform that enable scheduling.

DELETE /api/v1/fleet/teams/:team_id/schedule/:scheduled_query_id

Parameters

Example

DELETE /api/v1/fleet/teams/2/schedule/5

Default response

Status: 200

---

Scripts

• Run script
• Get script result
• Run live script
• Add script
• Delete script
• List scripts
• Get or download script
• Get script details by host

Run script

Run a script on a host.

The script will be added to the host's list of upcoming activities.

The new script will run after other activities finish. Failure of one activity won't cancel other activities.

POST /api/v1/fleet/scripts/run

Parameters

Note that if both script_id and script_contents are included in the request, this endpoint will respond with an error.

Example

POST /api/v1/fleet/scripts/run

Default response

Status: 202

{
  "host_id": 1227,
  "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002"
}

Get script result

Gets the result of a script that was executed.

Parameters

Example

GET /api/v1/fleet/scripts/results/:execution_id

Default Response

Status: 200

{
  "script_contents": "echo 'hello'",
  "exit_code": 0,
  "output": "hello",
  "message": "",
  "hostname": "Test Host",
  "host_timeout": false,
  "host_id": 1,
  "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002",
  "runtime": 20
}

Note: exit_code can be null if Fleet hasn't heard back from the host yet.

Run live script

Run a live script and get results back (5 minute timeout). Live scripts only runs on the host if it has no other scripts running.

POST /api/v1/fleet/scripts/run/sync

Parameters

Note that if both script_id and script_contents are included in the request, this endpoint will respond with an error.

Example

POST /api/v1/fleet/scripts/run/sync

Default response

Status: 200

{
  "host_id": 1227,
  "execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002",
  "script_contents": "echo 'hello'",
  "output": "hello",
  "message": "",
  "runtime": 1,
  "host_timeout": false,
  "exit_code": 0
}

Add script

Uploads a script, making it available to run on hosts assigned to the specified team (or no team).

POST /api/v1/fleet/scripts

Parameters

Example

POST /api/v1/fleet/scripts

Request headers

Content-Length: 306
Content-Type: multipart/form-data; boundary=------------------------f02md47480und42y

Request body

--------------------------f02md47480und42y
Content-Disposition: form-data; name="team_id"

1
--------------------------f02md47480und42y
Content-Disposition: form-data; name="script"; filename="myscript.sh"
Content-Type: application/octet-stream

echo "hello"
--------------------------f02md47480und42y--

Default response

Status: 200

{
  "script_id": 1227
}

Delete script

Deletes an existing script.

DELETE /api/v1/fleet/scripts/:id

Parameters

Example

DELETE /api/v1/fleet/scripts/1

Default response

Status: 204

List scripts

GET /api/v1/fleet/scripts

Parameters

Example

GET /api/v1/fleet/scripts

Default response

Status: 200

{
  "scripts": [
    {
      "id": 1,
      "team_id": null,
      "name": "script_1.sh",
      "created_at": "2023-07-30T13:41:07Z",
      "updated_at": "2023-07-30T13:41:07Z"
    },
    {
      "id": 2,
      "team_id": null,
      "name": "script_2.sh",
      "created_at": "2023-08-30T13:41:07Z",
      "updated_at": "2023-08-30T13:41:07Z"
    }
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

Get or download script

GET /api/v1/fleet/scripts/:id

Parameters

Example (get script)

GET /api/v1/fleet/scripts/123

Default response

Status: 200

{
  "id": 123,
  "team_id": null,
  "name": "script_1.sh",
  "created_at": "2023-07-30T13:41:07Z",
  "updated_at": "2023-07-30T13:41:07Z"
}

Example (download script)

GET /api/v1/fleet/scripts/123?alt=media

Example response headers

Content-Length: 13
Content-Type: application/octet-stream
Content-Disposition: attachment;filename="2023-09-27 script_1.sh"

Example response body

Status: 200

echo "hello"

Sessions

• Get session info
• Delete session

Get session info

Returns the session information for the session specified by ID.

GET /api/v1/fleet/sessions/:id

Parameters

Example

GET /api/v1/fleet/sessions/1

Default response

Status: 200

{
  "session_id": 1,
  "user_id": 1,
  "created_at": "2021-03-02T18:41:34Z"
}

Delete session

Deletes the session specified by ID. When the user associated with the session next attempts to access Fleet, they will be asked to log in.

DELETE /api/v1/fleet/sessions/:id

Parameters

Example

DELETE /api/v1/fleet/sessions/1

Default response

Status: 200

---

Software

• List software
• List software versions
• Get software
• Get software version

List software

Get a list of all software.

GET /api/v1/fleet/software/titles

Parameters

Example

GET /api/v1/fleet/software/titles

Default response

Status: 200

{
  "counts_updated_at": "2022-01-01 12:32:00",
  "count": 2,
  "software_titles": [
    {
      "id": 12,
      "name": "Firefox.app",
      "versions_count": 3,
      "source": "apps",
      "browser": "",
      "hosts_count": 48,
      "versions": [ 
        {
          "id": 123,
          "version": "1.12",
          "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"]
        }, 
        {
          "id": 124, 
          "version": "3.4",
          "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"]
        },
        {
          "id": 12
          "version": "1.13",
          "vulnerabilities": ["CVE-2023-1234","CVE-2023-4321","CVE-2023-7654"]
        }
      ]  
    },
    {
      "id": 22,
      "name": "Google Chrome.app",
      "versions_count": 5,
      "source": "apps",
      "browser": "",
      "hosts_count": 345,
      "versions": [
        {
          "id": 331,
          "version": "118.1",
          "vulnerabilities": ["CVE-2023-1234"]
        },
        {
          "id": 332,
          "version": "119.0",
          "vulnerabilities": ["CVE-2023-9876", "CVE-2023-2367"]
        },
        {
          "id": 334,
          "version": "119.4",
          "vulnerabilities": ["CVE-2023-1133", "CVE-2023-2224"]
        },
        {
          "id": 348,
          "version": "121.5",
          "vulnerabilities": ["CVE-2023-0987", "CVE-2023-5673", "CVE-2023-1334"]
        },
      ]
    },
    {
      "id": 32,
      "name": "1Password – Password Manager",
      "versions_count": 1,
      "source": "chrome_extensions",
      "browser": "chrome",
      "hosts_count": 345,
      "versions": [
        {
          "id": 4242,
          "version": "2.3.7",
          "vulnerabilities": []
        }
      ]
    }
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

List software versions

Get a list of all software versions.

GET /api/v1/fleet/software/versions

Parameters

Example

GET /api/v1/fleet/software/versions

Default response

Status: 200

{
    "counts_updated_at": "2022-01-01 12:32:00",
    "count": 1,
    "software": [
      {
        "id": 1,
        "name": "glibc",
        "version": "2.12",
        "source": "rpm_packages",
        "browser": "",
        "release": "1.212.el6",
        "vendor": "CentOS",
        "arch": "x86_64",
        "generated_cpe": "cpe:2.3:a:gnu:glibc:2.12:*:*:*:*:*:*:*",
        "vulnerabilities": [
          {
            "cve": "CVE-2009-5155",
            "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2009-5155",
            "cvss_score": 7.5,
            "epss_probability": 0.01537,
            "cisa_known_exploit": false,
            "cve_published": "2022-01-01 12:32:00",
            "cve_description": "In the GNU C Library (aka glibc or libc6) before 2.28, parse_reg_exp in posix/regcomp.c misparses alternatives, which allows attackers to cause a denial of service (assertion failure and application exit) or trigger an incorrect result by attempting a regular-expression match.",
            "resolved_in_version": "2.28"
          }
        ],
        "hosts_count": 1
      },
      {
        "id": 2,
        "name": "1Password – Password Manager",
        "version": "2.10.0",
        "source": "chrome_extensions",
        "browser": "chrome",
        "extension_id": "aeblfdkhhhdcdjpifhhbdiojplfjncoa",
        "generated_cpe": "cpe:2.3:a:1password:1password:2.19.0:*:*:*:*:chrome:*:*",
        "hosts_count": 345,
        "vulnerabilities": null
      }
    ],
    "meta": {
      "has_next_results": false,
      "has_previous_results": false
    }
}

Get software

Returns information about the specified software. By default, versions are sorted in descending order by the hosts_count field.

GET /api/v1/fleet/software/titles/:id

Parameters

Example

GET /api/v1/fleet/software/titles/12

Default response

Status: 200

{
  "software_title": {
    "id": 12,
    "name": "Firefox.app",
    "source": "apps",
    "browser": "",
    "hosts_count": 48,
    "versions": [ 
      {
        "id": 123,
        "version": "117.0",
        "vulnerabilities": ["CVE-2023-1234"],
        "hosts_count": 37
      },
      {
        "id": 124,
        "version": "116.0",
        "vulnerabilities": ["CVE-2023-4321"],
        "hosts_count": 7
      },
      {
        "id": 127,
        "version": "115.5",
        "vulnerabilities": ["CVE-2023-7654"],
        "hosts_count": 4
      }
    ]  
  }
}

Get software version

Returns information about the specified software version.

GET /api/v1/fleet/software/versions/:id

Parameters

Example

GET /api/v1/fleet/software/versions/12

Default response

Status: 200

{
  "software": {
    "id": 425224,
    "name": "Firefox.app",
    "version": "117.0",
    "bundle_identifier": "org.mozilla.firefox",
    "source": "apps",
    "browser": "",
    "generated_cpe": "cpe:2.3:a:mozilla:firefox:117.0:*:*:*:*:macos:*:*",
    "vulnerabilities": [
      {
        "cve": "CVE-2023-4863",
        "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2023-4863",
        "cvss_score": 8.8,
        "epss_probability": 0.4101,
        "cisa_known_exploit": true,
        "cve_published": "2023-09-12T15:15:00Z",
        "resolved_in_version": ""
      },
      {
        "cve": "CVE-2023-5169",
        "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2023-5169",
        "cvss_score": 6.5,
        "epss_probability": 0.00073,
        "cisa_known_exploit": false,
        "cve_published": "2023-09-27T15:19:00Z",
        "resolved_in_version": "118"
      }
    ]
  }
}

Vulnerabilities

• List vulnerabilities
• Get vulnerability

List vulnerabilities

Retrieves a list of all CVEs affecting software and/or OS versions.

GET /api/v1/fleet/vulnerabilities

Parameters

Default response

Status: 200

{
  "vulnerabilities": [
    {
      "cve": "CVE-2022-30190",
      "created_at": "2022-06-01T00:15:00Z",
      "hosts_count": 1234,
      "hosts_count_updated_at": "2023-12-20T15:23:57Z",
      "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190",
      "cvss_score": 7.8,// Available in Fleet Premium
      "epss_probability": 0.9729,// Available in Fleet Premium
      "cisa_known_exploit": false,// Available in Fleet Premium
      "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium
      "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability.",// Available in Fleet Premium
    }
  ],
  "count": 123,
  "counts_updated_at": "2024-02-02T16:40:37Z",
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

Get vulnerability

Retrieve details about a vulnerability and its affected software and OS versions.

Parameters

GET /api/v1/fleet/vulnerabilities/:cve

Example

GET /api/v1/fleet/vulnerabilities/cve-2022-30190

Default response

Status: 200

"vulnerability": {
  "cve": "CVE-2022-30190",
  "created_at": "2022-06-01T00:15:00Z",
  "hosts_count": 1234,
  "hosts_count_updated_at": "2023-12-20T15:23:57Z",
  "details_link": "https://nvd.nist.gov/vuln/detail/CVE-2022-30190",
  "cvss_score": 7.8,// Available in Fleet Premium
  "epss_probability": 0.9729,// Available in Fleet Premium
  "cisa_known_exploit": false,// Available in Fleet Premium
  "cve_published": "2022-06-01T00:15:00Z",// Available in Fleet Premium
  "cve_description": "Microsoft Windows Support Diagnostic Tool (MSDT) Remote Code Execution Vulnerability.",// Available in Fleet Premium
  "os_versions" : [
    {
      "os_version_id": 6,
      "hosts_count": 200,
      "name": "macOS 14.1.2",
      "name_only": "macOS",
      "version": "14.1.2",
      "platform": "darwin",
      "resolved_in_version": "14.2",
      "generated_cpes": [
        "cpe:2.3:o:apple:macos:*:*:*:*:*:14.2:*:*",
        "cpe:2.3:o:apple:mac_os_x:*:*:*:*:*:14.2:*:*"
      ]
    }
  ],
  "software": [
    {
      "id": 2363,
      "name": "Docker Desktop",
      "version": "4.9.1",
      "source": "programs",
      "browser": "",
      "generated_cpe": "cpe:2.3:a:docker:docker_desktop:4.9.1:*:*:*:*:windows:*:*",
      "hosts_count": 50,
      "resolved_in_version": "5.0.0"
    }
  ]
}

---

Targets

In Fleet, targets are used to run queries against specific hosts or groups of hosts. Labels are used to create groups in Fleet.

Search targets

The search targets endpoint returns two lists. The first list includes the possible target hosts in Fleet given the search query provided and the hosts already selected as targets. The second list includes the possible target labels in Fleet given the search query provided and the labels already selected as targets.

The returned lists are filtered based on the hosts the requesting user has access to.

POST /api/v1/fleet/targets

Parameters

Example

POST /api/v1/fleet/targets

Request body

{
  "query": "172",
  "selected": {
    "hosts": [],
    "labels": [7]
  },
  "include_observer": true
}

Default response

{
  "targets": {
    "hosts": [
      {
        "created_at": "2021-02-03T16:11:43Z",
        "updated_at": "2021-02-03T21:58:19Z",
        "id": 3,
        "detail_updated_at": "2021-02-03T21:58:10Z",
        "label_updated_at": "2021-02-03T21:58:10Z",
        "policy_updated_at": "2023-06-26T18:33:15Z",
        "last_enrolled_at": "2021-02-03T16:11:43Z",
        "software_updated_at": "2020-11-05T05:09:44Z",
        "seen_time": "2021-02-03T21:58:20Z",
        "hostname": "7a2f41482833",
        "uuid": "a2064cef-0000-0000-afb9-283e3c1d487e",
        "platform": "rhel",
        "osquery_version": "4.5.1",
        "os_version": "CentOS 6.10.0",
        "build": "",
        "platform_like": "rhel",
        "code_name": "",
        "uptime": 32688000000000,
        "memory": 2086899712,
        "cpu_type": "x86_64",
        "cpu_subtype": "142",
        "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz",
        "cpu_physical_cores": 4,
        "cpu_logical_cores": 4,
        "hardware_vendor": "",
        "hardware_model": "",
        "hardware_version": "",
        "hardware_serial": "",
        "computer_name": "7a2f41482833",
        "display_name": "7a2f41482833",
        "primary_ip": "172.20.0.3",
        "primary_mac": "02:42:ac:14:00:03",
        "distributed_interval": 10,
        "config_tls_refresh": 10,
        "logger_tls_period": 10,
        "additional": {},
        "status": "offline",
        "display_text": "7a2f41482833"
      },
      {
        "created_at": "2021-02-03T16:11:43Z",
        "updated_at": "2021-02-03T21:58:19Z",
        "id": 4,
        "detail_updated_at": "2021-02-03T21:58:10Z",
        "label_updated_at": "2021-02-03T21:58:10Z",
        "policy_updated_at": "2023-06-26T18:33:15Z",
        "last_enrolled_at": "2021-02-03T16:11:43Z",
        "software_updated_at": "2020-11-05T05:09:44Z",
        "seen_time": "2021-02-03T21:58:20Z",
        "hostname": "78c96e72746c",
        "uuid": "a2064cef-0000-0000-afb9-283e3c1d487e",
        "platform": "ubuntu",
        "osquery_version": "4.5.1",
        "os_version": "Ubuntu 16.4.0",
        "build": "",
        "platform_like": "debian",
        "code_name": "",
        "uptime": 32688000000000,
        "memory": 2086899712,
        "cpu_type": "x86_64",
        "cpu_subtype": "142",
        "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz",
        "cpu_physical_cores": 4,
        "cpu_logical_cores": 4,
        "hardware_vendor": "",
        "hardware_model": "",
        "hardware_version": "",
        "hardware_serial": "",
        "computer_name": "78c96e72746c",
        "display_name": "78c96e72746c",
        "primary_ip": "172.20.0.7",
        "primary_mac": "02:42:ac:14:00:07",
        "distributed_interval": 10,
        "config_tls_refresh": 10,
        "logger_tls_period": 10,
        "additional": {},
        "status": "offline",
        "display_text": "78c96e72746c"
      }
    ],
    "labels": [
      {
        "created_at": "2021-02-02T23:55:25Z",
        "updated_at": "2021-02-02T23:55:25Z",
        "id": 6,
        "name": "All Hosts",
        "description": "All hosts which have enrolled in Fleet",
        "query": "SELECT 1;",
        "label_type": "builtin",
        "label_membership_type": "dynamic",
        "host_count": 5,
        "display_text": "All Hosts",
        "count": 5
      }
    ],
    "teams": [
      {
        "id": 1,
        "created_at": "2021-05-27T20:02:20Z",
        "name": "Client Platform Engineering",
        "description": "",
        "agent_options": null,
        "user_count": 4,
        "host_count": 2,
        "display_text": "Client Platform Engineering",
        "count": 2
      }
    ]
  },
  "targets_count": 1,
  "targets_online": 1,
  "targets_offline": 0,
  "targets_missing_in_action": 0
}

---

Teams

• List teams
• Get team
• Create team
• Modify team
• Modify team's agent options
• Delete team

List teams

Available in Fleet Premium

GET /api/v1/fleet/teams

Parameters

Example

GET /api/v1/fleet/teams

Default response

Status: 200

{
  "teams": [
    {
      "id": 1,
      "created_at": "2021-07-28T15:58:21Z",
      "name": "workstations",
      "description": "",
      "agent_options": {
        "config": {
          "options": {
            "pack_delimiter": "/",
            "logger_tls_period": 10,
            "distributed_plugin": "tls",
            "disable_distributed": false,
            "logger_tls_endpoint": "/api/v1/osquery/log",
            "distributed_interval": 10,
            "distributed_tls_max_attempts": 3
          },
          "decorators": {
            "load": [
              "SELECT uuid AS host_uuid FROM system_info;",
              "SELECT hostname AS hostname FROM system_info;"
            ]
          }
        },
        "overrides": {},
        "command_line_flags": {}
      },
      "user_count": 0,
      "host_count": 0,
      "secrets": [
        {
          "secret": "",
          "created_at": "2021-07-28T15:58:21Z",
          "team_id": 10
        }
      ]
    },
    {
      "id": 2,
      "created_at": "2021-08-05T21:41:42Z",
      "name": "servers",
      "description": "",
      "agent_options": {
        "spec": {
          "config": {
            "options": {
              "pack_delimiter": "/",
              "logger_tls_period": 10,
              "distributed_plugin": "tls",
              "disable_distributed": false,
              "logger_tls_endpoint": "/api/v1/osquery/log",
              "distributed_interval": 10,
              "distributed_tls_max_attempts": 3
            },
            "decorators": {
              "load": [
                "SELECT uuid AS host_uuid FROM system_info;",
                "SELECT hostname AS hostname FROM system_info;"
              ]
            }
          },
          "overrides": {},
          "command_line_flags": {}
        },
        "user_count": 0,
        "host_count": 0,
        "secrets": [
          {
            "secret": "+ncixtnZB+IE0OrbrkCLeul3U8LMVITd",
            "created_at": "2021-08-05T21:41:42Z",
            "team_id": 15
          }
        ]
      }
    }
  ]
}

Get team

Available in Fleet Premium

GET /api/v1/fleet/teams/:id

Parameters

Example

GET /api/v1/fleet/teams/1

Default response

Status: 200

{
  "team": {
    "name": "Workstations",
    "id": 1,
    "user_count": 4,
    "host_count": 0,
    "agent_options": {
      "config": {
        "options": {
          "pack_delimiter": "/",
          "logger_tls_period": 10,
          "distributed_plugin": "tls",
          "disable_distributed": false,
          "logger_tls_endpoint": "/api/v1/osquery/log",
          "distributed_interval": 10,
          "distributed_tls_max_attempts": 3
        },
        "decorators": {
          "load": [
            "SELECT uuid AS host_uuid FROM system_info;",
            "SELECT hostname AS hostname FROM system_info;"
          ]
        }
      },
      "overrides": {},
      "command_line_flags": {}
    },
    "webhook_settings": {
      "failing_policies_webhook": {
        "enable_failing_policies_webhook": false,
        "destination_url": "",
        "policy_ids": null,
        "host_batch_size": 0
      }
    },
    "integrations": {
      "google_calendar": {
        "enable_calendar_events": true,
        "webhook_url": "https://server.com/example"
      }
    },
    "mdm": {
      "macos_updates": {
        "minimum_version": "12.3.1",
        "deadline": "2022-01-01"
      },
      "windows_updates": {
        "deadline_days": 5,
        "grace_period_days": 1
      },
      "macos_settings": {
        "custom_settings": ["path/to/profile1.mobileconfig"],
        "enable_disk_encryption": false
      },
      "windows_settings": {
        "custom_settings": ["path/to/profile2.xml"],
      },
      "macos_setup": {
        "bootstrap_package": "",
        "enable_end_user_authentication": false,
        "macos_setup_assistant": "path/to/config.json"
      }
    }
  }
}

Create team

Available in Fleet Premium

POST /api/v1/fleet/teams

Parameters

Example

POST /api/v1/fleet/teams

Request body

{
  "name": "workstations"
}

Default response

Status: 200

{
  "teams": [
    {
      "name": "workstations",
      "id": 1,
      "user_count": 0,
      "host_count": 0,
      "agent_options": {
        "config": {
          "options": {
            "pack_delimiter": "/",
            "logger_tls_period": 10,
            "distributed_plugin": "tls",
            "disable_distributed": false,
            "logger_tls_endpoint": "/api/v1/osquery/log",
            "distributed_interval": 10,
            "distributed_tls_max_attempts": 3
          },
          "decorators": {
            "load": [
              "SELECT uuid AS host_uuid FROM system_info;",
              "SELECT hostname AS hostname FROM system_info;"
            ]
          }
        },
        "overrides": {},
        "command_line_flags": {}
      },
      "webhook_settings": {
        "failing_policies_webhook": {
          "enable_failing_policies_webhook": false,
          "destination_url": "",
          "policy_ids": null,
          "host_batch_size": 0
        }
      }
    }
  ]
}

Modify team

Available in Fleet Premium

PATCH /api/v1/fleet/teams/:id

Parameters

Example (transfer hosts to a team)

PATCH /api/v1/fleet/teams/1

Request body

{
  "host_ids": [3, 6, 7, 8, 9, 20, 32, 44]
}

Default response

Status: 200

{
  "team": {
    "name": "Workstations",
    "id": 1,
    "user_count": 4,
    "host_count": 8,
    "agent_options": {
      "config": {
        "options": {
          "pack_delimiter": "/",
          "logger_tls_period": 10,
          "distributed_plugin": "tls",
          "disable_distributed": false,
          "logger_tls_endpoint": "/api/v1/osquery/log",
          "distributed_interval": 10,
          "distributed_tls_max_attempts": 3
        },
        "decorators": {
          "load": [
            "SELECT uuid AS host_uuid FROM system_info;",
            "SELECT hostname AS hostname FROM system_info;"
          ]
        }
      },
      "overrides": {},
      "command_line_flags": {}
    },
    "webhook_settings": {
      "failing_policies_webhook": {
        "enable_failing_policies_webhook": false,
        "destination_url": "",
        "policy_ids": null,
        "host_batch_size": 0
      }
    }
  }
}

Add users to a team

Available in Fleet Premium

PATCH /api/v1/fleet/teams/:id/users

Parameters

Example

PATCH /api/v1/fleet/teams/1/users

Request body

{
  "users": [
    {
      "id": 1,
      "role": "admin"
    },
    {
      "id": 17,
      "role": "observer"
    }
  ]
}

Default response

Status: 200

{
  "team": {
    "name": "Workstations",
    "id": 1,
    "user_count": 2,
    "host_count": 0,
    "agent_options": {
      "config": {
        "options": {
          "pack_delimiter": "/",
          "logger_tls_period": 10,
          "distributed_plugin": "tls",
          "disable_distributed": false,
          "logger_tls_endpoint": "/api/v1/osquery/log",
          "distributed_interval": 10,
          "distributed_tls_max_attempts": 3
        },
        "decorators": {
          "load": [
            "SELECT uuid AS host_uuid FROM system_info;",
            "SELECT hostname AS hostname FROM system_info;"
          ]
        }
      },
      "overrides": {},
      "command_line_flags": {}
    },
    "webhook_settings": {
      "failing_policies_webhook": {
        "enable_failing_policies_webhook": false,
        "destination_url": "",
        "policy_ids": null,
        "host_batch_size": 0
      }
    },
    "mdm": {
      "macos_updates": {
        "minimum_version": "12.3.1",
        "deadline": "2022-01-01"
      },
      "windows_updates": {
        "deadline_days": 5,
        "grace_period_days": 1
      },
      "macos_settings": {
        "custom_settings": ["path/to/profile1.mobileconfig"],
        "enable_disk_encryption": false
      },
      "windows_settings": {
        "custom_settings": ["path/to/profile2.xml"],
      },
      "macos_setup": {
        "bootstrap_package": "",
        "enable_end_user_authentication": false,
        "macos_setup_assistant": "path/to/config.json"
      }
    },
    "users": [
      {
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "id": 1,
        "name": "Example User1",
        "email": "[email protected]",
        "force_password_reset": false,
        "gravatar_url": "",
        "sso_enabled": false,
        "global_role": null,
        "api_only": false,
        "teams": null,
        "role": "admin"
      },
      {
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "id": 17,
        "name": "Example User2",
        "email": "[email protected]",
        "force_password_reset": false,
        "gravatar_url": "",
        "sso_enabled": false,
        "global_role": null,
        "api_only": false,
        "teams": null,
        "role": "observer"
      }
    ]
  }
}

Modify team's agent options

Available in Fleet Premium

POST /api/v1/fleet/teams/:id/agent_options

Parameters

Example

POST /api/v1/fleet/teams/1/agent_options

Request body

{
  "config": {
    "options": {
      "pack_delimiter": "/",
      "logger_tls_period": 20,
      "distributed_plugin": "tls",
      "disable_distributed": false,
      "logger_tls_endpoint": "/api/v1/osquery/log",
      "distributed_interval": 60,
      "distributed_tls_max_attempts": 3
    },
    "decorators": {
      "load": [
        "SELECT uuid AS host_uuid FROM system_info;",
        "SELECT hostname AS hostname FROM system_info;"
      ]
    }
  },
  "overrides": {},
  "command_line_flags": {}
}

Default response

Status: 200

{
  "team": {
    "name": "Workstations",
    "id": 1,
    "user_count": 4,
    "host_count": 8,
    "agent_options": {
      "config": {
        "options": {
          "pack_delimiter": "/",
          "logger_tls_period": 20,
          "distributed_plugin": "tls",
          "disable_distributed": false,
          "logger_tls_endpoint": "/api/v1/osquery/log",
          "distributed_interval": 60,
          "distributed_tls_max_attempts": 3
        },
        "decorators": {
          "load": [
            "SELECT uuid AS host_uuid FROM system_info;",
            "SELECT hostname AS hostname FROM system_info;"
          ]
        }
      },
      "overrides": {},
      "command_line_flags": {}
    },
    "webhook_settings": {
      "failing_policies_webhook": {
        "enable_failing_policies_webhook": false,
        "destination_url": "",
        "policy_ids": null,
        "host_batch_size": 0
      }
    }
  }
}

Delete team

Available in Fleet Premium

DELETE /api/v1/fleet/teams/:id

Parameters

Example

DELETE /api/v1/fleet/teams/1

Default response

Status: 200

---

Translator

• Translate IDs

Translate IDs

Transforms a host name into a host id. For example, the Fleet UI use this endpoint when sending live queries to a set of hosts.

POST /api/v1/fleet/translate

Parameters

Example

POST /api/v1/fleet/translate

Request body

{
  "list": [
    {
      "type": "user",
      "payload": {
        "identifier": "[email protected]"
      }
    },
    {
      "type": "label",
      "payload": {
        "identifier": "labelA"
      }
    },
    {
      "type": "team",
      "payload": {
        "identifier": "team1"
      }
    },
    {
      "type": "host",
      "payload": {
        "identifier": "host-ABC"
      }
    }
  ]
}

Default response

Status: 200

{
  "list": [
    {
      "type": "user",
      "payload": {
        "identifier": "[email protected]",
        "id": 32
      }
    },
    {
      "type": "label",
      "payload": {
        "identifier": "labelA",
        "id": 1
      }
    },
    {
      "type": "team",
      "payload": {
        "identifier": "team1",
        "id": 22
      }
    },
    {
      "type": "host",
      "payload": {
        "identifier": "host-ABC",
        "id": 45
      }
    }
  ]
}

---

Users

• List all users
• Create a user account with an invitation
• Create a user account without an invitation
• Get user information
• Modify user
• Delete user
• Require password reset
• List a user's sessions
• Delete a user's sessions

The Fleet server exposes a handful of API endpoints that handles common user management operations. All the following endpoints require prior authentication meaning you must first log in successfully before calling any of the endpoints documented below.

List all users

Returns a list of all enabled users

GET /api/v1/fleet/users

Parameters

Example

GET /api/v1/fleet/users

Request query parameters

None.

Default response

Status: 200

{
  "users": [
    {
      "created_at": "2020-12-10T03:52:53Z",
      "updated_at": "2020-12-10T03:52:53Z",
      "id": 1,
      "name": "Jane Doe",
      "email": "[email protected]",
      "force_password_reset": false,
      "gravatar_url": "",
      "sso_enabled": false,
      "global_role": null,
      "api_only": false,
      "teams": [
        {
          "id": 1,
          "created_at": "0001-01-01T00:00:00Z",
          "name": "workstations",
          "description": "",
          "role": "admin"
        }
      ]
    }
  ]
}

Failed authentication

Status: 401 Authentication Failed

{
  "message": "Authentication Failed",
  "errors": [
    {
      "name": "base",
      "reason": "Authentication failed"
    }
  ]
}

Create a user account with an invitation

Creates a user account after an invited user provides registration information and submits the form.

POST /api/v1/fleet/users

Parameters

Example

POST /api/v1/fleet/users

Request query parameters

{
  "email": "[email protected]",
  "invite_token": "SjdReDNuZW5jd3dCbTJtQTQ5WjJTc2txWWlEcGpiM3c=",
  "name": "janedoe",
  "password": "test-123",
  "password_confirmation": "test-123",
  "teams": [
    {
      "id": 2,
      "role": "observer"
    },
    {
      "id": 4,
      "role": "observer"
    }
  ]
}

Default response

Status: 200

{
  "user": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 2,
    "name": "janedoe",
    "email": "[email protected]",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "global_role": "admin",
    "teams": []
  }
}

Failed authentication

Status: 401 Authentication Failed

{
  "message": "Authentication Failed",
  "errors": [
    {
      "name": "base",
      "reason": "Authentication failed"
    }
  ]
}

Expired or used invite code

Status: 404 Resource Not Found

{
  "message": "Resource Not Found",
  "errors": [
    {
      "name": "base",
      "reason": "Invite with token SjdReDNuZW5jd3dCbTJtQTQ5WjJTc2txWWlEcGpiM3c= was not found in the datastore"
    }
  ]
}

Validation failed

Status: 422 Validation Failed

The same error will be returned whenever one of the required parameters fails the validation.

{
  "message": "Validation Failed",
  "errors": [
    {
      "name": "name",
      "reason": "cannot be empty"
    }
  ]
}

Create a user account without an invitation

Creates a user account without requiring an invitation, the user is enabled immediately. By default, the user will be forced to reset its password upon first login.

POST /api/v1/fleet/users/admin

Parameters

Example

POST /api/v1/fleet/users/admin

Request body

{
  "name": "Jane Doe",
  "email": "[email protected]",
  "password": "test-123",
  "teams": [
    {
      "id": 2,
      "role": "observer"
    },
    {
      "id": 3,
      "role": "maintainer"
    }
  ]
}

Default response

Status: 200

{
  "user": {
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "id": 5,
    "name": "Jane Doe",
    "email": "[email protected]",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "api_only": false,
    "global_role": null,
    "teams": [
      {
        "id": 2,
        "role": "observer"
      },
      {
        "id": 3,
        "role": "maintainer"
      }
    ]
  }
}

User doesn't exist

Status: 404 Resource Not Found

{
  "message": "Resource Not Found",
  "errors": [
    {
      "name": "base",
      "reason": "User with id=1 was not found in the datastore"
    }
  ]
}

Get user information

Returns all information about a specific user.

GET /api/v1/fleet/users/:id

Parameters

Example

GET /api/v1/fleet/users/2

Request query parameters

{
  "id": 1
}

Default response

Status: 200

{
  "user": {
    "created_at": "2020-12-10T05:20:25Z",
    "updated_at": "2020-12-10T05:24:27Z",
    "id": 2,
    "name": "Jane Doe",
    "email": "[email protected]",
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "global_role": "admin",
    "api_only": false,
    "teams": []
  }
}

User doesn't exist

Status: 404 Resource Not Found

{
  "message": "Resource Not Found",
  "errors": [
    {
      "name": "base",
      "reason": "User with id=5 was not found in the datastore"
    }
  ]
}

Modify user

PATCH /api/v1/fleet/users/:id

Parameters

Example

PATCH /api/v1/fleet/users/2

Request body

{
  "name": "Jane Doe",
  "global_role": "admin"
}

Default response

Status: 200

{
  "user": {
    "created_at": "2021-02-03T16:11:06Z",
    "updated_at": "2021-02-03T16:11:06Z",
    "id": 2,
    "name": "Jane Doe",
    "email": "[email protected]",
    "global_role": "admin",
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "api_only": false,
    "teams": []
  }
}

Example (modify a user's teams)

PATCH /api/v1/fleet/users/2

Request body

{
  "teams": [
    {
      "id": 1,
      "role": "observer"
    },
    {
      "id": 2,
      "role": "maintainer"
    }
  ]
}

Default response

Status: 200

{
  "user": {
    "created_at": "2021-02-03T16:11:06Z",
    "updated_at": "2021-02-03T16:11:06Z",
    "id": 2,
    "name": "Jane Doe",
    "email": "[email protected]",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "global_role": "admin",
    "teams": [
      {
        "id": 2,
        "role": "observer"
      },
      {
        "id": 3,
        "role": "maintainer"
      }
    ]
  }
}

Delete user

Delete the specified user from Fleet.

DELETE /api/v1/fleet/users/:id

Parameters

Example

DELETE /api/v1/fleet/users/3

Default response

Status: 200

Require password reset

The selected user is logged out of Fleet and required to reset their password during the next attempt to log in. This also revokes all active Fleet API tokens for this user. Returns the user object.

POST /api/v1/fleet/users/:id/require_password_reset

Parameters

Example

POST /api/v1/fleet/users/123/require_password_reset

Request body

{
  "require": true
}

Default response

Status: 200

{
  "user": {
    "created_at": "2021-02-23T22:23:34Z",
    "updated_at": "2021-02-23T22:28:52Z",
    "id": 2,
    "name": "Jane Doe",
    "email": "[email protected]",
    "force_password_reset": true,
    "gravatar_url": "",
    "sso_enabled": false,
    "global_role": "observer",
    "teams": []
  }
}

List a user's sessions

Returns a list of the user's sessions in Fleet.

GET /api/v1/fleet/users/:id/sessions

Parameters

None.

Example

GET /api/v1/fleet/users/1/sessions

Default response

Status: 200

{
  "sessions": [
    {
      "session_id": 2,
      "user_id": 1,
      "created_at": "2021-02-03T16:12:50Z"
    },
    {
      "session_id": 3,
      "user_id": 1,
      "created_at": "2021-02-09T23:40:23Z"
    },
    {
      "session_id": 6,
      "user_id": 1,
      "created_at": "2021-02-23T22:23:58Z"
    }
  ]
}

Delete a user's sessions

Deletes the selected user's sessions in Fleet. Also deletes the user's API token.

DELETE /api/v1/fleet/users/:id/sessions

Parameters

Example

DELETE /api/v1/fleet/users/1/sessions

Default response

Status: 200

Debug

• Get a summary of errors
• Get database information
• Get profiling information

The Fleet server exposes a handful of API endpoints to retrieve debug information about the server itself in order to help troubleshooting. All the following endpoints require prior authentication meaning you must first log in successfully before calling any of the endpoints documented below.

Get a summary of errors

Returns a set of all the errors that happened in the server during the interval of time defined by the logging_error_retention_period configuration.

The server only stores and returns a single instance of each error.

GET /debug/errors

Parameters

Example

GET /debug/errors?flush=true

Default response

Status: 200

[
  {
    "count": "3",
    "chain": [
      {
        "message": "Authorization header required"
      },
      {
        "message": "missing FleetError in chain",
        "data": {
          "timestamp": "2022-06-03T14:16:01-03:00"
        },
        "stack": [
          "github.com/fleetdm/fleet/v4/server/contexts/ctxerr.Handle (ctxerr.go:262)",
          "github.com/fleetdm/fleet/v4/server/service.encodeError (transport_error.go:80)",
          "github.com/go-kit/kit/transport/http.Server.ServeHTTP (server.go:124)"
        ]
      }
    ]
  }
]

Get database information

Returns information about the current state of the database; valid keys are:

• locks: returns transaction locking information.
• innodb-status: returns InnoDB status information.
• process-list: returns running processes (queries, etc).

GET /debug/db/:key

Parameters

None.

Get profiling information

Returns runtime profiling data of the server in the format expected by go tools pprof. The responses are equivalent to those returned by the Go http/pprof package.

Valid keys are: cmdline, profile, symbol and trace.

GET /debug/pprof/:key

Parameters

None.

API errors

Fleet returns API errors as a JSON document with the following fields:

• message: This field contains the kind of error (bad request error, authorization error, etc.).
• errors: List of errors with name and reason keys.
• uuid: Unique identifier for the error. This identifier can be matched to Fleet logs which might contain more information about the cause of the error.

Sample of an error when trying to send an empty body on a request that expects a JSON body:

$ curl -k -H "Authorization: Bearer $TOKEN" -H 'Content-Type:application/json' "https://localhost:8080/api/v1/fleet/sso" -d ''

Response:

{
  "message": "Bad request",
  "errors": [
    {
      "name": "base",
      "reason": "Expected JSON Body"
    }
  ],
  "uuid": "c0532a64-bec2-4cf9-aa37-96fe47ead814"
}

---