Skip to content

List an asset's field values

GET
/assets/{id}/fields

Returns the field values stored on an asset, together with its title and description where a field mirrors those columns. Any signed-in user can call this; values of a field with a read_capability are included only if you hold it globally or for the asset’s team.

Each entry carries the field’s code, label and type, the value in the member its type uses, where the value came from and when it was set. Values you may not read are left out, not blanked, so a missing entry can mean “no value” or “not for you”; GET /assets/{id}/field-composition tells the two apart.

Values of archived fields are still returned, and stored values are returned for a deleted asset too. Mirrored title and description entries appear only while the asset isn’t deleted, the field isn’t archived and the column isn’t empty. An id that matches no asset returns an empty list rather than 404.

Entries are sorted by display group, display order and code. Vocabulary values come with resolved_options and reference values with resolved_reference for display. Numbers come back as 32-bit floating-point values, so about seven significant digits survive. The readability check uses the server’s cached field definitions, so a change to a field’s read_capability can take a while to reach every server.

id
required
string format: uuid

The asset’s id.

The values you may read, possibly none.

Array<object>

One field value on an asset, with the field it belongs to and display data for vocabulary terms and references.

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.

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 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.

string
Allowed values: manual exif iptc xmp api import computed default mirror
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