Skip to content

List a collection's field values

GET
/collections/{id}/fields

Returns the field values stored on a collection, each with the field’s code, label and type, the value in the member its type uses, where it came from and when it was set. Any signed-in user can call this; values of a field with a read_capability are included only if you hold it globally (collections have no team).

Values you may not read are left out, so a missing entry can mean “no value” or “not for you”; GET /collections/{id}/field-composition tells the two apart. Values of archived fields are still returned, the collection isn’t checked for existence or deletion, and an unknown id returns an empty list. Entries are sorted by display group, display order and code, with resolved_options and resolved_reference for display, and numbers keep about seven significant digits.

Each server keeps the list per collection in a cache. Setting or clearing a value through these routes drops that entry and asks the other servers to drop theirs, but this is best effort, and a read that was already under way can put the old list back. Changes made any other way, such as a vocabulary merge, a relabelled term or a renamed referenced asset, aren’t announced at all, so an old list can stay until its entry is next dropped or replaced.

id
required
string format: uuid

The collection’s id.

The values you may read, possibly none.

Array<object>

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

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"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed