---
title: "Using Desktop Tags in the Workspot Control API"
slug: "using-desktop-tags-in-the-workspot-control-api"
updated: 2024-07-16T14:08:19Z
published: 2024-07-16T14:08:19Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.workspot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Desktop Tags in the Workspot Control API

### **Introduction**

The Tags command for the [Workspot Control API](/v1/docs/using-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](/v1/docs/using-the-workspot-control-api) for basic information on using the API.

### **Setting Tags**

### **Syntax**

The following screenshot gives the format of the tags URL.

![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/b64fd00b-78a6-4165-bd51-2149ae835a94.png)

The body of the tag command is:

```json
{ "desktopId": "string", "poolId": "string", "tags": [ { "name": "string", "value": "string" } ]}
```

Where

- **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.

### **Limitations**

- 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**

### **Syntax**

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

![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/43b52f00-db30-4a3a-b9ce-8e7183d41deb.png)

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

```json
{  "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](/v1/docs/using-the-workspot-control-api)