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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The field definition’s id.
Request Body required
Section titled “Request Body required ”object
Slug of the term to merge away. It must be a term of this field and must not already be merged.
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.
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.
Report the counts without saving anything. Defaults to false.
Responses
Section titled “ Responses ”What the merge changed, or with dry_run, what it would change.
object
The source slug you sent, trimmed.
The target slug you sent, trimmed.
Whether this was a dry run.
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.
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.
Whether source is now merged into target. Always false on a dry
run.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedsource 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
A readable explanation of the refusal.
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 wrongvalue_*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 whensourceortargetisn’t a term.option_not_offerable: the term is deprecated or archived and the record didn’t already hold it. A merge uses it whentargetis archived orsourcehas already been merged.dangling_reference: areferencevalue 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 holdfields.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’sregexp_filter.field_required: the field is required, so its value can’t be set to empty or removed.
The code of the field that refused the value.
The term involved, for the vocabulary reasons (unknown_option,
option_not_offerable and vocabulary_extension_forbidden).
Unexpected server error
object
Human-readable error summary
Example
the request could not be completed