Using Desktop Tags in the Workspot Control API

Robert Plamondon -


The Tags command for the Workspot Control API allows administrators to read and write up to five tags (text-based name:value pairs) per desktop.

Tags are available for persistent desktops only. They are available only through the Workspot Control API.

Once set, tags are displayed as part of the desktop details API command.

Note: See the Workspot Control API for basic information on using the API.

Setting Tags


The following screen shot gives the format of the tags URL.


The body of the tag command is:

"desktopId": "string",
"poolId": "string",
"tags": [
"name": "string",
"value": "string"


  • desktopId is the identifier for the desired desktop (from the desktops API command),
  • poolId is the identifier for the desired pool (from the pools API command),
  • name and value are the name:value pairs for the tags.


  • Tags are valid only for persistent desktop pools.
  • No more than five tags may be set per desktop.
  • The tag command must contain at least one tag.
  • The tag command must contain no duplicate tags.
  • All previous tags are deleted when you write a tag. To preserve tags, read the old tags, update or add the desired tags, then write the tags.
  • Length limitations:
    • Maximum of 2048 characters for all tags in a desktop.
    • Maximum of 128 characters per tag name.
    • Maximum of 512 characters per tag value.
  • Reserved characters: < > % & \ ? /
  • Desktop state limitations
    • Tagging allowed: Online, Offline, Rebooting, Redeploy, Ready, Connect, Disconnect, Suspended
    • Tagging NOT allowed: Failed, Deleting, Provisioning.
  • Tags are kept if a new desktop template is applied.
  • Tags are lost when:
    • The desktop is recreated via Auto create
    • The desktop is deleted.

Reading Tags


The tag list is returned as part of the desktop details command, shown below:


The tags are returned in the body of the command, as shown below:

  "email": "string",
  "fqdn": "string",
  "id": "string",
  "ipAddress": "string",
  "name": "string",
  "poolId": "string",
  "poolName": "string",
  "status": "string",
  "tags": [
      "name": "string",
      "value": "string"


Related Document

Using the Workspot Control API

Have more questions? Submit a request


Powered by Zendesk