Talewright Docs Open the app

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.

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.

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.

ActionWhoSessionCredential (scope)
List the fields and their choices of a workspace or the organization folderEveryone who can open itYesYes (files:read)
Add, rename, reorder or delete a field of a workspaceOwner or admin of the workspaceYesNo
Add, rename, reorder or delete a field of the organization folderOrganization owner or adminYesNo
Add, rename, reorder or delete a choice of a fieldThe same as for the fieldYesNo
Read a file's field values, details and tagsEveryone who can open the workspace or the organization folderYesYes (files:read)
Set field values on a workspace fileEvery member of the workspaceYesYes (files:write)
Set field values on an organization folder fileOrganization owner or adminYesYes (files:write)
Set one field on up to 100 files at onceThe same as for one fileYesYes (files:write)
Change a file's description, caption, alt text or tagsThe same as for field valuesYesYes (files:write)
List the tags of a workspace or the organization folderEveryone who can open itYesYes (files:read)
Rename or delete a tag of a workspaceOwner or admin of the workspaceYesYes (files:write)
Rename or delete a tag of the organization folderOrganization owner or adminYesYes (files:write)
Filter a file list by field or tagEveryone who can open itYesYes (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.

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.

KindIn the appHoldsIn 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.
  • 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

KindAcceptedRefusedClears the value
textA 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
numberA JSON number, whole or with decimals.A string, also one that holds digits, such as "12".null
dateA string YYYY-MM-DD that is a real date.A date that does not exist, such as 2026-13-01. A number.null
selectThe ID of one choice of that field, as a string.A list. The ID of a choice of another field. An unknown ID.null
multiSelectA 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.
  • 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.
  • 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":

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

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.

DetailPropertyLengthLine breaksFor
DescriptiondescriptionUp to 2,000 charactersAllowedWhat the file is and how to use it.
CaptioncaptionUp to 500 charactersAllowedA line to show with the file.
Alt textaltTextUp to 1,000 charactersRefusedA 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.
  • The file's name is the fourth detail in the same form. Its rules are in Folders, moving and finding.

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

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.

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.

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

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

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

The settings page "Tags" of a workspace or the organization folder lists its tags. See 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.

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.

OperationCapability IDMCP toolScope
GET W/file-fieldsworkspace.file_fields.list, library.file_fields.listworkspace_file_fields_list, library_file_fields_listfiles:read
GET W/files/{fileID}workspace.files.get, library.files.getworkspace_files_get, library_files_getfiles:read
PATCH W/files/{fileID}workspace.files.update, library.files.updateworkspace_files_update, library_files_updatefiles:write
POST W/files/fieldsworkspace.files.fields.set, library.files.fields.setworkspace_files_fields_set, library_files_fields_setfiles:write
GET W/files?field=...&tag=...workspace.files.search, library.files.searchworkspace_files_search, library_files_searchfiles:read
GET W/tagsworkspace.tags.list, library.tags.listworkspace_tags_list, library_tags_listfiles:read
PATCH W/tags/{tagID}workspace.tags.rename, library.tags.renameworkspace_tags_rename, library_tags_renamefiles:write
DELETE W/tags/{tagID}workspace.tags.delete, library.tags.deleteworkspace_tags_delete, library_tags_deletefiles:write
POST W/file-fieldsworkspace.file_fields.create, library.file_fields.createnonesession only
PATCH W/file-fields/{fieldID}workspace.file_fields.update, library.file_fields.updatenonesession only
DELETE W/file-fields/{fieldID}workspace.file_fields.delete, library.file_fields.deletenonesession only
PUT W/file-fields/orderworkspace.file_fields.reorder, library.file_fields.reordernonesession only
POST W/file-fields/{fieldID}/choicesworkspace.file_fields.choices.create, library.file_fields.choices.createnonesession only
PATCH W/file-fields/{fieldID}/choices/{choiceID}workspace.file_fields.choices.update, library.file_fields.choices.updatenonesession only
DELETE W/file-fields/{fieldID}/choices/{choiceID}workspace.file_fields.choices.delete, library.file_fields.choices.deletenonesession only
PUT W/file-fields/{fieldID}/choices/orderworkspace.file_fields.choices.reorder, library.file_fields.choices.reordernonesession 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:

curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/file-fields" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
{
  "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.
  • 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:

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:

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

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

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

{
  "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:

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

What the session-only operations take and return

OperationBodySuccess
Add a field{"name": "...", "kind": "text" | "number" | "date" | "select" | "multiSelect", "choices": ["..."]}; choices is optional201 with the field
Rename a field{"name": "..."}200 with the field
Delete a fieldnone204
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 choicenone200 with the field without the choice
Reorder a field's choices{"choiceIDs": ["..."]}200 with the field

Edge cases

SituationWhat happensWhy
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 choices422 VALIDATION_FAILED on choices.Only select fields have choices.
A choice is added to a text, number or date field422 VALIDATION_FAILED.Only select fields have choices.
A field is created with 101 choices, or a 101st choice is added422 VALIDATION_FAILED on choices.A field has at most 100 choices.
A 51st field is added to a workspace or the organization folder422 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 choice403 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 folder403 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 B404 NOT_FOUND.A field is managed only through its own workspace or the organization folder.
A credential of an owner tries the same403 FORBIDDEN, reason SESSION_REQUIRED.Fields are defined by a person in a browser.
A reorder names only some of the fields422 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 existedThe 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 browsersThe second attempt gets 404 NOT_FOUND.It is already gone.
A field is deleted while files in the trash have a value for itThose 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 valueThe 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 deletedFiles that had it have no value for the field. They match {fieldID}:none.A select value is one choice.
A multi-select choice is deletedFiles that had it keep their other choices.Only that choice is removed.
A field or choice is renamedNothing 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 organization422 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 files422 VALIDATION_FAILED. No file changes.The same rule.
fields holds the key status422 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 number422 VALIDATION_FAILED on fields.It takes a real date as YYYY-MM-DD.
A select field is sent a list with one choice422 VALIDATION_FAILED on fields.A select takes one choice ID, not a list.
A multi-select field is sent a single choice ID422 VALIDATION_FAILED on fields.A multi-select takes a list.
A select field is sent a choice of another field422 VALIDATION_FAILED on fields.A choice belongs to one field.
A multi-select list repeats a choiceIt 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 kind422. 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 hasIt succeeds and the lockVersion moves.Naming a detail counts as a change.
A request holds only expectedLockVersionIt succeeds, returns the file and moves nothing.There is nothing to change.
Two people save different details of the same file at the same momentOne 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 file403 FORBIDDEN.Only owners and admins change organization folder files.
A files:read credential sets a value403 FORBIDDEN, reason INSUFFICIENT_SCOPE.Setting values needs files:write.
A value is set on a file in the trash409 CONFLICT, reason IN_TRASH.Restore the file first. A trashed file keeps the values it had.
A batch of 100 files holds one trashed file409 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 good404 NOT_FOUND. No file changes.Every file must be a file of this workspace or organization folder.
A batch names 101 files, or none422 VALIDATION_FAILED on fileIDs.A batch holds 1 to 100 files.
A batch names the same file twiceIt counts once. The answer lists it once.Repeated IDs count once.
A batch is sent without value422 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 failsThe 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 versionIts 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 choicesFiles 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 colon422 VALIDATION_FAILED on field.The filter is checked before the list is read.
field={textFieldID}:noneFiles 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 tagsThe file gets one tag, "brand".Tags are normalized, and equal names count once.
51 different tags are sent422 VALIDATION_FAILED on tags. The file's tags stay.A file has at most 50 tags.
60 names are sent that normalize to 40 tagsIt works.The limit counts tags after duplicates are removed.
A tag of 51 characters, or an empty one, is sent422 VALIDATION_FAILED on tags.A tag is 1 to 50 characters once normalized.
The last file with a tag loses itThe 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 name409 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 againA 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 it403 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 workspacesThey 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 tagThe 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 it422 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 appThe 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 appThe 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 PDFIt 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 sent422 VALIDATION_FAILED on description or caption.Their limits.
description is sent as " " or nullThe description is cleared and reads null.Blank text and null clear a detail.
A member and an owner read the same field listThey see the same fileCounts. Only the owner, in the app, sees trashedFileCount.The counts cover only that workspace's or organization folder's own files.

Errors

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in, or an invalid credential.Sign in or use a valid credential.
FORBIDDEN403Someone 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_REQUIRED403A credential adds, renames, reorders or deletes a field or choice.A person does this in a browser.
FORBIDDEN, reason INSUFFICIENT_SCOPE403A 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_FOUND404The 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_TAKEN409A 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_TRASH409A 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_VERSION409The file changed since the lockVersion you sent. details.currentLockVersion holds the current one.Read the file again and repeat the change.
VALIDATION_FAILED on name422A 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 fields422On 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 choices422Choices 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 choiceIDs422A 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 fields422A 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 fileIDs422A batch with no files or more than 100 ("name 1 to 100 files").Send 1 to 100 files.
VALIDATION_FAILED on field422A 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 tags422A 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 caption422The text is over its limit or holds a control character that is not allowed.Shorten it. Keep an alt text on one line.
VALIDATION_FAILED422The body is not the expected JSON, for example a batch without value or a kind that is not a kind.Correct the body.
RATE_LIMITED429A credential passed its request limit.Wait for Retry-After seconds.

See Errors for the shape of every error.

Limits

WhatValue
Custom fields per workspace or organization folderUp to 50
Field name1 to 60 characters after trimming, no control characters, unique in its workspace or organization folder ignoring case
Choices per select or multi-select fieldUp to 100
Choice name1 to 60 characters after trimming, no control characters, unique in the field ignoring case
Text field value1 to 2,000 characters after trimming
Date field valueOne date, YYYY-MM-DD
Values per fileOne per field
Files in one field change1 to 100
Tags on one fileUp to 50
Tag name1 to 50 characters once normalized, no control characters, no comma, unique in its workspace or organization folder
Tags per workspace or organization folderNo limit
Tags in one tag filter1
Page size of a tag list1 to 100, default 50
DescriptionUp to 2,000 characters
CaptionUp to 500 characters
Alt textUp to 1,000 characters, one line

All limits are also in Limits.

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.

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.

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.

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.

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