REST API & Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Fleet REST API serves as the programmatic interface for interacting with the Fleet server, enabling automation, integration, and custom data visualization. Everything achievable within the Fleet UI can be performed via the REST API, which allows IT and security teams to manage endpoints, policies, and queries at scale.
The API architecture is designed to support various consumers, including the Fleet UI itself, the fleetctl CLI tool, and external integrations like Slack bots or custom dashboards. It provides access to telemetry data from hosts running osquery, vulnerability assessments, and configuration management capabilities.
Sources: articles/building-an-effective-dashboard-with-fleet-rest-api-flask-and-plotly.md:8-15, tools/fleet-slackbot/system-prompt.js:3-10, handbook/product-design/README.md:27-30
API Architecture and Consumers
Fleet utilizes a standard RESTful architecture where endpoints are accessed via HTTP methods. The system ensures consistency between the UI and API by using the same underlying logic for both.
Primary Consumers
- Fleet UI: The web interface for human operators.
- fleetctl: The command-line tool for GitOps workflows and automation.
- External Dashboards: Custom applications built using frameworks like Flask and Plotly to visualize host status.
- Fleet Slackbot: An AI-assisted interface that uses Fleet tools to retrieve information or propose configuration changes via GitOps.
Sources: articles/building-an-effective-dashboard-with-fleet-rest-api-flask-and-plotly.md:8-10, 24-28, tools/fleet-slackbot/system-prompt.js:3-8, handbook/product-design/README.md:27-30
Interaction Flow
The following diagram illustrates how different components interact with the Fleet REST API to retrieve data or enact changes.
The diagram shows the centralization of the REST API as the gateway for all management interfaces, including the UI, CLI, and automated bots, which ultimately interact with the database and managed hosts.
Core API Functional Areas
The API is organized into functional areas reflecting the lifecycle of device management and security operations.
Information Retrieval and Telemetry
The API provides endpoints to query host details, platform distribution, and compliance status. This includes real-time data retrieval via live osquery execution against endpoints.
| Function Category | Description | Key Capabilities |
|---|---|---|
| Endpoint Management | Host inventory and status | Get endpoint counts, platform distribution, and individual host details. |
| Policies & Compliance | Security posture monitoring | Retrieve policy compliance results and identify failing hosts. |
| Vulnerability Assessment | CVE impact analysis | Look up vulnerability impact using CISA KEV and EPSS data. |
| Live Queries | Ad-hoc SQL execution | Run osquery SQL against live hosts for data not already cached in Fleet. |
Sources: tools/fleet-slackbot/system-prompt.js:20-40, articles/building-an-effective-dashboard-with-fleet-rest-api-flask-and-plotly.md:52-55
Configuration and GitOps
Fleet emphasizes GitOps-native workflows. The API supports managing YAML-based configurations for fleets, policies, and software.
Configuration changes are often proposed as JSON objects that result in GitOps YAML updates, which are then submitted as GitHub pull requests.
Sources: tools/fleet-slackbot/system-prompt.js:10-15, 345-355, handbook/product-design/README.md:32-35
Endpoint Categories and Routing
Fleet documentation and website content distinguish between different categories of endpoints and resources available via the API and web interface.
Static and Dynamic Content Routing
The website build process maps various documentation and resource files to specific URL paths, which often correlate with API resource names.
- /reports: Informational and standard queries.
- /policies: Policy-related results and remediation steps.
- /tables: Documentation for the osquery schema and Fleet schema overrides.
- /software-catalog: Inventory of maintained applications.
- /mdm-commands: Platform-specific MDM instructions (Windows XML or Apple plist).
Sources: website/api/controllers/download-sitemap.js:65-100, website/scripts/build-static-content.js:203-220
Live API Interaction Logic
For developers building integrations, the following logic applies when interacting with live data:
- Summary First: Prefer aggregate tools (e.g.,
get_aggregate_platforms) before drilling into individual host details. - Cached Data: Use existing policy results (
get_host_policies) instead of running live queries for data Fleet already tracks. - Live Execution: Use
prepare_live_queryfollowed byrun_live_queryonly for ad-hoc data needs.
Sources: tools/fleet-slackbot/system-prompt.js:25-35, 60-70
API Documentation and Design Process
Fleet follows a "wireframe-first" and "design-first" approach for API changes. Every change to the REST API or YAML schema is wireframed and reviewed before implementation.
Design Workflow
- User Story: A requirement is identified.
- API/YAML Design: If the story requires API changes, a PR is opened against the reference documentation branch (e.g.,
docs-v4.61.0). - Consistency Check: Designers ensure consistent URL structures, parameter naming, and response formats.
- Review: The API design DRI approves the changes before they are merged into the release branch.
Sources: handbook/product-design/README.md:120-135, 235-245
Example Integration (Flask/Python)
Integrating with the Fleet API typically involves the requests library in Python to fetch JSON data from endpoints.
import requests
# Example of calling a Fleet endpoint
response = requests.get(
'https://fleet.example.com/api/v1/fleet/hosts',
headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
hosts_data = response.json()
Sources: articles/building-an-effective-dashboard-with-fleet-rest-api-flask-and-plotly.md:65-75
Summary
The REST API & Endpoints module provides a comprehensive, design-driven interface for all Fleet functionality. By centralizing management through a standard API, Fleet enables flexible consumption via the UI, CLI, and custom integrations, while maintaining a strong GitOps-native workflow for configuration and security policy management. The design process ensures that any changes to this surface are vetted for technical consistency and user benefit prior to release.