Skip to content

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.

id
required
string format: uuid

The collection’s id.

field_id
required
string format: uuid

The field definition’s id.

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
value_text

The value for a text, longtext, rich_text, select or tree field. Rich text is sanitized before it is stored.

string
nullable
value_num

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.

number
nullable
value_date

The value for a date or datetime field.

string format: date-time
nullable
value_options

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.

Array<string>
nullable
value_ref

For a reference field, the id of an asset that exists and isn’t deleted.

string format: uuid
nullable
set_by

A label for where the value came from: manual (the default), api, import or computed.

string
default: manual
Allowed values: manual api import computed
if_unchanged_since

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.

string format: date-time
if_absent

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.

boolean

The value as stored.

One field value on a collection. Same shape as an asset field value, with fewer set_by sources.

object
field_id
required

The field definition’s id.

string format: uuid
field_code
required

The field’s code.

string
field_label

The field’s label. Left out when it is empty.

string
type
required

The field’s type, which decides the member that holds the value.

string
Allowed values: text longtext rich_text number boolean date datetime select multi_select tree reference
value_text

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.

string
nullable
value_num

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.

number
nullable
value_date

The value of a date or datetime field.

string format: date-time
nullable
value_options

The terms of a multi_select value, as slugs. Left out when there are none.

Array<string>
nullable
value_ref

The id of the asset a reference value points to.

string format: uuid
nullable
set_by
required

Where the value came from: manual by default, or the api, import or computed label a writer sent.

string
Allowed values: manual api import computed
set_at
required

When the value was last written. Send it back as if_unchanged_since to guard a change.

string format: date-time
set_by_user_ref

The account that last wrote the value, when one is recorded.

integer format: int64
nullable
resolved_options

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
key
additional properties

How to display one vocabulary term. The term’s slug is the key it is listed under.

object
label
required

The term’s display text, or its slug when it has no label.

string
status
required

The term’s lifecycle state. Show anything other than active as retired or on its way out.

string
Allowed values: active deprecated archived
path

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.

Array<string>
nullable
resolved_reference

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
id
required

The referenced asset’s id, the same as value_ref.

string format: uuid
title
required

The referenced asset’s title, which can be empty; show the id when it is.

string

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The 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
error
required

A readable explanation of the refusal.

string
field_id
required

The field whose value wasn’t changed.

string format: uuid
present
required

Whether the field has a value on this collection now.

boolean
current
required

The value as stored now, or null when there is no value. It is returned without checking the field’s read_capability.

object
field_id
required

The field definition’s id.

string format: uuid
field_code
required

The field’s code.

string
field_label

The field’s label. Left out when it is empty.

string
type
required

The field’s type, which decides the member that holds the value.

string
Allowed values: text longtext rich_text number boolean date datetime select multi_select tree reference
value_text

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.

string
nullable
value_num

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.

number
nullable
value_date

The value of a date or datetime field.

string format: date-time
nullable
value_options

The terms of a multi_select value, as slugs. Left out when there are none.

Array<string>
nullable
value_ref

The id of the asset a reference value points to.

string format: uuid
nullable
set_by
required

Where the value came from: manual by default, or the api, import or computed label a writer sent.

string
Allowed values: manual api import computed
set_at
required

When the value was last written. Send it back as if_unchanged_since to guard a change.

string format: date-time
set_by_user_ref

The account that last wrote the value, when one is recorded.

integer format: int64
nullable
resolved_options

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
key
additional properties

How to display one vocabulary term. The term’s slug is the key it is listed under.

object
label
required

The term’s display text, or its slug when it has no label.

string
status
required

The term’s lifecycle state. Show anything other than active as retired or on its way out.

string
Allowed values: active deprecated archived
path

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.

Array<string>
nullable
resolved_reference

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
id
required

The referenced asset’s id, the same as value_ref.

string format: uuid
title
required

The referenced asset’s title, which can be empty; show the id when it is.

string

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
error
required

A readable explanation of the refusal.

string
reason
required

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 wrong value_* 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 when source or target isn’t a term.
  • option_not_offerable: the term is deprecated or archived and the record didn’t already hold it. A merge uses it when target is archived or source has already been merged.
  • dangling_reference: a reference value 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 hold fields.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’s regexp_filter.
  • field_required: the field is required, so its value can’t be set to empty or removed.
string
Allowed values: field_not_for_collection value_type_mismatch unknown_option option_not_offerable dangling_reference vocabulary_extension_forbidden field_read_only pattern_mismatch field_required
field

The code of the field that refused the value.

string
nullable
option

The term involved, for the vocabulary reasons (unknown_option, option_not_offerable and vocabulary_extension_forbidden).

string
nullable