Skip to main content

Remove Tags

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​

POST ~/api/tags/command/remove

Payload​

{
  "removeFrom": ["RegressionTests", "RegTests"]
}
FieldTypeRequiredDescription
removeFromstring[]yesThe tags to remove. Each is stripped from every visible asset carrying it.
fieldstringnoA custom tag attribute to operate on instead of TaggedWith.
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"] }'
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 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.

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 and keep the result.

If your goal is to rename rather than purge, use merge instead: it preserves the association under a new name.