# Replace a machine's tags

Source: https://www.jawsdeploy.net/rest-api/machines-tags-replace | Section: Machines

Set the complete list of tags a machine carries.

`PUT /api/machine/tags`

Replaces the machine's tags with **exactly** the ones you send. Tags the machine has that are not in the list are removed, and any in the list that it does not have are added.

To add or remove a single tag while leaving the rest alone, use [Assign a tag](https://www.jawsdeploy.net/rest-api/machines-tag-assign) or [Unassign a tag](https://www.jawsdeploy.net/rest-api/machines-tag-unassign) instead. The machine's current tags are returned by [List machines](https://www.jawsdeploy.net/rest-api/machines-list).

Every ID must name a tag in the **same workspace as the machine**. If any one of them does not, the whole call is refused and nothing is changed. Duplicate IDs are collapsed rather than rejected.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `machineId` | body | string | yes | ID of the machine, from [List machines](https://www.jawsdeploy.net/rest-api/machines-list). |
| `tagIds` | body | array<string> | yes | The complete set of tag IDs, from [List tags](https://www.jawsdeploy.net/rest-api/tags-list), the machine should carry. Send `[]` to remove all tags. |

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid `machineId`. A machine that belongs to another organization is reported the same way as one that does not exist. |
| 400 | One or more tag IDs are invalid for this workspace. Nothing is changed. |
| 401 | Missing or invalid Basic auth credentials, or the service account lacks permission to manage machines in this workspace. |

Example request:

```
PUT /api/machine/tags HTTP/1.1
Authorization: Basic <base64(...)>
Content-Type: application/json

{
  "machineId": "mch_web01",
  "tagIds": ["tag_web", "tag_canary"]
}
```

Example response:

```
{}
```