Clear an asset field value
DELETE /assets/{id}/fields/{field_id}
Removes one field’s value from an asset. Any signed-in user can call
this. Unlike setting a value, clearing doesn’t check the field’s
write_capability, and for an ordinary field there is no check that
you own or may edit the asset; fields that mirror the asset’s
title or description need permission to edit the asset.
A read_only field is refused with 422, and so is a required one;
archived fields can be cleared. Without if_unchanged_since the
removal is unconditional: you get 204 whether or not a value was
there, even when the field id matches no field. With it, only a
value carrying exactly that set_at is removed; if the value
changed or is already gone you get 409 with the current state, and a
field id that matches no field is 404. Removing an existing value
records an entry in its history.
Fields that mirror the asset’s title or description are cleared
by writing an empty value to the asset: the asset edit permission
applies (403), a missing or deleted asset is 404, the guard is
refused with 400, a required mirrored field can’t be cleared (400)
and no field history is recorded.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
The field definition’s id.
Query Parameters
Section titled “Query Parameters ”Remove the value only if it still carries exactly this set_at,
copied from the last value you read. Otherwise nothing is removed
and you get 409 with the value as it is now, or with present: false if it’s gone. Leave it out for an unconditional removal.
Refused with 400 on a field that mirrors an asset column.
Responses
Section titled “ Responses ”The value was removed, or there was nothing to remove.
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 completedThe stored value isn’t the version you guarded against, so nothing was changed.
Why a conditional write or removal wasn’t applied: the stored value
isn’t the version you guarded against, and nothing was changed.
present and current show the state as read just after the
refusal, so you can decide what to do without another request.
object
A readable explanation of the refusal.
The field whose value wasn’t changed.
Whether the field has a value on this asset now.
The value as stored now, with the set_at to guard a retry with, or
null when there is no value. It is returned without checking the
field’s read_capability.
object
The field definition’s id.
The field’s code.
The field’s label.
The field’s type, which decides the member that holds the value.
The value of a text, longtext, rich_text, select or tree field. Rich text is sanitized when it is written and again when it is read.
The value of a number field, or 1 or 0 for a boolean field. It is carried as a 32-bit floating-point number, so about seven significant digits survive.
The value of a date or datetime field.
The terms of a multi_select value, as slugs. Left out when there are none.
The id of the asset a reference value points to.
Where the value came from. manual is the default for values
written through this API, and a writer can label its value exif,
iptc, xmp, api, import or computed instead. default
marks a value placed by an upload default, and mirror marks a
field that shows the asset’s own title or description, where
set_at is the asset’s updated_at and there is no
set_by_user_ref. The write route doesn’t stop a client from
sending default itself, so treat the label as information, not
proof.
When the value was last written. Send it back as if_unchanged_since to guard a change.
The account that last wrote the value, when one is recorded.
Display data for the terms this value holds, keyed by slug, on
select, multi_select and tree fields. A slug that isn’t in the
field’s vocabulary has no entry; show the slug itself.
object
How to display one vocabulary term. The term’s slug is the key it is listed under.
object
The term’s display text, or its slug when it has no label.
The term’s lifecycle state. Show anything other than active as
retired or on its way out.
For a term below the top of a tree, the labels from the top level down to this term. Left out for top-level terms.
The asset a reference value points to, with its title for display.
It is filled in when the value is read from the database, and only
if that asset exists and isn’t deleted at that moment; otherwise
show the bare value_ref. Collection values come from a cache, so a
reference there can still show an asset that has since been deleted
or renamed. Whether you may see that asset isn’t checked.
object
The referenced asset’s id, the same as value_ref.
The referenced asset’s title, which can be empty; show the id when it is.
The value can’t be stored or removed. reason says why, field
names the field and, for vocabulary refusals, 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).