Skip to content

Merge one vocabulary term into another

POST
/fields/{id}/values/merge

Merges one term of a field’s vocabulary into another: every stored asset and collection value that uses source is changed to target, and source is kept as a retired term that points to target. Requires the fields.vocabulary.merge capability, granted globally; fields.admin doesn’t include it.

If you only want future values to resolve to another term, add an alias instead. Aliases change nothing already stored.

The merge changes this field’s values on every asset and collection that holds source, whoever owns them and whatever their visibility, and records each change in the value’s history. It doesn’t check the field’s write_capability or read_only setting. source becomes archived with replaced_by set to target, keeping its aliases and any child terms; target keeps its current status. Afterwards, a value written through the field-value routes that names source is redirected to target, or on to a later successor if target is merged too, as long as the links end at a term that isn’t archived; the result is then checked like any other value, so a deprecated target, for example, is accepted only on records that already hold it. The field’s upload default and team overrides aren’t updated: if they name source, new assets they apply to can keep receiving source until you change them.

source and target are slugs, trimmed but matched exactly, including case; labels and aliases don’t count. Both must be terms of this field. target can’t be archived, and a term that has already been merged can’t be merged again; a plain archived term can.

Send dry_run: true to see the counts first. A dry run does the same work and then undoes it, so it briefly locks the same rows, and a real merge afterwards can report different counts if values change in between. A real merge is written to the audit log with your reason and the counts after the change is saved; if writing that entry fails, the merge still stands.

id
required
string format: uuid

The field definition’s id.

object
source
required

Slug of the term to merge away. It must be a term of this field and must not already be merged.

string
target
required

Slug of the term to merge into. It must be a different term of this field and must not be archived; a deprecated term is accepted.

string
reason
required

Why the merge is right, in your own words. It is saved in the merge’s audit log entry, which is written after the merge and can be missing if that write fails. After trimming, it must be at least 3 bytes of UTF-8 text, so one or two non-ASCII characters can be enough; the 500-character limit shown isn’t checked.

string
>= 3 characters <= 500 characters
dry_run

Report the counts without saving anything. Defaults to false.

boolean

What the merge changed, or with dry_run, what it would change.

object
source
required

The source slug you sent, trimmed.

string
target
required

The target slug you sent, trimmed.

string
dry_run
required

Whether this was a dry run.

boolean
asset_values_rewritten
required

How many assets had source in this field and now have target. On a dry run, how many would have changed when the request ran; nothing is saved.

integer
collection_values_rewritten
required

How many collections had source in this field and now have target. On a dry run, how many would have changed when the request ran; nothing is saved.

integer
tombstoned
required

Whether source is now merged into target. Always false on a dry run.

boolean

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

source or target isn’t a term of this field, target is archived, or source has already been merged. option names the term.

Why a field value, or a vocabulary merge, was refused. field is the field’s code and option the term involved, so a client can point at the problem without reading error.

object
error
required

A readable explanation of the refusal.

string
reason
required

The kind of refusal:

  • field_not_for_collection: the field describes assets and can’t be set on a collection.
  • value_type_mismatch: the value was sent in the wrong value_* member for the field’s type.
  • unknown_option: the term isn’t in the field’s vocabulary at any level. A merge also uses it when source or target isn’t a term.
  • option_not_offerable: the term is deprecated or archived and the record didn’t already hold it. A merge uses it when target is archived or source has already been merged.
  • dangling_reference: a reference value names an asset that can’t be found. It is checked only when the value is written.
  • vocabulary_extension_forbidden: the field adds new terms, but you don’t hold fields.vocabulary.extend.
  • field_read_only: the field is read-only, so people can’t set or clear its values.
  • pattern_mismatch: the value doesn’t match the field’s regexp_filter.
  • field_required: the field is required, so its value can’t be set to empty or removed.
string
Allowed values: field_not_for_collection value_type_mismatch unknown_option option_not_offerable dangling_reference vocabulary_extension_forbidden field_read_only pattern_mismatch field_required
field

The code of the field that refused the value.

string
nullable
option

The term involved, for the vocabulary reasons (unknown_option, option_not_offerable and vocabulary_extension_forbidden).

string
nullable

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed