Set an asset field value
PUT /assets/{id}/fields/{field_id}
Stores one field’s value on an asset, replacing any value already
there. Put the value in the member the field’s type uses (see the
request body). Any signed-in user can call this; if the field has a
write_capability, you need it granted globally. For an ordinary
field there is no check that you own or may edit the asset, that the
field is an asset field, or that it applies to the asset’s type;
fields that mirror the asset’s title or description need
permission to edit the asset.
The field must exist (404) and not be archived (400). The server
then checks the write_capability (403), read_only (422), the
value’s member (400), the field’s pattern (422) and the guards (400
when if_absent: true is sent with if_unchanged_since), and, for
an ordinary field, required (422), the vocabulary (422) and, for a
reference, that the target asset exists and isn’t deleted (422). A
vocabulary value must name terms the field offers, though a term the
record already holds keeps saving after it is retired; an open
multi_select field adds new terms only if you hold
fields.vocabulary.extend.
Each successful write to an ordinary field gives the value a new
set_at and records an entry in the value’s history, in the same
transaction. Send if_unchanged_since or if_absent: true to make
the write conditional: if the stored value isn’t the one you guarded
against, nothing is stored and you get 409 with the value as it is
now. Without either, the last write wins.
Fields that mirror the asset’s title or description are written
to the asset itself: the usual asset edit permission applies (403),
a missing or deleted asset is 404, the guards are refused with 400,
a required mirrored field can’t be set blank (400), no field history
is recorded and set_at is the asset’s updated_at. For ordinary
fields, a write that has to insert a value for an asset id that
doesn’t exist (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; a deleted asset still accepts
values.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
The field definition’s id.
Request Body required
Section titled “Request Body required ”The value to store. Use the member that matches the field’s type:
value_text for text, longtext, rich_text, select and
tree (a tree value is the slug of one term); value_num for
number, and for boolean as 1 or 0; value_date for date and
datetime; value_options for multi_select, with at least one
term; value_ref for reference. Other members are ignored, and a
missing member is refused with 400.
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, and a term repeated in the list is stored once.
For a reference field, the id of an asset that exists and isn’t deleted.
A label for where the value came from; manual if you leave it out.
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, and so is sending it on a
field that mirrors an asset column.
With true, store the value only if the field has no value on this
asset 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, or on a field that mirrors an asset column, is
refused with 400.
Responses
Section titled “ Responses ”The value as stored.
One field value on an asset, with the field it belongs to and display data for vocabulary terms and references.
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.
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).