Clear a collection field value
DELETE /collections/{id}/fields/{field_id}
Removes one field’s value from a collection. Any signed-in user can
call this; clearing doesn’t check the field’s write_capability,
whether it is a collection field, or whether you may edit the
collection.
A read_only or required field is refused with 422. Without
if_unchanged_since the removal is unconditional and answers 204
whether or not a value was there, even for a field id that matches
no field. With it, only a value carrying exactly that set_at is
removed; otherwise you get 409 with the current state, and an
unknown field is 404. Removing an existing value records an entry in
its history.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The collection’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.
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 on a collection 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.
object
A readable explanation of the refusal.
The field whose value wasn’t changed.
Whether the field has a value on this collection now.
The value as stored now, 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. Left out when it is empty.
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 by default, or the api, import or computed label a writer sent.
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).