# Fields and tags

## Summary

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

A file carries four kinds of description:

- **Built-in details.** Every file has a description, a caption and an alt
  text. They are free text and always there.
- **Tags.** Short lower-case labels, up to 50 per file. Anyone who may change
  a file adds them freely. Tags belong to one workspace, or to the
  organization folder.
- **Custom fields.** Typed values that each workspace, and 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.
- **The status.** The built-in first field. It decides whether a file may be
  public and has its own rules. See [Statuses](statuses.md).

The owners and admins of a workspace or the organization folder decide which
custom fields it has and manage its tags. Whoever may change a file fills in
its fields and tags. Everyone who can open a file reads them.

This page covers custom fields and their choices, field values, tags, the
built-in details, and the field and tag filters. Renaming and moving files,
search and the other filters are in
[Folders, moving and finding](organizing.md).

## Who can do what

"Member of the workspace" means everyone who can open the workspace:
organization owners and admins, and members with a workspace membership.
"Owner or admin of the workspace" means the workspace's own owners and admins
and the organization's owners and admins. See
[Roles and permissions](../reference/permissions.md).

| Action | Who | Session | Credential (scope) |
| --- | --- | --- | --- |
| List the fields and their choices of a workspace or the organization folder | Everyone who can open it | Yes | Yes (`files:read`) |
| Add, rename, reorder or delete a field of a workspace | Owner or admin of the workspace | Yes | No |
| Add, rename, reorder or delete a field of the organization folder | Organization owner or admin | Yes | No |
| Add, rename, reorder or delete a choice of a field | The same as for the field | Yes | No |
| Read a file's field values, details and tags | Everyone who can open the workspace or the organization folder | Yes | Yes (`files:read`) |
| Set field values on a workspace file | Every member of the workspace | Yes | Yes (`files:write`) |
| Set field values on an organization folder file | Organization owner or admin | Yes | Yes (`files:write`) |
| Set one field on up to 100 files at once | The same as for one file | Yes | Yes (`files:write`) |
| Change a file's description, caption, alt text or tags | The same as for field values | Yes | Yes (`files:write`) |
| List the tags of a workspace or the organization folder | Everyone who can open it | Yes | Yes (`files:read`) |
| Rename or delete a tag of a workspace | Owner or admin of the workspace | Yes | Yes (`files:write`) |
| Rename or delete a tag of the organization folder | Organization owner or admin | Yes | Yes (`files:write`) |
| Filter a file list by field or tag | Everyone who can open it | Yes | Yes (`files:read`) |

- A credential acts for one member. The role rules above apply to that
  member: a `files:write` key of a plain member cannot change organization
  folder files or rename a tag.
- `files:write` includes `files:read`.
- Defining fields and choices is done by a person in a browser. A credential
  that tries gets `403 FORBIDDEN` with `details.reason` `SESSION_REQUIRED`.
- Someone who is not an owner or admin of the workspace or the organization
  folder gets `403 FORBIDDEN` when defining its fields and choices, or
  renaming or deleting its tags. A workspace admin who is a plain member of
  the organization manages the workspace's fields and tags, not the
  organization folder's.
- No verified email is needed for anything on this page.
- Setting the status needs more than this: an owner or admin, and
  `files:approve` for a credential. See
  [Statuses](statuses.md#setting-a-status-on-files).

## How it works

### Custom fields

- Every workspace has its own ordered list of custom fields, and so does the
  organization folder.
- A file carries values only of the fields of its own workspace, or of the
  organization folder for an organization folder file. A field of the
  organization folder cannot be set on a workspace file, nor a field of one
  workspace on a file of another.
- A new workspace has no custom fields, and neither does the organization
  folder of a new organization. They have only the built-in status.
- Fields of another workspace, of the organization folder or of another
  organization cannot be set or filtered by: that is refused with `422
  VALIDATION_FAILED`. Renaming, reordering or deleting a field of another
  workspace or organization folder through this one answers `404 NOT_FOUND`.

#### Kinds

Every field has one kind. The kind is chosen when the field is created and
never changes.

| Kind | In the app | Holds | In the API |
| --- | --- | --- | --- |
| `text` | "Text" | Free text, up to 2,000 characters. Line breaks are allowed. | A string |
| `number` | "Number" | One number, whole or with decimals. | A JSON number |
| `date` | "Date" | One calendar date, without a time. | A string `YYYY-MM-DD` |
| `select` | "Single select" | One choice from the field's list. | A choice ID |
| `multiSelect` | "Multi-select" | Any number of choices from the field's list. | A list of choice IDs |

- To change a field's kind, create a new field of the other kind and delete
  the old one. The old values are deleted with it.

#### Naming rules

- A field name is 1 to 60 characters long.
- Spaces at the start and end are removed before the name is measured and
  stored.
- A name with a control character, such as a tab or a line break, is refused.
- Field names are unique in their workspace or organization folder, ignoring
  case. "Rights" and "rights" cannot both exist there. Two workspaces can
  each have a field "Rights"; they are different fields.
- A custom field may be named "Status". The built-in status is not part of
  the name check.
- A choice name follows the same rules: 1 to 60 characters, trimmed, no
  control characters.
- Choice names are unique within their field, ignoring case. Two different
  fields can each have a choice "Other".

#### Creating a field

- The owners and admins of the workspace or the organization folder create
  its fields, in a browser.
- A field needs a name and a kind.
- A `select` or `multiSelect` field can be created with its choices, in the
  order given. It can also be created with none and get them later.
- Choices given for a `text`, `number` or `date` field are refused. Nothing
  is created.
- Two choices with the same name in one request are refused. Nothing is
  created.
- A new field goes to the end of the list.
- A workspace, or the organization folder, has at most 50 custom fields. The
  51st is refused with `422 VALIDATION_FAILED` on `fields` and the message
  "a file space has at most 50 fields". The app says "A workspace or the
  organization folder can have up to 50 custom fields. Delete one to add
  another."
- A field has at most 100 choices. A request with 101, or a 101st choice,
  is refused with `422 VALIDATION_FAILED` on `choices` and the message "a
  field has at most 100 choices".
- No file has a value for a new field. Nothing changes on any file.

#### Choices

- Only `select` and `multiSelect` fields have choices.
- Owners and admins add a choice to an existing field. It goes to the end of
  the field's choices.
- Adding a choice to a field that already has 100 is refused.
- Adding a choice to a `text`, `number` or `date` field is refused.
- A choice has an ID that never changes. Files store the ID, not the name.
- The app calls choices "options".

#### Renaming

- Owners and admins rename a field or a choice.
- A rename changes the name everywhere at once: on every file of the
  workspace or the organization folder, in filters and in the settings.
- A rename does not change any file. Values stay, and no file's
  `lockVersion` moves.
- Renaming to a name another field has, or another choice of the same field
  has, is refused with `409 CONFLICT`, reason `NAME_TAKEN`.
- Renaming a field or choice to its own name in a different case works.

#### Reordering

- Owners and admins put the fields in a new order, and the choices of a
  field in a new order.
- The order is the order in which fields show on a file and in the settings,
  and in which choices show in pickers and filters.
- A reorder request names every field of the workspace or the organization
  folder exactly once. A list that leaves one out, repeats one or names an
  unknown one is refused. Nothing changes.
- The same holds for choices: every choice of the field, exactly once.
- The built-in status is always first. It is not part of the order and is
  not named in a reorder.

#### Deleting a field

- Owners and admins delete a field.
- Deleting a field deletes every value of it, on every file of the workspace
  or the organization folder, live or in the trash.
- The values are gone for good. Creating a field with the same name later
  does not bring them back.
- Every file that had a value changes: its `lockVersion` moves, and it shows
  the person who deleted the field as the one who last changed it.
- Text values of the deleted field stop matching in search at once.
- The remaining fields close the gap in the order.
- Files that had no value are not touched.
- The app asks first and says how many files lose a value, live ones and
  those in the trash ("... and so will N files in the trash."). The API asks
  no confirmation.

#### Deleting a choice

- Owners and admins delete a choice.
- On a `select` field, files that had the choice have no value afterwards.
- On a `multiSelect` field, files that had the choice lose only that choice
  and keep their other choices.
- Every file that had the choice changes: its `lockVersion` moves.
- Files in the trash lose the choice as well.
- The remaining choices close the gap in the order.

#### Counts

- Every field reads `fileCount`: the number of live files of its workspace,
  or of the organization folder, that have a value for it.
- Every choice reads `fileCount`: the number of those files that have that
  choice.
- `fileCount` is the same for everyone who can open the workspace or the
  organization folder, as a status's counts are. See
  [Statuses](statuses.md#counts).
- Files in the trash are not counted in `fileCount`.
- Every field and choice also reads `trashedFileCount`: the number of files
  in the trash of the workspace or the organization folder that have a value
  for the field, or that choice. A deletion takes the value from them too.
- The app shows `fileCount` beside each field and option, and both numbers
  before a deletion.
- `trashedFileCount` 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 and its statuses `trashedFileCount` is
  always `null`.

### Field values

- A file has, for each field, one value or no value.
- A value belongs to the file, not to one version of it. Replacing the file
  with a new version keeps its values.
- A new upload has no values.
- Whoever may change a file sets its values: every member of the workspace
  for a workspace file, organization owners and admins for an organization
  folder file.
- Setting a value replaces the value the file had for that field.
- A file's values are read on the file itself, under `fields`, keyed by
  field ID. A field without a value is left out.
- File lists and search results do not carry `fields`. Read the file to see
  its values.
- A `multiSelect` value is returned in the order of the field's choices,
  whatever order it was sent in.
- Values are not part of the status. The status has its own operations.

#### What each kind accepts

| Kind | Accepted | Refused | Clears the value |
| --- | --- | --- | --- |
| `text` | A string of 1 to 2,000 characters after trimming. Line breaks and tabs are allowed. | A number or any other type. More than 2,000 characters. Other control characters. | `null`, or a string that is empty or only spaces |
| `number` | A JSON number, whole or with decimals. | A string, also one that holds digits, such as `"12"`. | `null` |
| `date` | A string `YYYY-MM-DD` that is a real date. | A date that does not exist, such as `2026-13-01`. A number. | `null` |
| `select` | The ID of one choice of that field, as a string. | A list. The ID of a choice of another field. An unknown ID. | `null` |
| `multiSelect` | A list of IDs of choices of that field. Repeated IDs count once. | A single ID that is not in a list. A choice of another field. An unknown ID. | `null`, or an empty list |

- Every refusal is `422 VALIDATION_FAILED` on `fields`.
- Text is trimmed before it is stored.

#### Setting values on one file

- Values are set with the file's other details in one change: the request
  may also rename the file, change its description, caption, alt text and
  tags, and move it.
- `fields` maps field IDs to values. Fields that are left out keep their
  values.
- The change needs the file's current `lockVersion` as
  `expectedLockVersion`. See
  [Stale pages and concurrent changes](#stale-pages-and-concurrent-changes).
- The change is all or nothing. If one value is refused, nothing in the
  request is applied: not the other values, not the new description.
- The file's `lockVersion` moves by one, however many details the request
  changed.
- A key that is not a field ID is refused. That includes the key `status`:
  the status is set with its own operation.

The checks happen in this order. The first that fails decides the answer:

1. Not signed in, or no valid credential: `401 UNAUTHENTICATED`.
2. The workspace or organization is unknown or out of reach:
   `404 NOT_FOUND`.
3. A key of `fields` is not a field ID: `422 VALIDATION_FAILED` on `fields`.
4. An organization folder file and you are not an owner or admin: `403
   FORBIDDEN`.
5. The name, alt text, description, caption or tags break their rules:
   `422 VALIDATION_FAILED` on that property.
6. The file is unknown here: `404 NOT_FOUND`.
7. The file is in the trash: `409 CONFLICT`, reason `IN_TRASH`.
8. `expectedLockVersion` is not current: `409 STALE_LOCK_VERSION`.
9. A field or choice is unknown, belongs to another workspace or the
   organization folder (or, for an organization folder file, to a
   workspace), or a value is of the wrong kind: `422 VALIDATION_FAILED` on
   `fields`.
10. Otherwise the file is changed: `200` with the file.

#### Setting one field on many files

- One request sets one field to one value on 1 to 100 files of the same
  workspace, or of the organization folder.
- It needs no `expectedLockVersion`. It overwrites whatever value each file
  had.
- `value` must be present. `null` clears the field on every named file. A
  request without `value` is refused and changes nothing.
- A file named twice counts once.
- The change is all or nothing. One unknown file refuses the whole request
  with `404 NOT_FOUND`. One file in the trash refuses it with `409 CONFLICT`,
  reason `IN_TRASH`.
- Every named file's `lockVersion` moves, also files that already had that
  value.
- The answer names the field and the files changed.
- The field must be a custom field of the same workspace or organization
  folder as the files. A field of another one is refused with `422
  VALIDATION_FAILED`. The built-in status cannot be named here.

### Filtering by field

- A file list can be limited to files with given field values.
- The filter is `field`, a comma-separated list of entries.
- An entry is `{fieldID}:{choiceID}`: files that have that choice. This
  works for `select` and `multiSelect` fields.
- Or an entry is `{fieldID}:none`: files that have no value for that field.
  This works for fields of every kind.
- Several entries for the same field match files that fit any of them.
- Entries for different fields must all match.
- A `multiSelect` file matches a choice when that choice is among its
  choices.
- There is no filter for the content of a `text`, `number` or `date` field.
  Text values are found through search. See [Search](#search).
- The filter combines with every other filter of the list: folder, search
  words, tag, type, status.
- A malformed entry, a field of another workspace, of the organization
  folder or of another organization, an unknown field or a choice that does
  not belong to the field is refused with `422 VALIDATION_FAILED` on
  `field`. Each list takes only the fields of the workspace or organization
  folder it lists.

Example: files whose "Rights" is "Owned" or not set, and whose "Channels"
include "Web":

```text
field={rightsID}:{ownedID},{rightsID}:none,{channelsID}:{webID}
```

### Tags

- A tag is a short label on files.
- Tags belong to one workspace, or to the organization folder. Every
  workspace has its own tags. The organization folder has its own.
- A tag is created by naming it on a file. There is no separate step to
  create one.
- Whoever may change a file sets its tags.
- A new upload has no tags.
- Tags belong to the file, not to one version. Replacing the file keeps
  them.

#### Tag names

- A tag name is normalized before it is stored: spaces at the start and end
  are removed, several spaces in a row become one, and letters become lower
  case.
- So "Brand", "brand" and " BRAND " are the same tag, "brand".
- "Campaign   2026" becomes "campaign 2026".
- A tag is 1 to 50 characters long once normalized.
- A tag with a control character, such as a tab or a line break, is refused.
- A tag with a comma is refused, with the message "a tag cannot contain a
  comma": on `tags` when it is set on a file or proposed, on `name` when a
  tag is renamed to it. See [The comma rule](#the-comma-rule).
- Any other character is allowed.

#### Setting a file's tags

- A file's tags are set as one complete list. The list 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.
- Names that normalize to the same tag count once.
- A file has at most 50 tags. A list with more, after duplicates are
  removed, is refused with `422 VALIDATION_FAILED` on `tags`.
- An empty name in the list is refused.
- Tags that do not exist yet in the workspace or organization folder are
  created.
- A file returns its tags sorted by name, each with `id` and `name`.
- File lists and search results carry each file's tags.

#### The tag list

- Each workspace and the organization folder has a list of its tags, sorted
  by name.
- Each tag reads `fileCount`: the number of live files that carry it. Files
  in the trash are not counted.
- A tag that no file carries any more stays in the list with a count of 0,
  until someone deletes it.
- The list is paged: 1 to 100 tags a page, 50 by default.

#### Renaming a tag

- The owners and admins of the workspace or the organization folder rename
  its tags: for a workspace its own owners and admins and the
  organization's, for the organization folder the organization's. A
  credential with `files:write` may, when its member is one of them. Anyone
  else gets `403 FORBIDDEN`.
- The new name is normalized like any tag name.
- Every file that carries the tag shows the new name at once, and its
  `lockVersion` moves.
- Renaming to a name another tag of the same workspace or organization
  folder has is refused with `409 CONFLICT`, reason `NAME_TAKEN`. Two tags
  are never merged by a rename.
- Renaming a tag to the name it already has, after normalizing, succeeds and
  changes nothing.
- The tag keeps its ID.

#### Deleting a tag

- The same owners and admins delete its tags, also through a credential
  with `files:write`. Anyone else gets `403 FORBIDDEN`.
- The tag is removed from every file that carried it, also files in the
  trash, and then deleted.
- Every file that carried it changes: its `lockVersion` moves.
- Naming the same tag on a file later creates a new tag with a new ID.

#### Filtering by tag

- A file list can be limited to the files that carry one tag: `tag` with the
  tag's ID.
- One tag at a time.
- The tag must be of the same workspace or organization folder. A tag ID
  from elsewhere matches no files.

#### Tags in suggestions

- A suggestion can propose adding a tag to a file or removing one, for a
  person to review. See [The organization folder and
  suggestions](library-and-suggestions.md#suggestions).

### Built-in details

Every file has three text details besides its name. They are fixed
properties of a file. They are not custom fields, they are not in any field
list, and they cannot be renamed, removed or added to.

| Detail | Property | Length | Line breaks | For |
| --- | --- | --- | --- | --- |
| Description | `description` | Up to 2,000 characters | Allowed | What the file is and how to use it. |
| Caption | `caption` | Up to 500 characters | Allowed | A line to show with the file. |
| Alt text | `altText` | Up to 1,000 characters | Refused | A description of an image for people who cannot see it. |

- Each is text or nothing. A file without one reads `null`.
- Spaces at the start and end are removed before the text is measured and
  stored.
- `null`, an empty string or only spaces clears the detail.
- Tabs and line breaks are allowed in a description and a caption. Any other
  control character is refused.
- An alt text with any control character is refused, including a line break.
- Whoever may change the file changes them: workspace members for workspace
  files, owners and admins for organization folder files.
- They belong to the file, not to one version. Replacing the file keeps
  them.
- A new upload has none of them.
- The API accepts an alt text on a file of any type. The app shows "Alt
  text" only for images.
- A suggestion can propose an alt text. See [The organization folder and
  suggestions](library-and-suggestions.md#suggestions).
- The file's name is the fourth detail in the same form. Its rules are in
  [Folders, moving and finding](organizing.md).

### Stale pages and concurrent changes

- Every file has a `lockVersion`, a number that moves each time its details
  change.
- A change to one file's details, tags or field values sends the
  `lockVersion` it was based on as `expectedLockVersion`.
- If the file changed in between, the change is refused with
  `409 STALE_LOCK_VERSION`. `details.currentLockVersion` holds the current
  number. Nothing is changed.
- So two people who edit the same file at once cannot silently overwrite
  each other. The second save is refused and can be repeated after reading
  the file again.
- These 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.
- A new version of the file does not move it.
- Setting one field on many files sends no `expectedLockVersion`. It always
  applies, and it moves each file's `lockVersion`. A page that had one of
  those files open is stale afterwards.
- A change that names nothing to change succeeds and moves nothing.
- A change that sets a detail to the value it already has still counts as a
  change: the `lockVersion` moves.
- Changes to a field list itself are handled one after the other. Two
  admins who add the 50th field of a workspace at the same moment cannot end
  up with 51.

### Search

- Search words match in a file's name, description, caption, alt text, tags
  and the values of its `text` fields.
- Each word matches as the start of a word: "spr" finds "Spring launch".
- Values of `number`, `date`, `select` and `multiSelect` fields are not
  searched. Choice names are not searched. Use the `field` filter for
  choices.
- A change is searchable at once: the moment a description, tag or text
  value is saved, cleared or deleted, search follows.
- Everything else about search is in
  [Folders, moving and finding](organizing.md).

### In the export

- An organization export lists, 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.
- See [Export](../organizations/export.md#the-manifest).

### In the audit trail

- Adding, renaming and deleting a field, changing its choices and reordering
  the fields are recorded as `file_field.created`, `file_field.updated`,
  `file_field.deleted` and `file_field.reordered`.
- Renaming and deleting a tag are recorded as `tag.renamed` and
  `tag.deleted`, with the number of files.
- A change to a file's details, tags or values is recorded as
  `file.updated`. Setting one field on many files records one event per
  file.
- See [Audit trail](../reference/audit-trail.md).

## In the app

### Defining fields

Each workspace and the organization folder has its own settings pages
"Statuses", "Custom fields" and "Tags", under "Files & Assets" in its own
level of the settings navigation (see [Workspaces, The settings
navigation](../organizations/workspaces.md#the-settings-navigation)).

- The organization folder's is **Settings > File spaces > Organization folder > Custom fields**
  (`/settings/organization/{organizationID}/library/fields`).
- A workspace's is **Settings > File spaces >
  {workspace} > Custom fields**
  (`/settings/organization/{organizationID}/workspaces/{workspaceID}/files/fields`).

The table "Custom fields" lists the fields of that workspace or the
organization folder in order. Everyone who can open it sees the table. Its
owners and admins also see the controls: "Add field" and each "Manage
{name}".

- Each field's row shows, under "Name", "Type" and "Files", its name, its
  kind ("Text", "Number", "Date", "Single select" or "Multi-select") and the
  number of files with a value, such as "7 files".
- Under a field with choices, each option has an indented row of its own,
  with the type "Option" and its own file count.
- With no custom fields the page says "No custom fields yet". While the
  table loads it reads "Loading fields". If it cannot be loaded: "Could not
  load the fields."

To add a field:

1. Choose "Add field".
2. The dialog "Add field" has "Name" and "Kind". The kind starts on "Text".
3. For "Single select" and "Multi-select" it also has "Options", with the
   hint "One per line." Empty lines are ignored.
4. "Add field" creates it. The field appears at the end of the list.

- A blank or too long name shows "Enter a name of 1 to 60 characters."
- A name another field has shows "That name is taken."
- Too many or too long options show "Use at most 100 options of 1 to 60
  characters each."
- With 50 custom fields the dialog shows "A workspace or the organization
  folder can have up to 50 custom fields. Delete one to add another."

Each field and each option has a menu, "Manage {name}":

- "Rename" opens "Rename {name}" with the field "Name" and the button
  "Rename".
- "Add option", on fields with options, opens "Add option to {field}" with
  "Name" and the button "Add option". On a field with 100 options it shows
  "A field can have up to 100 options. Delete one to add another."
- "Move up" and "Move down" change the order by one place. The first has no
  "Move up", the last no "Move down".
- "Delete" asks "Delete {name}?" and says "{n} files will lose this value."
  or "No file has this value." When files in the trash have one too, it
  says, for example, "7 files will lose this value, and so will 2 files in
  the trash.", or, with no live file, "2 files in the trash will lose this
  value." The button is "Delete field" or "Delete option".
- If a change fails, the row says "Could not change the field. Try again."
  or "Could not change the option. Try again."

### On a file's page

Under the preview, a file's page has "Details": the section "Details" with
its form on the left and other sections on the right. The form and the
section "Fields" hold what this page describes.

The form "File details":

- "Name", "Description", "Caption" and "Tags". For images also "Alt text",
  with the hint "Describe the image for people who cannot see it."
- "Description" and "Caption" take several lines. "Name", "Alt text" and
  "Tags" take one line.
- "Tags" is one text box with the hint "Separate tags with commas."
- "Save details" saves the form. It is disabled until something changed.
- Beside the button the form says "Unsaved changes" while there are any, and
  "Saved" after a save.
- After a save, "Tags" shows the tags as they are stored: normalized and
  sorted by name. " Spring Launch , q3" becomes "q3, spring launch".

The section "Fields":

- One input per custom field of the file's workspace or organization folder,
  in the fields' order:
  - 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",
  - a checkbox per option for "Multi-select".
- "Save fields" saves the section. It is disabled until a value changed.
- "Details" and "Fields" each save only their own part. Unsaved edits in the
  other stay.
- While the workspace or organization folder has no custom fields the
  section is not shown.
- The status has its own section, "Status". See [Statuses](statuses.md).

What you see when you cannot change the file, for example as a member in the
organization folder:

- "Details" shows "Description", "Caption", "Alt text" (images) and "Tags" as
  text. A missing one reads "None".
- "Fields" shows 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 details" and no "Save fields".

Messages when a save is refused:

- "Enter a name of 1 to 200 characters."
- "A description can be up to 2,000 characters."
- "A caption can be up to 500 characters."
- "Alt text can be up to 1,000 characters."
- "Remove the tab or other character that cannot be saved." under the
  name, description, caption or alt text that holds a control character
  the API refuses there. In practice this is a tab pasted into "Name" or
  "Alt text".
- "Use at most 50 tags of 1 to 50 characters each."
- "A field or option changed. Reload and try again." when a field or option
  was deleted since the page loaded.
- "This file is in the trash."
- "Only organization owners and admins can change the organization folder."
- "Could not save the details. Try again." for anything else.

When someone else changed the file since you opened it, the save is not
applied. The page says "This file changed since you opened it. Reloading
keeps your unsaved edits." with the button "Reload latest". After the
reload the page shows the other person's changes with your typed edits still
in place, and the next save applies both.

### The comma rule

- In the app a file's tags are typed into one box, separated by commas.
- So "red, white" typed in the app is two tags, "red" and "white".
- The API follows the same rule and refuses a tag that holds a comma.
- Spaces around a comma do not matter. Empty entries, as in "a, , b", are
  ignored.
- Typing the same tag twice stores it once.
- To add a tag, add it to the text and save. To remove one, delete it from
  the text and save. To remove all, empty the box and save.

### Tags in the browser

- In the list view each file row shows its tags under its name. The grid
  view does not show tags.
- The Filter menu has the group "Tag", with "All tags" and every tag of the
  open workspace or organization folder. It appears once there is at least
  one tag.
- Tags are renamed and deleted in the settings. See
  [Managing tags](#managing-tags).

### Managing tags

The settings page "Tags" of a workspace or the organization folder lists its
tags. See [Defining fields](#defining-fields) for where the pages are.

- The table is named "Tags". Each row shows, under "Name" and "Files", the
  tag's name and how many live files carry it, such as "12 files", "1 file"
  or "0 files".
- A workspace or organization folder without tags says "No tags yet". While
  the list loads the section says "Loading tags". If it cannot be loaded it
  says "Could not load the tags." with "Retry".
- Owners and admins of the workspace or the organization folder get the
  button "Manage {tag}" on each row, with "Rename" and "Delete". For a
  workspace that is its own owners and admins and the organization's; for
  the organization folder the organization's.
- Everyone else who can open it sees the list without the buttons. A rename
  or delete refused for lack of a role says "Only owners and admins rename
  and delete tags here."

To rename a tag:

1. Choose "Manage {tag}", then "Rename". The dialog "Rename {tag}" opens
   with the name in the box "Name". Under it: "12 files show the new name at
   once." The line is left out for a tag no file carries.
2. Type the new name and choose "Rename".
3. The app says "Renamed to {name}", with the name as it was stored: lower
   case, without extra spaces.

- A name another tag of the place already has is refused under the box:
  "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."
- An empty name or one with a comma is refused: "Enter a name of 1 to 50
  characters without a comma." The box takes at most 50 characters.
- A tag that someone deleted meanwhile: "This tag no longer exists. The list
  is up to date now."

To delete a tag:

1. Choose "Manage {tag}", then "Delete". The app asks "Delete {tag}?" and
   says how many files lose it: "12 files lose this tag. Files in the trash
   that have it lose it too. This cannot be undone." For a tag no live file
   carries: "No file outside the trash has this tag. Files in the trash that
   have it lose it too. This cannot be undone."
2. Choose "Delete tag". The app says "Deleted {tag}".

- If the delete fails the app says why, or "Could not delete the tag. Try
  again."
- After a rename or a delete, the file listings, the "Tag" group of the
  Filter menu and open file pages of that place show the change without a
  reload.
- A file page with unsaved edits says the file changed, as after any change
  by someone else. See
  [Stale pages and concurrent changes](#stale-pages-and-concurrent-changes).

### Filtering by field in the browser

- The Filter menu has one group per "Single select" and "Multi-select"
  field of the open workspace or organization folder, named after the field.
- Each group offers "Any" (no filter), "Not set" (files without a value) and
  every option.
- One choice per field at a time. Filters of several fields combine: a file
  must match all of them.
- "Text", "Number" and "Date" fields are not in the Filter menu.
- The "Filter" button shows how many filters are on. "Clear filters" turns
  them all off.
- A field or tag filter looks through every folder of the workspace or
  organization folder, not only the open one. Each result says which folder
  it is in.

### Setting a field on a selection

1. Select files in the browser. The toolbar "Selected files" appears.
2. Choose "Set field". It is offered while the open workspace or
   organization folder has at least one custom field and you may change the
   files. The picker offers that workspace's or organization folder's
   fields.
3. The dialog "Set field on {n} files" has the picker "Field" and, once a
   field is chosen, the input for its kind.
4. "Set field" applies it. Leaving the input empty, or choosing "None",
   clears the field on the selected files.
5. The app shows "Set {field} on {n} files".

- Folders in the selection are ignored. Only the selected files change.
- More than 100 files are sent in batches of 100. If a later batch fails,
  the earlier ones stay applied and the list is refreshed.
- The command palette offers the same as "Set field".
- If it fails the app says one of:
  - "A selected file is in the trash. Clear the selection and try again."
  - "A selected file no longer exists. The list is up to date now."
  - "That field or option no longer exists. Choose another."
  - "Only organization owners and admins can change the organization folder."
  - "Could not set the field. Try again."

## For agents

`W` is `/v1/workspaces/{workspaceID}`. Every workspace operation has a
twin for the organization folder (the API's library) under
`/v1/organizations/{organizationID}/library`
with the same body and answer. MCP tool names are the capability IDs with
the dots replaced by underscores. See [MCP](../agents/mcp.md).

| Operation | Capability ID | MCP tool | Scope |
| --- | --- | --- | --- |
| `GET W/file-fields` | `workspace.file_fields.list`, `library.file_fields.list` | `workspace_file_fields_list`, `library_file_fields_list` | `files:read` |
| `GET W/files/{fileID}` | `workspace.files.get`, `library.files.get` | `workspace_files_get`, `library_files_get` | `files:read` |
| `PATCH W/files/{fileID}` | `workspace.files.update`, `library.files.update` | `workspace_files_update`, `library_files_update` | `files:write` |
| `POST W/files/fields` | `workspace.files.fields.set`, `library.files.fields.set` | `workspace_files_fields_set`, `library_files_fields_set` | `files:write` |
| `GET W/files?field=...&tag=...` | `workspace.files.search`, `library.files.search` | `workspace_files_search`, `library_files_search` | `files:read` |
| `GET W/tags` | `workspace.tags.list`, `library.tags.list` | `workspace_tags_list`, `library_tags_list` | `files:read` |
| `PATCH W/tags/{tagID}` | `workspace.tags.rename`, `library.tags.rename` | `workspace_tags_rename`, `library_tags_rename` | `files:write` |
| `DELETE W/tags/{tagID}` | `workspace.tags.delete`, `library.tags.delete` | `workspace_tags_delete`, `library_tags_delete` | `files:write` |
| `POST W/file-fields` | `workspace.file_fields.create`, `library.file_fields.create` | none | session only |
| `PATCH W/file-fields/{fieldID}` | `workspace.file_fields.update`, `library.file_fields.update` | none | session only |
| `DELETE W/file-fields/{fieldID}` | `workspace.file_fields.delete`, `library.file_fields.delete` | none | session only |
| `PUT W/file-fields/order` | `workspace.file_fields.reorder`, `library.file_fields.reorder` | none | session only |
| `POST W/file-fields/{fieldID}/choices` | `workspace.file_fields.choices.create`, `library.file_fields.choices.create` | none | session only |
| `PATCH W/file-fields/{fieldID}/choices/{choiceID}` | `workspace.file_fields.choices.update`, `library.file_fields.choices.update` | none | session only |
| `DELETE W/file-fields/{fieldID}/choices/{choiceID}` | `workspace.file_fields.choices.delete`, `library.file_fields.choices.delete` | none | session only |
| `PUT W/file-fields/{fieldID}/choices/order` | `workspace.file_fields.choices.reorder`, `library.file_fields.choices.reorder` | none | session only |

An agent reads the fields, sets values and tags, and filters. An agent whose
member is an owner or admin of the workspace or the organization folder also
renames and deletes its tags. No agent can define fields or choices.

### List the fields first

Field values are sent by field ID and choice ID. Each workspace and the
organization folder has its own fields, so read the list of the place the
files are in:

```sh
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/file-fields" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

```json
{
  "items": [
    {
      "id": "status",
      "name": "Status",
      "kind": "select",
      "builtin": "status",
      "fileCount": 31,
      "trashedFileCount": null,
      "choices": [
        { "id": "0192e7c4-0c31-7f72-a043-6ebc9c8f7050", "name": "Approved for public use", "fileCount": 12, "trashedFileCount": null, "allowsPublic": true },
        { "id": "0192e7c4-0c32-7f72-a043-6ebc9c8f7051", "name": "Internal use only", "fileCount": 19, "trashedFileCount": null, "allowsPublic": false },
        { "id": "0192e7c4-0c33-7f72-a043-6ebc9c8f7052", "name": "Not approved", "fileCount": 0, "trashedFileCount": null, "allowsPublic": false }
      ]
    },
    {
      "id": "0192e7c5-1a01-7c10-9d21-000000000001",
      "name": "Rights",
      "kind": "select",
      "builtin": null,
      "fileCount": 7,
      "trashedFileCount": null,
      "choices": [
        { "id": "0192e7c5-1a02-7c10-9d21-000000000002", "name": "Owned", "fileCount": 5, "trashedFileCount": null, "allowsPublic": null },
        { "id": "0192e7c5-1a03-7c10-9d21-000000000003", "name": "Licensed", "fileCount": 2, "trashedFileCount": null, "allowsPublic": null }
      ]
    },
    {
      "id": "0192e7c5-1b01-7c10-9d21-000000000004",
      "name": "Campaign",
      "kind": "text",
      "builtin": null,
      "fileCount": 3,
      "trashedFileCount": null,
      "choices": []
    }
  ]
}
```

- The first item is always 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. Set it with the status operation, never through `fields`.
  See [Statuses](statuses.md#setting-a-status-on-files).
- Then come the workspace's or organization folder's own fields in their
  order. Their `builtin` is `null` and their choices' `allowsPublic` is
  `null`.
- The organization folder's list is
  `GET /v1/organizations/{organizationID}/library/file-fields`. Its IDs are
  not those of any workspace's fields, even where the names are the same.
- `choices` is empty for `text`, `number` and `date` fields.

### Set values on one file

Read the file for its `lockVersion`, then send only what should change:

```sh
curl -s -X PATCH "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/$FILE_ID" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedLockVersion": 4,
    "description": "Spring hero shot for the homepage",
    "fields": {
      "0192e7c5-1a01-7c10-9d21-000000000001": "0192e7c5-1a03-7c10-9d21-000000000003",
      "0192e7c5-1b01-7c10-9d21-000000000004": "Spring launch"
    }
  }'
```

The answer is the whole file. The parts this page covers:

```json
{
  "id": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
  "name": "hero.png",
  "lockVersion": 5,
  "altText": null,
  "description": "Spring hero shot for the homepage",
  "caption": null,
  "tags": [{ "id": "0192f0b3-0000-7000-8000-0000000000a1", "name": "spring launch" }],
  "fields": {
    "0192e7c5-1a01-7c10-9d21-000000000001": "0192e7c5-1a03-7c10-9d21-000000000003",
    "0192e7c5-1b01-7c10-9d21-000000000004": "Spring launch"
  }
}
```

- Use the returned `lockVersion` for the next change.
- To clear a value send `null` for its field: `"fields": {"{fieldID}": null}`.
- On `409 STALE_LOCK_VERSION`, read the file again, look at what changed and
  repeat the change with `details.currentLockVersion`.

### Set one field on many files

```json
{
  "name": "workspace_files_fields_set",
  "arguments": {
    "workspaceID": "0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21",
    "fileIDs": [
      "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
      "0192f0b2-7a40-7d22-8b66-3a7e1d2f8c02"
    ],
    "fieldID": "0192e7c5-1a01-7c10-9d21-000000000001",
    "value": "0192e7c5-1a02-7c10-9d21-000000000002"
  }
}
```

```json
{
  "fileIDs": [
    "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
    "0192f0b2-7a40-7d22-8b66-3a7e1d2f8c02"
  ],
  "fieldID": "0192e7c5-1a01-7c10-9d21-000000000001"
}
```

- Over REST this is `POST W/files/fields` with the body `{"fileIDs": [...],
  "fieldID": "...", "value": ...}`.
- `value` is always sent. `null` clears the field on those files.
- For more than 100 files, send several requests. Each is all or nothing by
  itself.

### Filter by a field or a tag

```sh
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files?field=$RIGHTS_ID:$OWNED_ID&sort=name" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

- Files with no "Rights" yet: `field=$RIGHTS_ID:none`. This is the list to
  work through when filling a field in.
- Files with one tag: `tag=$TAG_ID`, with the ID from `GET W/tags`.
- The answer is a page of file summaries with `items` and `nextCursor`.
  Summaries carry `tags` but not `fields`.

### Set, rename and delete tags

A file's tags are replaced as a whole. To add "q3" to a file that has
"spring launch":

```json
{
  "name": "workspace_files_update",
  "arguments": {
    "workspaceID": "0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21",
    "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
    "expectedLockVersion": 5,
    "tags": ["spring launch", "Q3"]
  }
}
```

The file then has the tags "q3" and "spring launch".

`GET W/tags` returns a page of tags by name:

```json
{
  "items": [
    { "id": "0192f0b3-0000-7000-8000-0000000000a2", "name": "q3", "fileCount": 1 },
    { "id": "0192f0b3-0000-7000-8000-0000000000a1", "name": "spring launch", "fileCount": 4 }
  ],
  "nextCursor": null
}
```

- `PATCH W/tags/{tagID}` with `{"name": "..."}` renames the tag on every
  file and answers the tag.
- `DELETE W/tags/{tagID}` removes it from every file and answers `204`.
- More examples, including proposing tags and alt text for review, are in
  [MCP](../agents/mcp.md#describe-alt-text-a-caption-and-tags).

### What the session-only operations take and return

| Operation | Body | Success |
| --- | --- | --- |
| Add a field | `{"name": "...", "kind": "text" \| "number" \| "date" \| "select" \| "multiSelect", "choices": ["..."]}`; `choices` is optional | `201` with the field |
| Rename a field | `{"name": "..."}` | `200` with the field |
| Delete a field | none | `204` |
| Reorder the fields | `{"fieldIDs": ["..."]}` | `200` with the whole list, the status first |
| Add a choice | `{"name": "..."}` | `201` with the field and all its choices |
| Rename a choice | `{"name": "..."}` | `200` with the field |
| Delete a choice | none | `200` with the field without the choice |
| Reorder a field's choices | `{"choiceIDs": ["..."]}` | `200` with the field |

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| A field "Rights" exists and someone adds "rights" | `409 CONFLICT`, reason `NAME_TAKEN`. | Field names are unique in their workspace or organization folder, ignoring case. |
| Two workspaces each add a field "Rights" | Both work. They are two fields with different IDs. | Each workspace and the organization folder has its own fields. |
| A field has the choice "Owned" and someone adds "OWNED" | `409 CONFLICT`, reason `NAME_TAKEN`. | Choice names are unique in their field, ignoring case. |
| Two fields each get a choice "Other" | Both work. | Choice names only need to be unique within one field. |
| A field is created with the choices "A" and "a" | `409 CONFLICT`, reason `NAME_TAKEN`. No field is created. | The two choices collide. |
| A text field is created with choices | `422 VALIDATION_FAILED` on `choices`. | Only select fields have choices. |
| A choice is added to a text, number or date field | `422 VALIDATION_FAILED`. | Only select fields have choices. |
| A field is created with 101 choices, or a 101st choice is added | `422 VALIDATION_FAILED` on `choices`. | A field has at most 100 choices. |
| A 51st field is added to a workspace or the organization folder | `422 VALIDATION_FAILED` on `fields`. The app says "A workspace or the organization folder can have up to 50 custom fields. Delete one to add another." | A workspace, or the organization folder, has at most 50 custom fields. |
| A member tries to add, rename, reorder or delete a field or choice | `403 FORBIDDEN`. Nothing changes. | Only owners and admins of the workspace or the organization folder define its fields. |
| A workspace admin who is a plain member of the organization adds a field to the organization folder | `403 FORBIDDEN`. | The organization folder's fields are managed by the organization's owners and admins. |
| An owner renames a field of workspace A through the address of workspace B | `404 NOT_FOUND`. | A field is managed only through its own workspace or the organization folder. |
| A credential of an owner tries the same | `403 FORBIDDEN`, reason `SESSION_REQUIRED`. | Fields are defined by a person in a browser. |
| A reorder names only some of the fields | `422 VALIDATION_FAILED` on `fieldIDs`. The order stays. | The new order must name every field exactly once. |
| A field is added by one admin while another sends a reorder made before it existed | The reorder is refused with `422`. | It no longer names every field. Load the list again and reorder. |
| A field is deleted twice, for example from two browsers | The second attempt gets `404 NOT_FOUND`. | It is already gone. |
| A field is deleted while files in the trash have a value for it | Those values are deleted too. A restored file comes back without them. | Deleting a field deletes every value of it. |
| A field is deleted while files in the trash also have a value | The app says, for example, "7 files will lose this value, and so will 2 files in the trash." All nine lose it. | The confirmation counts live files (`fileCount`) and the others (`trashedFileCount`) apart. |
| A select choice is deleted | Files that had it have no value for the field. They match `{fieldID}:none`. | A select value is one choice. |
| A multi-select choice is deleted | Files that had it keep their other choices. | Only that choice is removed. |
| A field or choice is renamed | Nothing changes on any file, and no `lockVersion` moves. | Files store IDs, not names. |
| A member has a file open, an admin deletes a field the file had a value for, and the member saves | "This file changed since you opened it." After "Reload latest" the file no longer has that value. | Deleting the field moved the file's `lockVersion`. |
| A member has a file open, an admin deletes a field the file had no value for, and the member sets it and saves | "A field or option changed. Reload and try again." Nothing is saved. | The file did not change, but the field no longer exists (`422` on `fields`). |
| A value is sent for a field of another workspace, of the organization folder, or of another organization | `422 VALIDATION_FAILED` on `fields`. | A file carries only the fields of its own workspace or organization folder. |
| A batch sets an organization folder field on workspace files | `422 VALIDATION_FAILED`. No file changes. | The same rule. |
| `fields` holds the key `status` | `422 VALIDATION_FAILED` on `fields`. | The status has its own operation. |
| A number field is sent `"12"` | `422 VALIDATION_FAILED` on `fields`. | A number field takes a JSON number, not a string. |
| A date field is sent `2026-13-01` or a number | `422 VALIDATION_FAILED` on `fields`. | It takes a real date as `YYYY-MM-DD`. |
| A select field is sent a list with one choice | `422 VALIDATION_FAILED` on `fields`. | A select takes one choice ID, not a list. |
| A multi-select field is sent a single choice ID | `422 VALIDATION_FAILED` on `fields`. | A multi-select takes a list. |
| A select field is sent a choice of another field | `422 VALIDATION_FAILED` on `fields`. | A choice belongs to one field. |
| A multi-select list repeats a choice | It is stored once. | Repeated IDs count once. |
| A text field is sent `"   "`, or a multi-select `[]` | The value is cleared. | Blank text and an empty list mean no value. |
| One request sets three values and one is of the wrong kind | `422`. None of the three is stored, and nothing else in the request is applied. | A change to a file is all or nothing. |
| A request sets a field to the value it already has | It succeeds and the `lockVersion` moves. | Naming a detail counts as a change. |
| A request holds only `expectedLockVersion` | It succeeds, returns the file and moves nothing. | There is nothing to change. |
| Two people save different details of the same file at the same moment | One succeeds. The other gets `409 STALE_LOCK_VERSION` and keeps its typed edits in the app. | Both were based on the same `lockVersion`. |
| A member sets a value on an organization folder file | `403 FORBIDDEN`. | Only owners and admins change organization folder files. |
| A `files:read` credential sets a value | `403 FORBIDDEN`, reason `INSUFFICIENT_SCOPE`. | Setting values needs `files:write`. |
| A value is set on a file in the trash | `409 CONFLICT`, reason `IN_TRASH`. | Restore the file first. A trashed file keeps the values it had. |
| A batch of 100 files holds one trashed file | `409 CONFLICT`, reason `IN_TRASH`. No file changes. | A batch is all or nothing. |
| A batch names a file of another workspace, or one that was deleted for good | `404 NOT_FOUND`. No file changes. | Every file must be a file of this workspace or organization folder. |
| A batch names 101 files, or none | `422 VALIDATION_FAILED` on `fileIDs`. | A batch holds 1 to 100 files. |
| A batch names the same file twice | It counts once. The answer lists it once. | Repeated IDs count once. |
| A batch is sent without `value` | `422 VALIDATION_FAILED`. Nothing is cleared. | Only an explicit `null` clears a value. |
| The app sets a field on 250 selected files and the third batch fails | The first 200 keep the new value. The app says what failed and refreshes the list. | The app sends batches of 100, each all or nothing. |
| A file is replaced with a new version | Its values, tags, description, caption and alt text stay. | They belong to the file, not to a version. |
| `field` names the same field twice with different choices | Files with either choice match. | Entries of one field match any of them. |
| `field` names a choice of another field, an unknown field, a field of another workspace or the organization folder, or has no colon | `422 VALIDATION_FAILED` on `field`. | The filter is checked before the list is read. |
| `field={textFieldID}:none` | Files without a value for the text field. | `none` works for every kind. |
| `field={textFieldID}:{someID}` | `422 VALIDATION_FAILED` on `field`. | A text field has no choices to match. |
| "Brand" and " brand " are sent as two tags | The file gets one tag, "brand". | Tags are normalized, and equal names count once. |
| 51 different tags are sent | `422 VALIDATION_FAILED` on `tags`. The file's tags stay. | A file has at most 50 tags. |
| 60 names are sent that normalize to 40 tags | It works. | The limit counts tags after duplicates are removed. |
| A tag of 51 characters, or an empty one, is sent | `422 VALIDATION_FAILED` on `tags`. | A tag is 1 to 50 characters once normalized. |
| The last file with a tag loses it | The tag stays in the tag list with `fileCount` 0, and in the app's "Tag" filter. | Tags are removed only by deleting them. |
| A tag is renamed to another tag's name | `409 CONFLICT`, reason `NAME_TAKEN`. | A rename never merges two tags. To merge, retag the files and delete the tag that is left over. |
| A tag is renamed to " Launch " | It becomes "launch". | The new name is normalized. |
| A tag "brand" is renamed to "BRAND" | `200`. Nothing changes. | Both normalize to the same name. |
| A tag is deleted and later named on a file again | A new tag with a new ID is created. Filters that used the old ID match nothing. | A deleted tag is gone. |
| A member renames or deletes a tag of their workspace, or a `files:write` key of a member tries it | `403 FORBIDDEN`. The tag stays. | Only owners and admins of the workspace or the organization folder rename and delete its tags. Tagging files stays open to whoever may change them. |
| The tag "logo" is used in two workspaces | They are two tags with different IDs. Renaming or deleting one does not touch the other. | Tags belong to one workspace or the organization folder. |
| `tag` holds the ID of another workspace's tag | The list is empty. | A tag only marks files of its own workspace or organization folder. |
| A tag "red, white" is sent through the API, or a tag is renamed to it | `422 VALIDATION_FAILED` on `tags` (on `name` for a rename): "a tag cannot contain a comma". The file's tags stay. | The comma separates tags in the app, so no tag holds one. Send "red" and "white" as two tags. |
| Text with line breaks is pasted into "Alt text" in the app | The box takes one line, so the line breaks are dropped as the text goes in. | An alt text is a single line. |
| A tab is pasted into "Alt text" in the app | The save is refused, with the message "Remove the tab or other character that cannot be saved." under "Alt text". | Control characters are refused in an alt text (`422` on `altText`). |
| An alt text is set through the API on a PDF | It is stored and returned. The app does not show it. | The app shows "Alt text" for images only. |
| A description of 2,001 characters, or a caption of 501, is sent | `422 VALIDATION_FAILED` on `description` or `caption`. | Their limits. |
| `description` is sent as `" "` or `null` | The description is cleared and reads `null`. | Blank text and `null` clear a detail. |
| A member and an owner read the same field list | They see the same `fileCount`s. Only the owner, in the app, sees `trashedFileCount`. | The counts cover only that workspace's or organization folder's own files. |

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | Not signed in, or an invalid credential. | Sign in or use a valid credential. |
| `FORBIDDEN` | 403 | Someone who is not an owner or admin of the workspace or the organization folder defines its fields or choices, or renames or deletes its tags; a plain member changes values, details or tags of an organization folder file. | Ask an owner or admin of the workspace, or of the organization for the organization folder. |
| `FORBIDDEN`, reason `SESSION_REQUIRED` | 403 | A credential adds, renames, reorders or deletes a field or choice. | A person does this in a browser. |
| `FORBIDDEN`, reason `INSUFFICIENT_SCOPE` | 403 | A credential without `files:read` reads fields, files or tags, or one without `files:write` changes values, details or tags. `details.requiredScopes` names the scope. | Use a credential with that scope. |
| `NOT_FOUND` | 404 | The organization, workspace, file, field, choice or tag is unknown or out of your reach, or a field or choice is managed through another workspace or the organization folder than its own. In a batch: one of the files is. | Check the IDs. Read the field list again. |
| `CONFLICT`, reason `NAME_TAKEN` | 409 | A field name another field has; a choice name another choice of the field has, or two equal choices in one request; a tag renamed to another tag's name. Messages: "Another field has that name", "Another choice has that name", "Two choices have the same name", "That name is already taken here". | Choose another name. |
| `CONFLICT`, reason `IN_TRASH` | 409 | A file in the trash is changed, alone or in a batch. Message: "The file is in the trash; restore it first". | Restore it, or leave it out of the batch. |
| `STALE_LOCK_VERSION` | 409 | The file changed since the `lockVersion` you sent. `details.currentLockVersion` holds the current one. | Read the file again and repeat the change. |
| `VALIDATION_FAILED` on `name` | 422 | A field, choice or tag name that is empty, too long or holds a control character; a tag name with a comma; a choice for a field that is not a select. | Correct the name. |
| `VALIDATION_FAILED` on `fields` | 422 | On adding a field: a 51st field in the workspace or organization folder ("a file space has at most 50 fields"). | Delete a field first. |
| `VALIDATION_FAILED` on `choices` | 422 | Choices for a field that is not a select ("only select fields have choices"); more than 100 ("a field has at most 100 choices"); a choice name that breaks the naming rules. | Correct the choices. |
| `VALIDATION_FAILED` on `fieldIDs` or `choiceIDs` | 422 | A reorder that does not name every field, or every choice of the field, exactly once. | Read the list again and send all of them. |
| `VALIDATION_FAILED` on `fields` | 422 | A key that is not a field ID, including `status`; an unknown field or choice, or one of another workspace, the organization folder or another organization; a value of the wrong kind; a text over 2,000 characters. | Read the field list and send the value its kind takes. |
| `VALIDATION_FAILED` on `fileIDs` | 422 | A batch with no files or more than 100 ("name 1 to 100 files"). | Send 1 to 100 files. |
| `VALIDATION_FAILED` on `field` | 422 | A `field` filter that is malformed, or names an unknown field, a field of another workspace, the organization folder or another organization, or a choice that is not the field's. | Use `{fieldID}:{choiceID}` or `{fieldID}:none`. |
| `VALIDATION_FAILED` on `tags` | 422 | A tag that is empty, over 50 characters or holds a control character ("each tag must be 1 to 50 characters"); a tag with a comma ("a tag cannot contain a comma"); more than 50 tags ("a file has at most 50 tags"). | Correct the list. |
| `VALIDATION_FAILED` on `altText`, `description` or `caption` | 422 | The text is over its limit or holds a control character that is not allowed. | Shorten it. Keep an alt text on one line. |
| `VALIDATION_FAILED` | 422 | The body is not the expected JSON, for example a batch without `value` or a `kind` that is not a kind. | Correct the body. |
| `RATE_LIMITED` | 429 | A credential passed its request limit. | Wait for `Retry-After` seconds. |

See [Errors](../reference/errors.md) for the shape of every error.

## Limits

| What | Value |
| --- | --- |
| Custom fields per workspace or organization folder | Up to 50 |
| Field name | 1 to 60 characters after trimming, no control characters, unique in its workspace or organization folder ignoring case |
| Choices per select or multi-select field | Up to 100 |
| Choice name | 1 to 60 characters after trimming, no control characters, unique in the field ignoring case |
| Text field value | 1 to 2,000 characters after trimming |
| Date field value | One date, `YYYY-MM-DD` |
| Values per file | One per field |
| Files in one field change | 1 to 100 |
| Tags on one file | Up to 50 |
| Tag name | 1 to 50 characters once normalized, no control characters, no comma, unique in its workspace or organization folder |
| Tags per workspace or organization folder | No limit |
| Tags in one `tag` filter | 1 |
| Page size of a tag list | 1 to 100, default 50 |
| Description | Up to 2,000 characters |
| Caption | Up to 500 characters |
| Alt text | Up to 1,000 characters, one line |

All limits are also in [Limits](../reference/limits.md).

## Questions and answers

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

**Who decides which fields exist?**
For a workspace, its owners and admins and the organization's, on the
workspace's "Custom fields" settings page. For the organization folder, the
organization's owners and admins, in **Settings > File spaces > Organization folder > Custom fields**.

**Who can fill fields in?**
Everyone who may change the file: every member of a workspace for its files,
and owners and admins for organization folder files.

**Can each workspace have its own fields?**
Yes. Every workspace and the organization folder has its own fields,
statuses and tags. A field of one cannot be set on files of another, even
with the same name.

**Can I change a field from "Text" to "Single select"?**
No. A field's kind never changes. Create a new field and delete the old one.
The old values are not carried over.

**What happens to the values when I delete a field?**
They are deleted from every file, including files in the trash. This cannot
be undone. The app tells you how many files have a value before you confirm.

**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 keep their other options.

**Does renaming a field or an option change my files?**
No. Files keep their values and show the new name.

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

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

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

**Can I filter by a text, number or date field?**
Not by its content. You can filter for files where it is not set. Text
values are found by search.

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

**Why do my tags turn lower case?**
Tags are normalized so that "Brand" and "brand" are one tag: trimmed, single
spaces, lower case.

**Can a tag contain a comma?**
No. In the app the comma separates tags, and the API refuses a tag that
holds one.

**How do I rename a tag everywhere, or delete it?**
In the app: the workspace's "Tags" settings page, or **Settings >
File spaces > Organization folder > Tags**, then
"Manage {tag}" and "Rename" or "Delete". Through the API or an agent: `PATCH
W/tags/{tagID}` and `DELETE W/tags/{tagID}`, or the tools
`workspace_tags_rename` and `workspace_tags_delete`. Only owners and admins
of the workspace or the organization folder may.

**Why can't I rename or delete a tag?**
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. You can
still add and remove tags on the files you may change.

**How do I merge two tags?**
There is no merge. Give the files of one tag the other tag, then delete the
tag that is left over.

**Why is a tag still offered in the filter when no file has it?**
A tag stays until it is deleted, even with no files.

**Do tags from one workspace show in another, or in the organization folder?**
No. Each workspace and the organization folder has its own tags.

**Why can't I see "Alt text" on my PDF?**
The app shows "Alt text" for images only.

**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, a batch change. Choose "Reload latest". Your
typed edits are kept, and you can save again.

**Do fields, tags and descriptions survive when I replace a file with a new
version?**
Yes. They belong to the file, not to one version.

**Does a file keep its values 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.

**Is the status a custom field?**
No. It is the built-in first field, with its own rules and permissions. It
is listed with the fields so that one call describes everything. See
[Statuses](statuses.md).

**Do field values or tags decide who can open a file?**
No. Only the status and the sharing settings do. See
[Sharing and public links](sharing.md#the-strict-rule).

**Can an agent define fields?**
No. An agent reads the fields and sets values and tags, and renames or
deletes tags when its member is an owner or admin of the workspace or the
organization folder. Fields and choices are defined by a person in a browser.

**How does an agent know which values a field takes?**
`workspace_file_fields_list` (with `workspaceID`) or
`library_file_fields_list` (with `organizationID`) returns every field of
that workspace or the organization folder with its kind and its choices.
Values are sent by choice ID, not by name.

**Can an agent propose tags instead of setting them?**
Yes, as a suggestion that a person applies. A suggestion can add and remove
tags and set an alt text. It cannot set custom fields, descriptions or
captions. See [The organization folder and
suggestions](library-and-suggestions.md#suggestions).

**Are fields and tags in the export?**
Yes: each workspace's and the organization folder's field definitions and
tags, and each file's values, tags and texts. See
[Export](../organizations/export.md#the-manifest).

**Is anyone notified when a field is added or deleted?**
No. The change is recorded in the audit trail.

## Related pages

- [Files & Assets overview](overview.md)
- [Statuses](statuses.md)
- [Folders, moving and finding](organizing.md)
- [The organization folder and suggestions](library-and-suggestions.md)
- [Sharing and public links](sharing.md)
- [Versions and history](versions.md)
- [Trash and restore](trash.md)
- [Export](../organizations/export.md)
- [Credentials and scopes](../agents/credentials.md)
- [MCP](../agents/mcp.md) and [The REST API](../agents/rest-api.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md), [Errors](../reference/errors.md) and
  [Audit trail](../reference/audit-trail.md)

