Commands API 403/404 on status read + Blueprint converge via API: use v0 Commands path and Operations API

Android

If you're using the Esper Commands API or Operations API to manage devices, you may encounter 403 or 404 errors when reading command status, or 404 errors when triggering a Blueprint converge. This article explains why these errors occur and how to resolve them.

Understanding the issue

The Esper platform has two separate command API namespaces that can cause confusion:

• Legacy path: /api/v0/enterprise/{ent}/command/ — the older command namespace
• Current path: /api/commands/v0/commands/ — the current command namespace

If you create a command using the current path but try to read its status from the legacy path, you'll receive a 403 or 404 error because the command doesn't exist in that namespace. Similarly, the Blueprint REST endpoints are not the correct method for triggering a converge programmatically — you must use the Operations API instead.

How to read command status correctly

1. Verify you're polling the same API path used to create the command. Commands created via POST /api/commands/v0/commands/ must be read via GET /api/commands/v0/commands/{command_id}/.
2. Do not attempt to read command status from the legacy endpoint /api/v0/enterprise/{ent}/command/ — commands created on the current path will not be present there.
3. To list all commands and their statuses for a specific device, use:

   GET /api/commands/v0/commands/?device_id=<device-uuid>

4. Verify the response includes a status field reflecting the current state (for example, QUEUED, INITIATED, SUCCEEDED, or FAILED). A 200 response with status data confirms the path mismatch is resolved.

How to trigger a Blueprint converge via API

1. Do not use /api/enterprise/{ent}/blueprint/ or /api/v0/enterprise/{ent}/blueprint/ to trigger a converge — these endpoints are not supported for this purpose.
2. Use the Operations API to initiate a converge. To converge all provisioned devices in a group, make a request like this:

   curl -i -X POST \
   https://<tenant-name>-api.esper.cloud/api/v0/operations/ \
   -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
   -H 'Content-Type: application/json' \
   -d '{
    "operation_type": "CONVERGE",
    "schedule_type": "IMMEDIATE",
    "operation_device_query": {
    "device_request": {
    "state": "1",
    "group": "<group-uuid>"
    }
    }
   }'

   Replace <tenant-name>, <YOUR_API_TOKEN>, and <group-uuid> with your tenant-specific values.
3. To converge a specific device instead of a group, replace the device_request object with a device-level selector targeting the device UUID.
4. Verify the Operations API returns a 201 response with an operation ID. You can then poll GET /api/v0/operations/{operation_id}/ to track converge status.

How to verify API token permissions

If you continue to receive errors, check your API token permissions:

• 403 on /api/commands/v0/commands/: Verify your API token has the command:read scope (or equivalent) assigned in the Esper Console under Settings → API Management.
• Operations API returns 403: Confirm your API token has Operations-level write scope. Tokens with read-only scopes cannot create operations.
• Operations API returns 404: Confirm you're using the correct tenant name in the base URL (<tenant-name>-api.esper.cloud). Do not use the Esper Console URL.
• Converge operation completes but Blueprint is not applied: Verify the Blueprint is published and correctly assigned to the target group or devices in the Esper Console under Devices & Groups → [Group Name] → Blueprint.

Still need help?

If these steps don't resolve your issue, contact Esper Support and provide:

• Your tenant ID
• Your Enterprise ID
• The specific API token scope list
• Example request and response pairs (with tokens redacted)
• The Esper Agent version on affected devices