---
id: tags-remove
slug: /apis/tags/remove
title: 'Remove Tags'
description: 'Purge tags from every asset carrying them with POST ~/api/tags/command/remove.'
sidebar_label: 'Remove Tags'
sidebar_position: 6
tags: ['api', 'tags', 'admin']
---

Removes the specified tags from every asset they exist on. Because a tag has no existence
independent of the assets carrying it, removing it from every asset removes it from the
instance.

## Request

```text
POST ~/api/tags/command/remove
```

### Payload

```json
{
  "removeFrom": ["RegressionTests", "RegTests"]
}
```

| Field        | Type     | Required | Description                                                                                     |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------ |
| `removeFrom` | string[] | yes      | The tags to remove. Each is stripped from every visible asset carrying it.                       |
| `field`      | string   | no       | A [custom tag attribute](/apis/tags/query#custom-tag-fields) to operate on instead of `TaggedWith`. |

```bash title="Request"
curl -X POST "https://{host}/{instance}/api/tags/command/remove" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "removeFrom": ["RegressionTests", "RegTests"] }'
```

:::warning Older documentation showed the wrong payload
Earlier reference material showed the **merge** payload — `MergeTo` plus
`MergeFrom` — for this endpoint. That shape is wrong here: the endpoint binds
`removeFrom` and `field`, and a request using the merge fields is **rejected
with `400 Bad Request`**. If you built an integration from the old example,
it stopped at the door — correct the payload to `removeFrom`.
:::

## Behavior

- Tags in `removeFrom` that do not exist are ignored rather than erroring.
- The operation writes to every affected asset, so it appears in asset history and
  [activity stream](/apis/activity-stream) output attributed to the calling member.
- Other tags on those assets are untouched.

## Permissions and Scope

Remove requires the **`ManageTags`** privilege, and acts only on assets the caller can see and
edit — the same limitation described for [merge](/apis/tags/merge#permissions-and-scope).

:::danger There is no undo
Removal rewrites the `TaggedWith` attribute on every matching asset and cannot be batch-reversed.
If you may need the association back, capture it first — query the affected assets and their
tags through [`query.v1`](/apis/query-v1) and keep the result.

If your goal is to rename rather than purge, use [merge](/apis/tags/merge) instead: it preserves
the association under a new name.
:::

## Related Topics

- [Merge tags](/apis/tags/merge)
- [Query all tags](/apis/tags/query-all) — verify the tag is gone afterwards
- [Tags overview](/apis/tags)