Set a collection field value
PUT /collections/{id}/fields/{field_id}
Stores one field’s value on a collection, replacing any value
already there. Put the value in the member the field’s type uses.
Any signed-in user can call this; if the field has a
write_capability, you need it granted globally. There is no check
that you own or may edit the collection.
The field must exist (404) and be a collection field (422). The
server then checks the write_capability (403), read_only (422),
the value’s member (422), the field’s pattern (422) and the guards
(400 when if_absent: true is sent with if_unchanged_since), then
the vocabulary and, for a reference, that the target asset exists
and isn’t deleted, and required last (all 422). Unlike on assets,
archived fields aren’t refused, a wrong member is 422 rather than
400, and an empty value_options list is accepted on a
multi_select field that isn’t required.
Each successful write gives the value a new set_at and records a
history entry in the same transaction. if_unchanged_since and
if_absent: true make the write conditional as on assets: on a
mismatch nothing is stored and you get 409 with the current value.
For a collection id that doesn’t exist, a write that has to insert a
value (unguarded or with if_absent: true) fails with a 500 error
rather than 404, while one guarded by if_unchanged_since gets 409
with no current value.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The collection’s id.
The field definition’s id.
Request Body required
Section titled “Request Body required ”The value to store. The members match the asset write: value_text
for text, longtext, rich_text, select and tree;
value_num for number, and for boolean as 1 or 0; value_date
for date and datetime; value_options for multi_select;
value_ref for reference. Other members are ignored, and a
missing member is refused with 422 (value_type_mismatch).
object
The value for a text, longtext, rich_text, select or tree field. Rich text is sanitized before it is stored.
The value for a number field, or 1 or 0 for a boolean field. It is read as a 32-bit floating-point number, so only about seven significant digits are kept.
The value for a date or datetime field.
The terms of a multi_select value, usually as slugs. Aliases and merged terms are redirected, a term repeated in the list is stored once, and an empty list is accepted unless the field is required.
For a reference field, the id of an asset that exists and isn’t deleted.
A label for where the value came from: manual (the default), api, import or computed.
Store the value only if the stored value still carries exactly this
set_at, copied from the last value you read or were sent; a
rounded time doesn’t match. If it has changed or been removed,
nothing is stored and you get 409 with the current state. The check
and the write are one database statement, and a write that succeeds
gets a new set_at from the database clock, so a second writer
holding the same token is normally refused. Sending it with
if_absent: true is refused with 400.
With true, store the value only if the field has no value on this
collection yet; if one exists, nothing is stored and you get 409
with it. false or leaving it out turns this check off, but an
if_unchanged_since you send still applies. Sending true with
if_unchanged_since is refused with 400.
Responses
Section titled “ Responses ”The value as stored.
One field value on a collection. Same shape as an asset field value,
with fewer set_by sources.
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.
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).