Skip to content

Update tags associated with a device.
Stable

Request

Updates the tags associated with a device.

Applies tag changes incrementally via add and remove lists, for a single enrolled Apple, Linux, or Windows device identified by UUID.

About Device Tags Device tags are free-form labels that can be used to organize and filter devices (for example, in the Device Telemetry report's tags filter) independently of device groups. This endpoint currently applies to Apple, Linux, and Windows devices.

Key Fields / Query Parameters

  • id — UUID of the device to update tags for
  • add — List of tags to add to the device
  • remove — List of tags to remove from the device

Common Use Cases

  • Tagging a device for a temporary pilot or campaign without changing its device group
  • Bulk-organizing devices by attributes not covered by groups (e.g., ownership, condition, project)
  • Removing outdated tags as a device's status changes

Best Practices

  • Use add/remove incrementally rather than trying to replace the full tag set in one call, since the API is additive/subtractive by design
  • Keep a consistent tagging convention across the fleet so tags remain useful for filtering in reports
  • Confirm the device platform — this endpoint currently supports Apple, Linux, and Windows devices, not Android
Security
device_apiKey
Path
idstring, (uuid)required

ID of the device

Bodyapplication/jsonrequired
Any of:

Either 'add' or 'remove' must be non-empty. A tag ID must not appear in both 'add' and 'remove' in the same request; this cross-array constraint cannot be expressed in OpenAPI 3.0 and is enforced server-side.

addArray of strings, [ 1 .. 5 ] items, uniquerequired
removeArray of strings, <= 5 items, unique
cURL
curl -i -X PUT \
  'https://api.esper.io/_mock/openapi/v2/devices/{id}/tags/' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "add": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "remove": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  }'

Responses

Success

Bodyapplication/json
contentobject(device_DeviceTagsResponse)
Response
{
  "content": {
    "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
    "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    "tag_ids": [ … ]
  }
}