# Fields and tags: questions and answers

Short answers about describing files: custom fields and their kinds and
options, setting values on one file or many, filtering by field, tags and
their rules, and the built-in description, caption and alt text. Each answer
links to the section of [Fields and tags](../files/fields-and-tags.md) that
owns the rule.

## The basics

### What are fields and tags for?

They are how a team describes its files, so that people and agents can find
them, filter them and understand them without opening each one.

More: [Fields and tags, Summary](../files/fields-and-tags.md#summary)

### Which kinds of description can a file carry?

Four: the built-in details (description, caption and alt text), tags, custom
fields, and the status.

More: [Fields and tags, Summary](../files/fields-and-tags.md#summary)

### What is the difference between a tag and a custom field?

A tag is a free label anyone working with a file can make up on the spot. A
custom field is defined by an owner or admin, has a kind and, for select
kinds, a fixed list of options. Both live in one workspace or the
organization folder. Use tags for loose grouping and
fields for facts every file should answer the same way, such as usage
rights.

More: [Fields and tags, Summary](../files/fields-and-tags.md#summary)

### Do field values or tags decide who can open a file?

No. Only the status and the sharing settings do.

More: [Sharing and public links, The strict rule](../files/sharing.md#the-strict-rule)

### Who can read a file's field values, details and tags?

Everyone who can open the file's workspace, or the organization folder. A
credential needs `files:read`.

More: [Fields and tags, Who can do what](../files/fields-and-tags.md#who-can-do-what)

### Do I need a verified email to work with fields and tags?

No. No verified email is needed for defining fields, setting values or
tagging.

More: [Fields and tags, Who can do what](../files/fields-and-tags.md#who-can-do-what)

### Is anyone notified when a field is added or deleted?

No. The change is recorded in the audit trail.

More: [Fields and tags, In the audit trail](../files/fields-and-tags.md#in-the-audit-trail)

### Does Talewright tag or describe files automatically?

No. Tags, field values, descriptions, captions and alt text are set by a
person, or by an agent that acts for one through the API or MCP.

More: [Fields and tags, Who can do what](../files/fields-and-tags.md#who-can-do-what)

### Does Talewright recognize faces or objects in images?

No. A file is described by the tags, field values and texts that people and
agents enter.

More: [Fields and tags, Summary](../files/fields-and-tags.md#summary)

## Custom fields and their kinds

### What is a custom field?

A typed value that a workspace, or the organization folder, defines for its
own files: a text, a number, a date, one choice from a list, or several
choices from a list.

More: [Fields and tags, Custom fields](../files/fields-and-tags.md#custom-fields)

### Which kinds of custom field are there?

Five: "Text", "Number", "Date", "Single select" and "Multi-select". In the
API they are `text`, `number`, `date`, `select` and `multiSelect`.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### What does a "Text" field hold?

Free text, up to 2,000 characters. Line breaks are allowed.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### What does a "Number" field hold?

One number, whole or with decimals. In the API it is a JSON number.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### What does a "Date" field hold?

One calendar date, without a time. In the API it is a string `YYYY-MM-DD`.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### What does a "Single select" field hold?

One choice from the field's list of options. In the API the value is the
choice's ID.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### What does a "Multi-select" field hold?

Any number of choices from the field's list of options. In the API the value
is a list of choice IDs.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### Can a date field hold a time of day?

No. A date field holds one calendar date, without a time.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### Can I change a field from "Text" to "Single select"?

No. The kind is chosen when the field is created and never changes. Create a
new field of the other kind and delete the old one. The old values are
deleted with it.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### Is there a checkbox or yes/no field?

No. The five kinds are text, number, date, single select and multi-select.
A single select with the options "Yes" and "No" does the same job.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### Is there a field kind for links, people or currency?

No. There are five kinds: text, number, date, single select and
multi-select. A link or a name goes into a text field, an amount into a
number field.

More: [Fields and tags, Kinds](../files/fields-and-tags.md#kinds)

### Does a new organization have any custom fields?

No. A new workspace has no custom fields, and neither does the organization
folder of a new organization. They have only the built-in status.

More: [Fields and tags, Custom fields](../files/fields-and-tags.md#custom-fields)

### Does every workspace have its own custom fields?

Yes. Every workspace has its own ordered list of custom fields, and so does
the organization folder. A file carries values only of its own workspace's
fields, or the organization folder's for an organization folder file. Two
workspaces can each have a field "Rights"; they are different fields with
different IDs.

More: [Fields and tags, Custom fields](../files/fields-and-tags.md#custom-fields)

### Can another organization read or use our custom fields?

No. Fields belong to their workspace or organization folder. A field of
another organization, like one of another workspace or the organization
folder, cannot be set on a file or filtered by: that answers `422
VALIDATION_FAILED`.

More: [Fields and tags, Custom fields](../files/fields-and-tags.md#custom-fields)

## Creating a field

### How do I add a custom field?

1. Open the settings page "Custom fields" of the workspace or the
   organization folder. For a workspace it is **Settings > Organization
   folder and workspaces > {workspace} > Custom fields**. For the
   organization folder it is **Settings > File spaces > Organization folder > Custom fields**.
2. Choose "Add field".
3. Fill in "Name" and choose a "Kind".
4. For "Single select" and "Multi-select", type the "Options", one per
   line.
5. Choose "Add field".

The field appears at the end of the list.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### Who can add, rename or delete a custom field?

For a workspace, its owners and admins and the organization's owners and
admins. For the organization folder, the organization's owners and admins.
Always in a browser. A workspace admin who is a plain member of the
organization manages the workspace's fields, not the organization folder's.

More: [Fields and tags, Who can do what](../files/fields-and-tags.md#who-can-do-what)

### Can a member define a custom field?

No. A member who is not an owner or admin of the workspace or the
organization folder and tries to add, rename, reorder or delete a field or
an option gets `403 FORBIDDEN`, and nothing changes. Members see the list
and fill fields in on files they may change.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### Why does defining a field with an API key answer `SESSION_REQUIRED`?

Fields and options are defined by a person in a browser. A credential that
tries gets `403 FORBIDDEN` with `details.reason` `SESSION_REQUIRED`, also
when it belongs to an owner.

More: [Fields and tags, Who can do what](../files/fields-and-tags.md#who-can-do-what)

### Can I give a new field a default value?

No. A new field is empty on every file. To fill many files at once, select
them and choose "Set field".

More: [Fields and tags, Creating a field](../files/fields-and-tags.md#creating-a-field)

### Can I make a field required?

No. Every field can be left empty. To find the files that still miss a
value, filter by "Not set" in the app or `{fieldID}:none` in the API.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### Can I create a select field first and add its options later?

Yes. A `select` or `multiSelect` field can be created with its options, in
the order given, or with none and get them later.

More: [Fields and tags, Creating a field](../files/fields-and-tags.md#creating-a-field)

### How do I enter the options when I add a select field in the app?

Type them into "Options", one per line. Empty lines are ignored.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### What happens when two options in the "Add field" request have the same name?

The request is refused with `409 CONFLICT`, reason `NAME_TAKEN`, and no
field is created. "A" and "a" count as the same name.

More: [Fields and tags, Creating a field](../files/fields-and-tags.md#creating-a-field)

### Why does "Add field" say "Enter a name of 1 to 60 characters."?

The name is blank or longer than 60 characters. Spaces at the start and end
do not count.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### Why does "Add field" say "That name is taken."?

Another field of the same workspace or organization folder has that name,
ignoring case. "Rights" and "rights" cannot both exist there.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### Why does "Add field" say "Use at most 100 options of 1 to 60 characters each."?

You typed more than 100 options, or one of them is longer than 60
characters.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### How do I make room for a new field when a workspace or the organization folder has 50?

Delete a field first. A workspace, or the organization folder, has at most
50 custom fields. The app says "A workspace or the organization folder can
have up to 50 custom fields. Delete one to add another." Each workspace
counts its own 50.

More: [Fields and tags, Creating a field](../files/fields-and-tags.md#creating-a-field)

### Can a custom field be named "Status"?

Yes. The built-in status is not part of the name check.

More: [Fields and tags, Naming rules](../files/fields-and-tags.md#naming-rules)

### Can a field name contain a tab or a line break?

No. A name with a control character is refused. Spaces at the start and end
are removed before the name is measured and stored.

More: [Fields and tags, Naming rules](../files/fields-and-tags.md#naming-rules)

### Which kind does the "Add field" dialog start on?

"Text".

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### What happens when two admins add the 50th field at the same moment?

They cannot end up with 51. Changes to a workspace's or the organization
folder's field list are handled one after the other, so one is added and the
other is refused.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

## Options of a select field

### What is the difference between an "option" and a "choice"?

None. The app calls the choices of a select field "options". The API calls
them `choices`.

More: [Fields and tags, Choices](../files/fields-and-tags.md#choices)

### How do I add an option to an existing field?

Open "Manage {name}" on the field and choose "Add option". The dialog "Add
option to {field}" has "Name" and the button "Add option". The new option
goes to the end.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### Which fields can have options?

Only "Single select" and "Multi-select" fields. Adding a choice to a text,
number or date field is refused.

More: [Fields and tags, Choices](../files/fields-and-tags.md#choices)

### Can two different fields have an option with the same name?

Yes. Option names only have to be unique within their own field, ignoring
case. Two fields can each have an option "Other".

More: [Fields and tags, Naming rules](../files/fields-and-tags.md#naming-rules)

### Does a file store the name of a chosen option or its ID?

The ID. A choice has an ID that never changes. That is why renaming an
option changes no file.

More: [Fields and tags, Choices](../files/fields-and-tags.md#choices)

### How do I change the order of a field's options?

Open "Manage {name}" on an option and choose "Move up" or "Move down". The
order is the order in which options show in pickers and filters.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### How does the settings page show a field's options?

Each option has an indented row of its own under its field in the table
"Custom fields", with the type "Option" and its own file count.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

## Renaming and ordering fields

### How do I rename a field or an option?

Open its menu "Manage {name}" and choose "Rename". The dialog "Rename
{name}" has the field "Name" and the button "Rename".

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### Does renaming a field or an option change my files?

No. Files keep their values and show the new name. No file's `lockVersion`
moves.

More: [Fields and tags, Renaming](../files/fields-and-tags.md#renaming)

### Where does a renamed field show its new name?

Everywhere at once: on every file of the workspace or the organization
folder, in filters and in the settings.

More: [Fields and tags, Renaming](../files/fields-and-tags.md#renaming)

### What happens when I rename a field to a name another field has?

It is refused with `409 CONFLICT`, reason `NAME_TAKEN`. The same holds for
an option renamed to the name of another option of the same field.

More: [Fields and tags, Renaming](../files/fields-and-tags.md#renaming)

### Can I change only the capital letters in a field's name?

Yes. Renaming a field or an option to its own name in a different case
works.

More: [Fields and tags, Renaming](../files/fields-and-tags.md#renaming)

### How do I change the order of the custom fields?

Open "Manage {name}" on a field and choose "Move up" or "Move down". Each
moves it one place. The first has no "Move up", the last no "Move down".

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### Where does the order of the fields show?

On a file's page and in the settings. Options show in their own order in
pickers and filters.

More: [Fields and tags, Reordering](../files/fields-and-tags.md#reordering)

### Can I move a custom field above the status?

No. The built-in status is always first. It is not part of the order and is
not named in a reorder.

More: [Fields and tags, Reordering](../files/fields-and-tags.md#reordering)

### Why did reordering the fields fail after another admin added one?

Your request was made before the new field existed, so it no longer names
every field. A reorder must name every field exactly once. Load the list
again and reorder.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

## Deleting fields and options

### How do I delete a custom field?

Open "Manage {name}" on the field and choose "Delete". The app asks "Delete
{name}?" and says how many files will lose a value. Confirm with "Delete
field".

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### What happens to the values when I delete a field?

They are deleted from every file of the workspace or the organization
folder, live or in the trash. This cannot be undone.

More: [Fields and tags, Deleting a field](../files/fields-and-tags.md#deleting-a-field)

### What does "{n} files will lose this value." mean?

That many live files have a value for the field, or have the option, you are
about to delete. They lose it with the deletion.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### What does "7 files will lose this value, and so will 2 files in the trash." mean?

Seven live files have the value, and two more files in the trash of the
workspace or the organization folder have it too. All nine lose it.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### What does "No file has this value." mean?

Deleting the field or option changes no file, because no file has a value
for it.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### Does the API ask before it deletes a field?

No. The app asks first and says how many files lose a value. The API asks no
confirmation.

More: [Fields and tags, Deleting a field](../files/fields-and-tags.md#deleting-a-field)

### What changes on a file when a field it had a value for is deleted?

The value is gone, the file's `lockVersion` moves, and the file shows the
person who deleted the field as the one who last changed it. Files that had
no value are not touched.

More: [Fields and tags, Deleting a field](../files/fields-and-tags.md#deleting-a-field)

### How do I delete an option of a select field?

Open "Manage {name}" on the option and choose "Delete". Confirm with "Delete
option".

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### What happens when I delete an option that files use?

On a single select those files have no value afterwards. On a multi-select
they lose only that option and keep their other options.

More: [Fields and tags, Deleting a choice](../files/fields-and-tags.md#deleting-a-choice)

### Does search still find the text of a deleted field?

No. Text values of the deleted field stop matching in search at once.

More: [Fields and tags, Deleting a field](../files/fields-and-tags.md#deleting-a-field)

### What happens when a field is deleted from two browsers at once?

The second attempt gets `404 NOT_FOUND`. The field is already gone.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

## Counts

### What does the number of files beside a field in settings mean?

The number of files with a value for that field, such as "7 files". Under a
field with options, each option shows its own count.

More: [Fields and tags, Defining fields](../files/fields-and-tags.md#defining-fields)

### What does `fileCount` on a field or a choice count?

For a field, the live files of its workspace or the organization folder that
have a value for it. For a choice, those of them that have that choice.

More: [Fields and tags, Counts](../files/fields-and-tags.md#counts)

### Do a member and an owner see the same field counts?

Yes. `fileCount` covers only the files of the field's own workspace or the
organization folder, so it is the same for everyone who can open it. Only
`trashedFileCount` differs: it is a number for an owner or admin in the app
and `null` for everyone else.

More: [Fields and tags, Counts](../files/fields-and-tags.md#counts)

### Why is `trashedFileCount` on a field `null`?

It is a number only for an owner or admin of the workspace or the
organization folder signed in to the app, who may delete the field. For
everyone else, and for every credential, it is `null`. For the built-in
"Status" field it is always `null`.

More: [Fields and tags, Counts](../files/fields-and-tags.md#counts)

### Are files in the trash counted in a field's `fileCount`?

No. Files in the trash are not counted there. They count in
`trashedFileCount`.

More: [Fields and tags, Counts](../files/fields-and-tags.md#counts)

## Setting field values on a file

### How do I fill in a custom field on a file?

Open the file's page. In "Details", the section "Fields" has one input per
custom field of the file's workspace or organization folder. Enter the
values and choose "Save fields".

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### Who can fill in the fields of a file?

Everyone who may change the file: every member of the workspace for a
workspace file, and organization owners and admins for an organization
folder file.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

### Can a member set field values on an organization folder file?

No. Only owners and admins of the organization change organization folder
files. A member's attempt answers `403 FORBIDDEN`, and the app says "Only
organization owners and admins can change the organization folder."

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### Which input does each kind of field get on a file's page?

A text box for "Text", a number input for "Number", a date picker for
"Date", a picker with "None" and the options for "Single select", and a
checkbox per option for "Multi-select".

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### How do I clear a field value on a file?

Empty the input, choose "None" for a single select or untick every option of
a multi-select, then choose "Save fields". Through the API, send `null` for
the field.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Why is "Save fields" disabled?

No value has changed yet. "Save fields" is disabled until a value changed.

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### Does "Save fields" also save what I typed in "Details"?

No. Each section saves only its own part. Unsaved edits in the other
section stay where they are.

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### Does a newly uploaded file have field values?

No. A new upload has no values, no tags, no description, no caption and no
alt text.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

### Do field values survive when I replace a file with a new version?

Yes. A value belongs to the file, not to one version of it. Tags,
description, caption and alt text stay too.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

### Does a file keep its field values while it is in the trash?

Yes, and they are back with a restore, unless the field was deleted in the
meantime. A file in the trash cannot be edited.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### Can a file have two values for the same field?

No. A file has, for each field, one value or no value. A multi-select value
is one value that holds several choices.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

### What do I see in "Fields" when I cannot change the file?

Each field's name with its value: the text, the number, the date, or the
names of the chosen options. A field without a value reads "None". There is
no "Save fields".

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### What does the section "Fields" show when the workspace or organization folder has no custom fields?

Nothing: the section is not shown. The status has its own section, "Status".

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### What does setting a value do to the value the file had?

It replaces it. Setting a value replaces the value the file had for that
field.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

## Field values in the API

### How are field values sent in a request?

As `fields`, a map from field ID to value, in the same change as the file's
other details. Fields that are left out keep their values.

More: [Fields and tags, Setting values on one file](../files/fields-and-tags.md#setting-values-on-one-file)

### What value does each kind of field take in the API?

`text` takes a string of 1 to 2,000 characters. `number` takes a JSON
number. `date` takes a string `YYYY-MM-DD` that is a real date. `select`
takes the ID of one choice. `multiSelect` takes a list of choice IDs.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Why is `"12"` refused for a number field?

A number field takes a JSON number, not a string, also not one that holds
digits. Send `12`.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Which values clear a text field?

`null`, an empty string or a string of only spaces.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Which values clear a multi-select field?

`null` or an empty list.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Why is a list refused for a single select field?

A select takes one choice ID as a string, not a list, also not a list with
one entry.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Why is a single choice ID refused for a multi-select field?

A multi-select takes a list. Send the ID inside a list.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Which date values does a date field refuse?

A date that does not exist, such as `2026-13-01`, and a number. It takes a
real date as `YYYY-MM-DD`.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### Can a text field value contain tabs and line breaks?

Yes. Line breaks and tabs are allowed. Other control characters are refused.
Text is trimmed before it is stored.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### In what order does the API return the choices of a multi-select value?

In the order of the field's choices, whatever order they were sent in.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

### What happens when a multi-select value names the same choice twice?

It is stored once. Repeated IDs count once.

More: [Fields and tags, What each kind accepts](../files/fields-and-tags.md#what-each-kind-accepts)

### What happens when one of several field values in a request is invalid?

Nothing in the request is applied: not the other values, not a new
description. A change to a file is all or nothing.

More: [Fields and tags, Setting values on one file](../files/fields-and-tags.md#setting-values-on-one-file)

### Do file lists and search results carry field values?

No. They do not carry `fields`. Read the file to see its values. They do
carry each file's tags.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

### How does the API show a field that has no value on a file?

It is left out. A file's `fields` holds only the fields that have a value,
keyed by field ID.

More: [Fields and tags, Field values](../files/fields-and-tags.md#field-values)

### Does setting a field to the value it already has count as a change?

Yes. The request succeeds and the file's `lockVersion` moves.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

### In what order is a change to a file's values checked?

1. Not signed in or no valid credential: `401 UNAUTHENTICATED`.
2. Workspace or organization unknown or out of reach: `404 NOT_FOUND`.
3. A key of `fields` that is not a field ID: `422` on `fields`.
4. An organization folder file and not an owner or admin: `403 FORBIDDEN`.
5. Name, alt text, description, caption or tags break their rules: `422`.
6. Unknown file: `404 NOT_FOUND`.
7. File in the trash: `409 CONFLICT`, reason `IN_TRASH`.
8. `expectedLockVersion` not current: `409 STALE_LOCK_VERSION`.
9. Unknown field or choice, one of another workspace or the organization
   folder, or a value of the wrong kind: `422` on `fields`.

More: [Fields and tags, Setting values on one file](../files/fields-and-tags.md#setting-values-on-one-file)

### What happens when a value is sent for a field of another workspace or organization?

`422 VALIDATION_FAILED` on `fields`. A file carries only the fields of its
own workspace or organization folder, so a field of another workspace, of
the organization folder or of another organization is refused like an
unknown one. The same holds for "Set field" on many files and for the
`field` filter.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### Can a key with only `files:read` set a field value?

No. Setting values needs `files:write`. The call answers `403 FORBIDDEN`
with reason `INSUFFICIENT_SCOPE`.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### How much does the `lockVersion` move when one request changes several details?

By one, however many details the request changed.

More: [Fields and tags, Setting values on one file](../files/fields-and-tags.md#setting-values-on-one-file)

## Setting a field on many files

### How do I set a field on many files at once?

1. Select the files in the browser.
2. In the toolbar "Selected files", choose "Set field".
3. Pick the "Field" and enter the value.
4. Choose "Set field".

The app shows "Set {field} on {n} files".

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### How do I set a field on a whole folder?

Open the folder, select its files and choose "Set field". The value is set
on the selected files. Files added later do not get it.

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### Why is "Set field" missing from the toolbar "Selected files"?

It is offered while the open workspace or organization folder has at least
one custom field and you may change the files. In the organization folder
that means owners and admins.

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### How do I clear a field on many files at once?

Choose "Set field", pick the field, and leave the input empty or choose
"None". "Set field" then clears the field on the selected files.

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### What happens to folders in my selection when I choose "Set field"?

They are ignored. Only the selected files change.

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### What happens when I set a field on more than 100 selected files?

The app sends them in batches of 100. If a later batch fails, the earlier
ones stay applied and the list is refreshed.

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### Can I set a field from the command palette?

Yes. The command palette offers the same as "Set field".

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### Is setting one field on many files all or nothing?

Per request, yes. One unknown file refuses the whole request with `404
NOT_FOUND`, and one file in the trash refuses it with `409 CONFLICT`, reason
`IN_TRASH`. No file changes.

More: [Fields and tags, Setting one field on many files](../files/fields-and-tags.md#setting-one-field-on-many-files)

### Does setting a field on many files need each file's `lockVersion`?

No. It needs no `expectedLockVersion`. It overwrites whatever value each
file had.

More: [Fields and tags, Setting one field on many files](../files/fields-and-tags.md#setting-one-field-on-many-files)

### Can one batch request set two different fields?

No. One request sets one field to one value on 1 to 100 files of the same
workspace, or of the organization folder.

More: [Fields and tags, Setting one field on many files](../files/fields-and-tags.md#setting-one-field-on-many-files)

### Can the batch field operation set the status?

No. The field must be a custom field. The built-in status cannot be named
there. It has its own operation.

More: [Fields and tags, Setting one field on many files](../files/fields-and-tags.md#setting-one-field-on-many-files)

### What happens when a batch field request leaves out `value`?

It is refused with `422 VALIDATION_FAILED` and changes nothing. Only an
explicit `null` clears the field.

More: [Fields and tags, Setting one field on many files](../files/fields-and-tags.md#setting-one-field-on-many-files)

### Does a batch field change touch files that already had the value?

Yes. Every named file's `lockVersion` moves, also files that already had
that value.

More: [Fields and tags, Setting one field on many files](../files/fields-and-tags.md#setting-one-field-on-many-files)

### What happens to a file page I had open when someone sets a field in a batch?

The page is stale. The batch moved the file's `lockVersion`, so your next
save is refused until you reload the latest.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

### Why does setting a field say "A selected file is in the trash. Clear the selection and try again."?

One of the selected files went to the trash after you selected it. A field
can be set only on live files.

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

### Why does setting a field say "A selected file no longer exists. The list is up to date now."?

One of the files was deleted for good, or is no longer in this workspace or
organization folder. The list was refreshed. Select again and repeat.

More: [Fields and tags, Setting a field on a selection](../files/fields-and-tags.md#setting-a-field-on-a-selection)

## Filtering by field

### How do I filter files by a custom field in the app?

Open "Filter". It has one group per "Single select" and "Multi-select" field
of the open workspace or organization folder, named after the field. Choose
an option, or "Not set".

More: [Fields and tags, Filtering by field in the browser](../files/fields-and-tags.md#filtering-by-field-in-the-browser)

### Which fields appear in the Filter menu?

"Single select" and "Multi-select" fields. "Text", "Number" and "Date"
fields are not in the Filter menu.

More: [Fields and tags, Filtering by field in the browser](../files/fields-and-tags.md#filtering-by-field-in-the-browser)

### What do "Any" and "Not set" mean in a field's filter group?

"Any" is no filter. "Not set" shows the files without a value for that
field.

More: [Fields and tags, Filtering by field in the browser](../files/fields-and-tags.md#filtering-by-field-in-the-browser)

### Can I filter by a text, number or date field?

Not by its content. You can filter for files where it is not set, with
`{fieldID}:none` in the API. Text values are found by search.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### Can I filter by a date range or a number range?

No. There is no filter for the content of a `text`, `number` or `date`
field.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### Can I filter by two options of the same field?

In the API, yes: `field={fieldID}:{a},{fieldID}:{b}` matches files with
either. The app's Filter menu takes one option per field.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### How do filters on several fields combine?

A file must match all of them. Entries for the same field match files that
fit any of them.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### Does a field filter look only in the open folder?

No. A field or tag filter looks through every folder of the workspace or
organization folder. Each result says which folder it is in.

More: [Fields and tags, Filtering by field in the browser](../files/fields-and-tags.md#filtering-by-field-in-the-browser)

### How do I find the files that still have no value for a field?

In the app, choose "Not set" in the field's filter group. In the API, use
`field={fieldID}:none`. It works for fields of every kind.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### Does a file with several options match a filter on one of them?

Yes. A multi-select file matches a choice when that choice is among its
choices.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### Can a field filter be combined with search, tags and status?

Yes. The filter combines with every other filter of the list: folder, search
words, tag, type and status.

More: [Fields and tags, Filtering by field](../files/fields-and-tags.md#filtering-by-field)

### How do I see how many filters are on, and turn them off?

The "Filter" button shows how many filters are on. "Clear filters" turns
them all off.

More: [Fields and tags, Filtering by field in the browser](../files/fields-and-tags.md#filtering-by-field-in-the-browser)

### What does a filter on a text field with a choice ID answer?

`422 VALIDATION_FAILED` on `field`. A text field has no choices to match.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### Which files match a filter on a select option that was deleted?

Files that had the option have no value for the field afterwards, so they
match `{fieldID}:none`. A filter that still names the deleted option is
refused.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### Does search find the values of custom fields?

Only of `text` fields. Values of `number`, `date`, `select` and
`multiSelect` fields are not searched, and option names are not searched.
Use the field filter for options.

More: [Fields and tags, Search](../files/fields-and-tags.md#search)

## Tags

### What is a tag?

A short lower-case label on files. Anyone who may change a file adds tags
freely, up to 50 per file. Tags belong to one workspace, or to the
organization folder.

More: [Fields and tags, Tags](../files/fields-and-tags.md#tags)

### How do I add a tag to a file?

On the file's page, type it into "Tags" in the section "Details", separated from
the other tags by a comma, and choose "Save details".

More: [Fields and tags, The comma rule](../files/fields-and-tags.md#the-comma-rule)

### How do I remove a tag from a file?

Delete it from the text in "Tags" and choose "Save details". To remove all
tags, empty the box and save.

More: [Fields and tags, The comma rule](../files/fields-and-tags.md#the-comma-rule)

### Do I have to create a tag before I can use it?

No. A tag is created by naming it on a file. There is no separate step to
create one.

More: [Fields and tags, Tags](../files/fields-and-tags.md#tags)

### Who can tag files?

Whoever may change the file: every member of the workspace for a workspace
file, and organization owners and admins for an organization folder file. A
credential needs `files:write`.

More: [Fields and tags, Who can do what](../files/fields-and-tags.md#who-can-do-what)

### Why do my tags turn lower case?

Tags are normalized so that "Brand" and "brand" are one tag: spaces at the
start and end are removed, several spaces in a row become one, and letters
become lower case.

More: [Fields and tags, Tag names](../files/fields-and-tags.md#tag-names)

### Can a tag contain spaces?

Yes. "spring launch" is one tag. Several spaces in a row become one, so
"Campaign   2026" becomes "campaign 2026".

More: [Fields and tags, Tag names](../files/fields-and-tags.md#tag-names)

### Which characters can a tag contain?

Any character except a comma and control characters such as a tab or a line
break.

More: [Fields and tags, Tag names](../files/fields-and-tags.md#tag-names)

### Are tags shared between workspaces?

No. Every workspace has its own tags, and the organization folder has its own.

More: [Fields and tags, Tags](../files/fields-and-tags.md#tags)

### What happens when I type the same tag twice on a file?

It is stored once. Names that normalize to the same tag count once.

More: [Fields and tags, The comma rule](../files/fields-and-tags.md#the-comma-rule)

### What happens to empty entries such as "a, , b" in the "Tags" box?

They are ignored. Spaces around a comma do not matter either.

More: [Fields and tags, The comma rule](../files/fields-and-tags.md#the-comma-rule)

### In what order are a file's tags shown?

Sorted by name. After a save, "Tags" shows the tags as they are stored:
normalized and sorted. " Spring Launch , q3" becomes "q3, spring launch".

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### Where do I see a file's tags in the file list?

In the list view, under the file's name on its row. The grid view does not
show tags.

More: [Fields and tags, Tags in the browser](../files/fields-and-tags.md#tags-in-the-browser)

### Does a file keep its tags when it gets a new version?

Yes. Tags belong to the file, not to one version. Replacing the file keeps
them.

More: [Fields and tags, Tags](../files/fields-and-tags.md#tags)

### How does the API set a file's tags?

As one complete list that replaces the tags the file had. To add a tag, send
the current tags plus the new one. To remove one, send the list without it.
To remove all, send an empty list.

More: [Fields and tags, Setting a file's tags](../files/fields-and-tags.md#setting-a-files-tags)

### Do 60 tag names that normalize to 40 tags fit on one file?

Yes. The limit of 50 counts tags after duplicates are removed.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### What happens to a file's tags when I send 51 different ones?

The request is refused with `422 VALIDATION_FAILED` on `tags`, and the
file's tags stay as they were.

More: [Fields and tags, Setting a file's tags](../files/fields-and-tags.md#setting-a-files-tags)

### Can I tag many files at once in the app?

Tags are set file by file in the section "Details" on the file's page. The toolbar "Selected files"
offers "Set field" for custom fields. An agent can change the tags of many
files through the API, or propose them in a suggestion.

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### Can I tag a folder?

No. A tag is a label on files. Folders carry no tags.

More: [Fields and tags, Tags](../files/fields-and-tags.md#tags)

## Managing tags

### Where is the list of all tags of a workspace?

In the app, the workspace's settings page "Tags" lists them with their file
counts; for the organization folder it is **Settings > Organization folder
and workspaces > Organization folder > Tags**. The Filter menu's group "Tag"
also lists every tag of the open workspace or organization folder. Through
the API, each workspace and the organization folder has a tag list, sorted
by name, with a `fileCount` per tag.

More: [Fields and tags, The tag list](../files/fields-and-tags.md#the-tag-list)

### Why is a tag still offered in the filter when no file has it?

A tag that no file carries any more stays in the list with a count of 0,
until someone deletes it.

More: [Fields and tags, The tag list](../files/fields-and-tags.md#the-tag-list)

### How do I rename a tag on every file at once?

On the settings page "Tags" of the workspace or the organization folder,
choose "Manage {tag}" and "Rename". Through the API or an agent: `PATCH`
the tag with a new `name`, or use the tool `workspace_tags_rename` or
`library_tags_rename`. Every file that carries the tag shows the new name at
once.

More: [Fields and tags, Renaming a tag](../files/fields-and-tags.md#renaming-a-tag)

### Can I rename or delete a tag in the app?

Yes, if you are an owner or admin of the workspace or the organization
folder. Its settings page "Tags" lists its tags, and "Manage {tag}" on a
row offers "Rename" and "Delete".

More: [Fields and tags, Managing tags](../files/fields-and-tags.md#managing-tags)

### Why can I not rename or delete tags in the app?

Renaming and deleting a tag changes every file that carries it, so only the
owners and admins of the workspace or the organization folder do it: for a
workspace its own owners and admins and the organization's, for the
organization folder the organization's. Everyone else sees the tags and
their counts, without "Manage". You can still add and remove tags on the
files you may change.

More: [Fields and tags, Managing tags](../files/fields-and-tags.md#managing-tags)

### What does the app ask before it deletes a tag?

"Delete {tag}?", with how many files lose it, for example "12 files lose
this tag. Files in the trash that have it lose it too. This cannot be
undone." The count is of live files. "Delete tag" confirms.

More: [Fields and tags, Managing tags](../files/fields-and-tags.md#managing-tags)

### How do I delete a tag everywhere?

On the settings page "Tags" of the workspace or the organization folder,
choose "Manage {tag}" and "Delete". Through the API or an
agent: `DELETE` the tag, or use the tool `workspace_tags_delete` or
`library_tags_delete`. The tag is removed from every file that carried it,
also files in the trash, and then deleted.

More: [Fields and tags, Deleting a tag](../files/fields-and-tags.md#deleting-a-tag)

### Who can rename or delete a tag?

The owners and admins of the workspace or the organization folder: for a
workspace tag, the workspace's owners and admins and the organization's; for
an organization folder tag, the organization's. A credential needs
`files:write` and works only when its member is one of them. Anyone else
gets `403 FORBIDDEN`. Tagging files stays open to whoever may change them.

More: [Fields and tags, Who can do what](../files/fields-and-tags.md#who-can-do-what)

### How do I merge two tags into one?

There is no merge. Give the files of one tag the other tag, then delete the
tag that is left over.

More: [Fields and tags, Renaming a tag](../files/fields-and-tags.md#renaming-a-tag)

### What happens when I rename a tag to the name of another tag?

It is refused with `409 CONFLICT`, reason `NAME_TAKEN`. Two tags are never
merged by a rename. The app says so under the box "Name": "Another tag here
already has that name, and a rename never merges two tags. To merge them,
give this tag's files the other tag, then delete this one."

More: [Fields and tags, Renaming a tag](../files/fields-and-tags.md#renaming-a-tag)

### Does a renamed tag keep its ID?

Yes. The tag keeps its ID, so a filter on it keeps working.

More: [Fields and tags, Renaming a tag](../files/fields-and-tags.md#renaming-a-tag)

### What does renaming a tag do to the files that carry it?

Each shows the new name at once, and its `lockVersion` moves.

More: [Fields and tags, Renaming a tag](../files/fields-and-tags.md#renaming-a-tag)

### What happens when I rename "brand" to "BRAND"?

Nothing changes. Both normalize to the same name, so the request succeeds
and the tag stays "brand".

More: [Fields and tags, Renaming a tag](../files/fields-and-tags.md#renaming-a-tag)

### What happens when I use the name of a deleted tag again?

A new tag with a new ID is created. Filters that used the old ID match
nothing.

More: [Fields and tags, Deleting a tag](../files/fields-and-tags.md#deleting-a-tag)

### How do I filter files by tag?

Open "Filter" and choose a tag in the group "Tag". It offers "All tags" and
every tag of the open workspace or organization folder.

More: [Fields and tags, Tags in the browser](../files/fields-and-tags.md#tags-in-the-browser)

### Can I filter by two tags at once?

No. A file list can be limited to the files that carry one tag. One tag at a
time.

More: [Fields and tags, Filtering by tag](../files/fields-and-tags.md#filtering-by-tag)

### Why is there no "Tag" group in my Filter menu?

The group appears once the open workspace or organization folder has at
least one tag.

More: [Fields and tags, Tags in the browser](../files/fields-and-tags.md#tags-in-the-browser)

### What does a tag's `fileCount` count?

The live files that carry the tag. Files in the trash are not counted.

More: [Fields and tags, The tag list](../files/fields-and-tags.md#the-tag-list)

### What does a `tag` filter with the ID of another workspace's tag return?

An empty list. A tag only marks files of its own workspace or organization
folder.

More: [Fields and tags, Filtering by tag](../files/fields-and-tags.md#filtering-by-tag)

### Can a tag be proposed for review and not set directly?

Yes. A suggestion can propose adding a tag to a file or removing one, for a
person to review.

More: [Fields and tags, Tags in suggestions](../files/fields-and-tags.md#tags-in-suggestions)

### What do the tag operations of the API answer?

Renaming answers the tag. Deleting answers `204`. Listing answers a page of
tags by name, each with `id`, `name` and `fileCount`, and a `nextCursor`.

More: [Fields and tags, Set, rename and delete tags](../files/fields-and-tags.md#set-rename-and-delete-tags)

## Description, caption and alt text

### Which built-in details does every file have?

Three besides its name: a description, a caption and an alt text. They are
free text and always there.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### What is the difference between a description and a caption?

A description says what the file is and how to use it, in up to 2,000
characters. A caption is a line to show with the file, in up to 500
characters.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### What is alt text for?

It describes an image for people who cannot see it. The app's hint reads
"Describe the image for people who cannot see it."

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### How do I add alt text to an image?

On the image's page, type it into "Alt text" in the section "Details" and choose
"Save details".

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### Why is there no "Alt text" on my PDF or video?

The app shows "Alt text" only for images. The API accepts an alt text on a
file of any type and stores it, but the app does not show it there.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### What happens when I paste several lines into "Alt text"?

The box takes one line, so the line breaks are dropped as the text goes in.
An alt text is a single line.

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

### Why does a save say "Remove the tab or other character that cannot be saved."?

The name, description, caption or alt text holds a control character that is
refused there. In practice this is a tab pasted into "Name" or "Alt text".

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### How do I remove a description, a caption or an alt text?

Empty the box and choose "Save details". Through the API, send `null`, an
empty string or only spaces. The detail then reads `null`.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### Can a description or a caption have several lines?

Yes. Tabs and line breaks are allowed in a description and a caption. Any
other control character is refused.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### Can I rename "Caption" or add built-in details of my own?

No. The three details are fixed properties of a file. They cannot be
renamed, removed or added to. For your own properties, define custom fields.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### Are description, caption and alt text custom fields?

No. They are not custom fields and they are not in any field list.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### Do description, caption and alt text survive a new version of the file?

Yes. They belong to the file, not to one version.

More: [Fields and tags, Built-in details](../files/fields-and-tags.md#built-in-details)

### Does the alt text travel with a file's public link?

No. A public link serves the file's bytes. Write the `alt` attribute in your
own page.

More: [Image delivery, A responsive image](../files/image-delivery.md#a-responsive-image)

### Why is "Save details" disabled?

Nothing in the form has changed yet. Beside the button the form says
"Unsaved changes" while there are any, and "Saved" after a save.

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### Which boxes in the form "File details" take several lines?

"Description" and "Caption". "Name", "Alt text" and "Tags" take one line.

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### What does "None" mean under "Description" or "Caption"?

The file has no such detail, and you are seeing the read-only view because
you cannot change the file.

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

## Saving at the same time as someone else

### Why was my save refused with "This file changed since you opened it"?

Someone or something changed the file after you opened it: another person, a
tag rename, a deleted field or a batch change. Choose "Reload latest". Your
typed edits are kept, and you can save again.

More: [Fields and tags, On a file's page](../files/fields-and-tags.md#on-a-files-page)

### What is a file's `lockVersion`?

A number that moves each time the file's details change. A change to one
file's details, tags or field values sends the `lockVersion` it was based on
as `expectedLockVersion`.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

### Which changes move a file's `lockVersion`?

A change to its name, description, caption, alt text, tags, folder or field
values. Setting a field on it in a batch. Renaming or deleting a tag it
carries. Deleting a field or a choice it had a value for. Moving it to the
trash and restoring it.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

### Does uploading a new version move the `lockVersion`?

No. A new version of the file does not move it.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

### Can two people overwrite each other's edits to a file's details?

No. The second save is refused with `409 STALE_LOCK_VERSION` and can be
repeated after reading the file again.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

### What should an agent do after `STALE_LOCK_VERSION` on a details change?

Read the file again, look at what changed and repeat the change with
`details.currentLockVersion`.

More: [Fields and tags, Set values on one file](../files/fields-and-tags.md#set-values-on-one-file)

### What happens when a change names nothing to change?

It succeeds, returns the file and moves nothing. A request that holds only
`expectedLockVersion` is such a change.

More: [Fields and tags, Stale pages and concurrent changes](../files/fields-and-tags.md#stale-pages-and-concurrent-changes)

### An admin deleted a field while I had a file open. What happens when I save?

If the file had a value for it, the save is refused with "This file changed
since you opened it." If it had none and you set one, the save is refused
with "A field or option changed. Reload and try again."

More: [Fields and tags, Edge cases](../files/fields-and-tags.md#edge-cases)

## Search, export and the audit trail

### Which of a file's details does search look at?

Its name, description, caption, alt text, tags and the values of its `text`
fields.

More: [Fields and tags, Search](../files/fields-and-tags.md#search)

### How soon can I search for a tag or description I just saved?

At once. The moment a description, tag or text value is saved, cleared or
deleted, search follows.

More: [Fields and tags, Search](../files/fields-and-tags.md#search)

### Does search match the middle of a word in a description or tag?

No. Each search word matches as the start of a word: "spr" finds "Spring
launch".

More: [Fields and tags, Search](../files/fields-and-tags.md#search)

### What does an organization export hold about fields and tags?

For every workspace and the organization folder, its custom fields with
their kinds and choices and its tags, and for every file its tags, its field
values, its description, caption and alt text.

More: [Fields and tags, In the export](../files/fields-and-tags.md#in-the-export)

### Which audit events record changes to fields and tags?

`file_field.created`, `file_field.updated`, `file_field.deleted` and
`file_field.reordered` for the field list, `tag.renamed` and `tag.deleted`
for tags, and `file.updated` for a change to a file's details, tags or
values.

More: [Fields and tags, In the audit trail](../files/fields-and-tags.md#in-the-audit-trail)

### How many audit events does setting one field on many files record?

One `file.updated` event per file.

More: [Fields and tags, In the audit trail](../files/fields-and-tags.md#in-the-audit-trail)

## Agents and the API

### Which MCP tools work with fields and field values?

`workspace_file_fields_list` (with `workspaceID`) and
`library_file_fields_list` (with `organizationID`) read the fields of a
workspace or the organization folder. `workspace_files_update`
and `library_files_update` set values on one file. `workspace_files_fields_set`
and `library_files_fields_set` set one field on many files.

More: [Fields and tags, For agents](../files/fields-and-tags.md#for-agents)

### Why should an agent list the fields before it sets a value?

Field values are sent by field ID and choice ID, not by name. The field list
of the workspace or organization folder the files are in returns every field
with its kind and its choices. Each workspace and the organization folder
has its own IDs.

More: [Fields and tags, List the fields first](../files/fields-and-tags.md#list-the-fields-first)

### Why is the first item of the field list called `status`?

It is the built-in status: `id` `status`, `builtin` `status`, kind `select`,
with the workspace's or organization folder's statuses as its choices. It is
there so one call describes everything a file can carry. It is set with the
status operation, never through `fields`.

More: [Fields and tags, List the fields first](../files/fields-and-tags.md#list-the-fields-first)

### What do `builtin` and `allowsPublic` read on a custom field?

`builtin` is `null` on the workspace's or organization folder's own fields,
and their choices' `allowsPublic` is `null`. Only the built-in status
carries values there.

More: [Fields and tags, List the fields first](../files/fields-and-tags.md#list-the-fields-first)

### How does an agent work through the files that miss a field?

List them with `field={fieldID}:none`, read each file for its `lockVersion`
and set the value. The listing returns summaries that carry `tags` but not
`fields`.

More: [Fields and tags, Filter by a field or a tag](../files/fields-and-tags.md#filter-by-a-field-or-a-tag)

### Can an agent define fields or options?

No. An agent reads the fields, sets values and tags, and filters. It renames
and deletes tags only when its member is an owner or admin of the workspace
or the organization folder. Fields and options are defined by a person in a
browser.

More: [Fields and tags, For agents](../files/fields-and-tags.md#for-agents)

### Does an organization folder version exist for every field and tag operation?

Yes. Every workspace operation has an organization folder twin under
`/v1/organizations/{organizationID}/library` with the same body and answer.

More: [Fields and tags, For agents](../files/fields-and-tags.md#for-agents)

### What do the browser-only field operations take and return?

Adding a field takes `name`, `kind` and optional `choices` and answers `201`
with the field. Renaming takes `name`. Deleting a field answers `204`.
Reordering takes `fieldIDs` and answers the whole list, the status first.
Adding, renaming, deleting and reordering choices answer the field.

More: [Fields and tags, What the session-only operations take and return](../files/fields-and-tags.md#what-the-session-only-operations-take-and-return)
