Rotating Managed Configuration Keys via Esper Blueprint API: Blueprint publish does not trigger device convergence

Android

When you update a managed configuration in an Esper Blueprint via API and set "publish": true, the Blueprint is promoted to its published state, but assigned devices do not automatically receive the update. Publishing and device convergence are separate operations. This article explains how to ensure your updated managed configurations are pushed to enrolled devices.

Before you begin

You'll need:

A Blueprint ID for the configuration you want to update
An Enterprise API key with Blueprint write access
The current managed configuration payload from your Blueprint

How to update a managed configuration and push it to devices

Follow this API workflow to update a managed configuration key and ensure assigned devices receive the change:

Identify the target Blueprint ID. List all Blueprints to find the relevant one:
```
GET https://{{tenant_name}}-api.esper.cloud/api/v2/blueprints/?limit=100&offset=0
```
Note the id field of the target Blueprint from the response.
Fetch current Blueprint details. Retrieve the existing managed configuration payload:
```
GET https://{{tenant_name}}-api.esper.cloud/api/v2/blueprints/{{blueprint_id}}/
```
Extract the current managed_config block to use as the base for your update.
Publish the Blueprint with the updated key. Submit the updated managed configuration via PUT with "publish": true:
```
PUT https://{{tenant_name}}-api.esper.cloud/api/v2/blueprints/{{blueprint_id}}/
```
In the request body, update the relevant key within the managed_config object and include:
```
"publish": true
```
Trigger device convergence. After publishing, explicitly dispatch a convergence command to push the updated Blueprint to all assigned devices. Refer to your Esper API documentation for the correct convergence or apply endpoint.
Verify the update. Confirm that devices have received the updated managed configuration by checking the device's Blueprint state in the Esper Console under Devices & Groups → [Device Name] → Blueprint, or by querying the device's applied configuration via the Device Details API.

Why devices don't automatically receive updates

The "publish": true parameter in the Blueprint PUT request only updates the Blueprint's published state. It does not trigger a convergence job on devices already assigned to that Blueprint. Publishing and converging are decoupled operations — a Blueprint can be published without all assigned devices being immediately instructed to converge to the new state.

When automating managed configuration updates via API, you must trigger convergence explicitly after publishing to push the new configuration to enrolled devices.

Troubleshooting

Convergence endpoint is unclear: Check your Esper API reference and search for converge or apply under the Blueprints section.

Devices show the Blueprint as applied, but the app isn't reading the updated key: Verify that the application is correctly reading from managed configurations at runtime. This is application-side behavior, outside Esper's scope.

PUT request returns an error or the Blueprint does not update: Verify that:

Your API key has sufficient permissions (Enterprise API key with Blueprint write access)
The full Blueprint payload is being passed in the PUT body — partial updates may not be supported

Convergence jobs are dispatched but devices aren't receiving updates: Contact Esper Support with details about the timeframe and affected devices.

Still need help?

If you're still experiencing issues with Blueprint convergence or managed configuration updates, submit a support ticket and include your Blueprint ID and the API requests you're sending.