Skip to content

Blueprint Drift

APIs to fetch device Blueprint Drift status

Operations

Fetch Blueprint Drift summary counts for a tenant

Request

Fetches Blueprint Drift summary counts for a tenant.

Returns the number of devices grouped by their highest Blueprint Drift severity, giving a tenant-wide, at-a-glance view of fleet configuration compliance. Reponse varies by customer and feature availibility. Non-Architect customer where Blueprint Drift is not enabled returns an empty response. Architect customers where Blueprint Drift is not enabled due to not meeting the Esper Agent eligibility criteria returns a Version Mismatch response. Architect customers where Blueprint Drift is enabled returns the full Blueprint Drift response, including drift details.

About Blueprint Drift Summary Blueprint Drift detects when a device's actual configuration diverges from the Blueprint it was assigned, using state reported via the device state-report ingestion endpoint. This summary endpoint aggregates that per-device drift status into fleet-wide severity counts.

Common Use Cases

  • Powering a fleet-wide compliance dashboard showing how many devices have drifted from their Blueprint
  • Prioritizing remediation by severity across the fleet
  • Tracking drift trends over time by polling this summary periodically

Best Practices

  • Use this summary for dashboard-level reporting, and drill into the status/per-device endpoints when investigating specific devices
  • Poll on a reasonable interval appropriate for a compliance dashboard rather than continuously
  • Pair with the per-device status endpoint to identify which specific devices need attention within a severity bucket

Workflow

  1. GET this endpoint for the tenant-wide severity breakdown
  2. Use GET /v2/blueprint-drift/status to identify which devices fall into a severity bucket of interest
  3. Use GET /v2/blueprint-drift/{deviceId}/status for per-setting detail on a specific device
Security
drift_apiKey
cURL
curl -i -X GET \
  https://develop-api.esper.io/_mock/openapi/v2/blueprint-drift/summary \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Blueprint Drift summary counts

Bodyapplication/json
drifted_totalintegerrequired

Devices with drifted settings (highest severity shown in breakdown fields)

compliant_totalintegerrequired

Devices with no drifted settings

critical_totalintegerrequired

Drifted devices whose highest severity is critical

major_totalintegerrequired

Drifted devices whose highest severity is major

minor_totalintegerrequired

Drifted devices whose highest severity is minor

log_only_totalintegerrequired

Drifted devices whose highest severity is log_only

Response
{
  "drifted_total": 0,
  "compliant_total": 0,
  "critical_total": 0,
  "major_total": 0,
  "minor_total": 0,
  "log_only_total": 0
}