Skip to main content

Merge Tags

Merges several tags into a single tag. Every tag listed in MergeFrom is removed from the assets carrying it, and MergeTo is added to those assets in its place.

This is the supported way to rename a tag — merge the old name into the new one.

Request​

POST ~/api/tags/command/merge

Payload​

{
  "mergeTo": "Regression Tests",
  "mergeFrom": ["RegressionTests", "RegTests"]
}
FieldTypeRequiredDescription
mergeTostringyesThe surviving tag. May be an existing tag or an entirely new one.
mergeFromstring[]yesTags to collapse. Each is removed from every visible asset carrying it.
fieldstringnoA custom tag attribute to operate on instead of TaggedWith.
Casing on the wire

The published reference showed these fields PascalCased (MergeTo, MergeFrom). Both work — the server's JSON binding matches property names case-insensitively — but the API's JSON serializer is configured for camelCase, so mergeTo / mergeFrom is the canonical form and is what responses elsewhere in this API use. Existing integrations sending PascalCase do not need to change.

Request
curl -X POST "https://{host}/{instance}/api/tags/command/merge" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "mergeTo": "Regression Tests",
        "mergeFrom": ["RegressionTests", "RegTests"]
      }'
Merging into a new tag is allowed

mergeTo does not have to exist beforehand. Merging RegressionTests and RegTests into Regression Tests creates that tag on every affected asset even if nothing was tagged that way before.

Behavior​

  • An asset carrying more than one of the mergeFrom tags ends up with a single mergeTo tag, not duplicates.
  • An asset that already had mergeTo is not double-tagged.
  • Tags in mergeFrom 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.

Permissions and Scope​

Merge requires the ManageTags privilege.

A merge is only as wide as your visibility

The command acts only on assets the caller can see and edit. If you run it as a project-scoped member, the MergeFrom tags survive on assets outside your scope — and the response will not tell you. Run vocabulary cleanup as a member with instance-wide visibility, then re-check with query all tags to confirm the old names are gone.

There is no undo

Merge rewrites the TaggedWith attribute on every matching asset. There is no batch rollback. Before merging, capture the current state with query all tags, or query the affected assets and their tags via query.v1, so you can reconstruct if the merge turns out to be wrong.