Skip to content

Fetch Blueprint Drift status for devices

Request

Fetches Blueprint Drift status for a set of devices.

Returns each requested device's current Blueprint Drift state (compliant, drifted, or unknown) in a single call, given a list of device IDs. 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 Status Blueprint Drift detects when a device's actual configuration diverges from its assigned Blueprint. This endpoint is the per-device counterpart to the fleet-wide summary, letting you check drift status for a specific set of devices at once.

Key Fields / Query Parameters

  • device_ids — List of device UUIDs to check drift status for

Common Use Cases

  • Checking drift status for a specific group of devices before or after a remediation effort
  • Confirming devices returned to compliant status after a config fix
  • Building a device-list view filtered or annotated by drift status

Best Practices

  • Batch device_ids in a single call rather than checking devices one at a time
  • Treat unknown status as meaning insufficient state data has been reported yet, not necessarily non-compliant
  • Use the per-setting audit endpoint for any device showing drifted status to see exactly what differs

Workflow

  1. Gather the device_ids to check
  2. GET this endpoint with those device_ids
  3. For any device showing drifted, call GET /v2/blueprint-drift/{deviceId}/status for per-setting detail
Security
drift_apiKey
Query
device_idsstring, <= 10000 characters^([0-9a-fA-F\\-]{36})(,([0-9a-fA-F\\-]{36}))*$required

Comma-separated list of device UUIDs (max 100 ids). Devices not found return with state: unknown in the response.

Example:device_ids=550e8400-e29b-41d4-a716-446655440001,550e8400-e29b-41d4-a716-446655440002
cURL
curl -i -X GET \
  'https://develop-api.esper.io/_mock/openapi/v2/blueprint-drift/status?device_ids=550e8400-e29b-41d4-a716-446655440001%2C550e8400-e29b-41d4-a716-446655440002' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Blueprint Drift status result set

Bodyapplication/json
resultsArray of objects(drift_BlueprintDriftStatusItem)required
Response
{
  "results": [
    { … }
  ]
}