Create a field definition
POST /fields
Creates a new custom metadata field for assets or collections.
Requires the fields.admin or system.admin capability, granted
globally; a team-scoped grant is not enough.
code, label and type are required. The code is trimmed and
must start with a lowercase letter, followed by lowercase letters,
digits or underscores. It must be unique among all field
definitions, archived ones included, so an archived field’s code
can’t be reused: restore that field instead. The label is trimmed
and can’t be blank.
The new field starts out active. Its code, type and subject kind
can’t be changed later. Settings this body doesn’t include, such as
the display flags, read_only, regexp_filter, display_condition
and the extraction source, start at their defaults and are set
afterwards with PATCH /fields/{id} or PUT /fields/{id}/extraction. Unknown properties in the body are
ignored.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The field’s stable identifier, such as color_space. Trimmed before it is checked. It must be unique among all field definitions, archived ones included, and can’t be changed later. The 64-character limit shown isn’t checked by the server.
The name shown to people. Trimmed; can’t be blank. The 200-character limit shown isn’t checked by the server.
A longer explanation of the field. Defaults to an empty string.
The kind of value the field holds. Can’t be changed later.
Whether the field describes assets or collections. Defaults to asset and can’t be changed later.
Type-specific settings, such as the vocabulary of a select, multi_select or tree field. See options in the response for the format and the checks.
object
Let values add new terms to this field’s vocabulary. Only
multi_select fields use it. Defaults to false.
Whether the field is required. See required in the response for what that enforces. Defaults to false.
Include the field’s values in full-text search.
Asset type refs the field applies to. Leave it out or send an empty list for every type. Collection fields don’t use it. The refs aren’t checked against existing asset types.
Capability someone needs to read the field’s current values. The code is stored as given and isn’t checked against known capabilities.
Capability someone needs to change the field’s values. The code is stored as given and isn’t checked against known capabilities.
Sort position within the display group. Lower numbers come first.
Name of the group the field is shown in.
Upload default for the new field. Asset fields only. It is checked against the field’s type and, for vocabulary fields, against the options in this same request.
object
literal for a fixed value, context for one the server fills in when the asset is created.
The literal value for text, longtext, rich_text, select and tree fields. For select and tree, an active slug.
The literal value for number and boolean fields. A boolean is 1 or 0.
The literal value for date and datetime fields.
The literal value for multi_select fields: active slugs.
The literal value for reference fields: an asset id.
Required when kind is context, and not allowed otherwise. The
server fills in the value when the asset is created:
uploading_user: the uploader’s full name from their account, or their username if no full name is set. Use it on text fields.uploading_team: the name of the uploader’s team. Use it on text fields. Skipped when the uploader belongs to no team or to more than one.current_date: the creation time, fordateanddatetimefields. Adatefield gets the day (UTC), adatetimefield the exact time.
These three are the only choices.
Responses
Section titled “ Responses ”The new field definition.
object
The field’s id, used in the /fields/{id} routes.
The field’s stable identifier, such as color_space. It is unique among all field definitions on this server, archived ones included, and can’t be changed after the field is created.
The name shown to people.
A longer explanation of the field. An empty string when none was given.
The kind of value the field holds. It can’t be changed after the field is created.
Whether the field describes individual assets or whole collections. A definition is one or the other; to have a field on both, create two definitions.
Type-specific settings. For select, multi_select and tree
fields this holds the vocabulary as {"values": [...]}, where each
entry is either a slug string or an object {value, label?, status?, replaced_by?, aliases?, children?}:
valueis the slug stored on records. Slugs are trimmed and must be unique across the whole document, including nested terms.statusisactive(the default),deprecatedorarchived. Don’t offer deprecated or archived terms for new values. Deprecated terms still display on records that have them.replaced_bynames another slug in the same field. An archived term withreplaced_byworks as a merge: a value that names it is stored as the replacement.aliasesare other spellings that lead to the term when a value is written. They are stored in lowercase and must not clash with any slug, label or alias in the field. Adding or removing an alias doesn’t change stored values.childrennests terms. It is what makes atreefield hierarchical; a stored value is still a single slug.
Documents without values, and other keys, are stored as sent. To
offer terms in a form, use GET /fields/{id}/values rather than
reading this document, which can be large.
object
When true, saving a value with a term the field doesn’t have yet
adds the term: the text becomes its label and a slug is made from
it. People need the fields.vocabulary.extend capability to add
terms this way, and metadata extraction can add them too. When
false, the default, an unknown term is refused with 422.
Terms are matched by slug or label, ignoring case and any spaces at
either end, so Character and character name the same term. Only
multi_select fields use this setting.
When true, people can’t save an empty value or remove the value once one is set. Uploading an asset doesn’t require it, but creating a collection does require a value for each required collection field. Upload defaults and metadata extraction aren’t affected.
Include this field’s values in full-text search. True by default. Only values of active asset fields are indexed.
Turning it off takes the field out of the search index only. A
field: filter on the field still works, and whether the advanced
search page offers the field as a filter is a separate setting,
show_in_advanced_search.
Asset type refs this field applies to. An empty list means every asset type. Collection fields don’t use it.
Capability someone needs to read this field’s current values. null or an empty string means no capability is needed. It doesn’t hide the definition itself, and the value-history routes, GET /assets/{id}/fields/{field_id}/history and GET /collections/{id}/fields/{field_id}/history, don’t check it, so earlier values stay readable there.
Capability someone needs to change this field’s values. null or an empty string means no extra capability is needed.
Sort position within the display group. Lower numbers come first.
Name of the group the field is shown in, such as general.
Name of the extracted value that fills this field, such as
capture_datetime. An empty string means the field isn’t filled by
extraction. Set it with PUT /fields/{id}/extraction.
How extracted values are applied. skip_if_set fills the field only
when it is empty or still holds its upload default; a value set any
other way, by a person, an import or an earlier extraction, is left
alone. replace overwrites the current value whenever the file has
one. append and prepend are accepted but currently work the same
as replace.
Show this field’s value on asset cards in browse views. It is a display hint only and controls no access, filtering or search.
A field with a read_capability can’t be shown on cards, because
cards are drawn without checking per-field capabilities. A request
that would leave a field with both is refused with 400.
Offer this field as a filter on the advanced search page. True by
default. It only decides whether the page shows a control: it
doesn’t change search results, and a field: filter on the field
works either way. People who can’t read the field’s values can’t
filter on it whatever this says.
Offer this field on upload and create forms. True by default. It is
a hint for forms, not an access rule: hiding a field from a form
doesn’t stop its values being set through PUT /assets/{id}/fields/{field_id}.
The edit-form tab this field belongs to, or null for none. Tabs
group fields more coarsely than display_group. A blank tab name is
refused; to remove the tab, use clear_edit_tab on PATCH /fields/{id}.
When true, people can’t set or clear this field’s values through the API, whatever capabilities they hold. Values already stored are kept.
The server’s own writers still fill the field: upload defaults and
metadata extraction. For a collection field, a value given when the
collection is created is also accepted. A field with
mirrors_column can’t be made read-only.
A pattern that values people enter must match, or null for none.
It uses Go RE2 syntax and always matches the whole value, so don’t
add ^ or $: a|b means the whole value is a or b. The
pattern is stored exactly as sent, spaces included.
Only text and longtext fields can have one, and not fields with
mirrors_column. It checks new input only: stored values aren’t
rechecked when the pattern changes, and upload defaults and metadata
extraction aren’t held to it.
When set, this field has no storage of its own: it reads and writes
that column of the asset, title or description. null means an
ordinary field.
Writing a mirrored field changes the asset, so it needs the same permission as editing the asset. Forms that already show the title or description should skip the mirrored field. This setting can’t be changed through the API.
When to offer this field in forms: a list of terms that must all be
true, or null to always offer it. Each term is
<code><operator><value> and names another field of the same
subject kind, such as work_type=commission.
=compares the stored value exactly, including case. On amulti_selectfield it checks whether the term is one of the selected values.~checks whether the stored value contains the text, ignoring case.textandlongtextfields take=and~;select,treeandmulti_selectfields take=. Other types can’t be used in a condition.
Spaces around the code and value in a term are ignored; the stored value is compared as it is.
This is a form hint, not access control. A hidden field keeps its
values and can still be written through PUT /assets/{id}/fields/{field_id}, and hiding a field never clears it.
If any term can’t be evaluated, for example because the other field
is missing, archived or not readable by the person using the form,
the whole condition is ignored and the field is shown. A readable
field with no value counts as false.
Set it with display_condition on PATCH /fields/{id} and remove
it with clear_display_condition. It can’t be set when a field is
created.
active fields are offered for new values. deprecated fields still show and keep their values but shouldn’t be offered for new ones. archived fields are retired: left out of field lists and forms by default, but kept with their values. Only active fields count in full-text search and field: filters.
The field that replaces this one, if any. For information only.
Upload default: the value a new asset gets for this field when
nothing else sets it, or null for none. Only active asset fields
use it, and only on asset types the field applies to. A team can
override it for its own uploads through
/fields/{id}/default-overrides. Metadata extraction can replace a
default value later.
object
literal for a fixed value, context for one the server fills in when the asset is created.
The literal value for text, longtext, rich_text, select and tree fields. For select and tree, an active slug.
The literal value for number and boolean fields. A boolean is 1 or 0.
The literal value for date and datetime fields.
The literal value for multi_select fields: active slugs.
The literal value for reference fields: an asset id.
Required when kind is context, and not allowed otherwise. The
server fills in the value when the asset is created:
uploading_user: the uploader’s full name from their account, or their username if no full name is set. Use it on text fields.uploading_team: the name of the uploader’s team. Use it on text fields. Skipped when the uploader belongs to no team or to more than one.current_date: the creation time, fordateanddatetimefields. Adatefield gets the day (UTC), adatetimefield the exact time.
These three are the only choices.
When the definition was created.
When the definition last changed. Send it as if_unchanged_since on PATCH /fields/{id} to have the update refused if the field has changed since; that check has limits, described there.
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 completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed