# Folders, moving and finding

## Summary

This page covers how files are kept in order and found again: folders,
moving files and folders, renaming, a file's details (name, description,
caption, alt text and tags), favorites, search, filters and sorting.

Every workspace has its own folders, and so does the organization
folder. Folders nest, files sit in one folder or at the top
level, and everything can be moved within its own workspace or organization
folder.

Two rules run through the whole page:

- **A move can change who can open a file.** Moving a file into a public
  folder can make it public, and moving it out can stop its public link.
  Such a move is never done silently, and only owners and admins can make
  files public this way.
- **Changes are checked against what you last saw.** If someone else changed
  a file or folder after you opened it, your change is refused instead of
  overwriting theirs.

## Who can do what

`W` stands for `/v1/workspaces/{workspaceID}` and `L` for
`/v1/organizations/{organizationID}/library`, the organization folder (the
API's library).

| Action | In a workspace | In the organization folder | Session | Credential (scope) |
| --- | --- | --- | --- | --- |
| List folders, list and search files, read a file | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Create a folder | Every member of the workspace | Owners and admins | Yes | Yes (`files:write`) |
| Rename a folder | Every member of the workspace | Owners and admins | Yes | Yes (`files:write`) |
| Move a folder | Every member of the workspace | Owners and admins | Yes | Yes (`files:write`) |
| Rename a file, change its description, caption, alt text or tags | Every member of the workspace | Owners and admins | Yes | Yes (`files:write`) |
| Move a file | Every member of the workspace | Owners and admins | Yes | Yes (`files:write`) |
| A move that makes files public | Owners and admins | Owners and admins | Yes, after confirming | Yes (`files:write` and `files:approve`), after confirming |
| A move that only stops public links | Every member of the workspace | Owners and admins | Yes, after confirming | Yes (`files:write`), after confirming |
| List tags | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Rename or delete a tag everywhere | Owners and admins of the workspace | Owners and admins | Yes | Yes (`files:write`) |
| List, add, reorder and remove your own favorites | Every member of the workspace | Every member of the organization | Yes | Yes (`files:read`) |

- "Member of the workspace" includes organization owners and admins, who
  reach every workspace. In a workspace the role that counts is the
  effective workspace role. In the organization folder it is the
  organization role.
- A credential must list the workspace. It reaches the organization folder
  of its own organization.
- Through a credential, a move that makes files public also needs the
  member's email to be verified.
- Statuses, general access and public links have their own rules. See
  [Statuses](statuses.md) and [Sharing and public links](sharing.md).
- The full matrix is in
  [Roles and permissions](../reference/permissions.md#files-in-a-workspace).

## How it works

### Folders

- Each workspace has one tree of folders. The organization folder has its own.
- A folder belongs to exactly one workspace or to the organization folder.
  It cannot be moved to another.
- A folder holds files and other folders.
- A file sits in exactly one folder, or at the top level, which is no
  folder at all.
- A folder knows how many folders (`folderCount`) and how many live files
  (`fileCount`) are directly inside it. Files in subfolders are not
  counted.
- Folders are listed by name.
- An empty folder is allowed and stays until someone moves it to the trash.

### Folder names

- A folder name is 1 to 200 characters long.
- Spaces at the start and end are removed before the name is measured and
  stored.
- A name that is empty after trimming is refused.
- A name must not contain `/`.
- A name must not contain a control character, such as a tab or a line
  break.
- A folder name is unique among the folders in the same place, ignoring
  case. "Brand" and "bRAND" cannot both sit in one folder.
- Only live folders count. The name of a trashed folder is free at once.
- Folders in different places can have the same name.
- Creating, renaming or moving a folder so that two siblings would share a
  name answers `409 CONFLICT` with `details.reason` `NAME_TAKEN` and the
  message "That name is already taken here".

### How deep folders nest

- Folders nest at most 16 levels deep. A folder at the top level is level 1.
- Creating a folder at level 17 answers `422 VALIDATION_FAILED` on
  `parentID` with the message "folders nest at most 16 levels deep".
- Moving a folder counts the folders inside it. A folder with three levels
  below it cannot be moved into a folder at level 14.
- Files do not count as a level. A file can sit in a folder at level 16.

### Creating a folder

- A folder needs a name. `parentID` names the folder it goes into; left
  out, it goes to the top level.
- The parent must be a live folder of the same workspace or organization folder.
  Otherwise the answer is `422 VALIDATION_FAILED` on `parentID`.
- A new folder is empty, is restricted, and has `lockVersion` 1.
- With a `requestID`, repeating the same request within 24 hours returns the
  folder the first request made. A workspace and the organization folder
  keep their request IDs apart. See [Safe
  retries](../agents/rest-api.md#safe-retries-with-requestid).

### Renaming a folder

- A rename changes the name and nothing else: the folder's ID, its content,
  its place and its general access stay.
- A public folder's gallery link keeps working after a rename.
- A rename needs the folder's current `lockVersion`. See
  [Lock versions](#lock-versions).
- A trashed folder cannot be renamed: `409 CONFLICT`, reason `IN_TRASH`.

### Moving a folder

- A folder moves with everything inside it.
- `parentID` names the new parent. `null` moves the folder to the top
  level.
- A folder moves only within its own workspace or organization folder.
- A folder cannot be moved into itself or into a folder below it. That
  answers `409 CONFLICT` with reason `CYCLE` and the message "A folder
  cannot move into itself or its subfolders".
- The destination must be a live folder here: otherwise `422
  VALIDATION_FAILED` on `parentID`.
- The move must respect the depth limit and the naming rule at the
  destination.
- A rename and a move can be sent together in one request.
- A trashed folder cannot be moved.
- Two moves at the same moment can never build a loop together. They are
  handled one after the other.

### Moving a file

- `folderID` names the folder the file moves to. `null` moves it to the
  top level.
- A file moves only within its own workspace or organization folder.
- The destination must be a live folder here: otherwise `422
  VALIDATION_FAILED` on `folderID`.
- A move keeps everything else: the file's ID, name, versions, status,
  details, tags and its own general access.
- File names need not be unique, so a move never fails because of a name.
- A trashed file cannot be moved: `409 CONFLICT`, reason `IN_TRASH`.
- A move needs the file's current `lockVersion`, and moves it on by one.

### Moves that change who can open files

A folder can be public: its general access is "Anyone with the link". Every
file in a public folder, or in a folder below it, that has a status allowing
public use is then public too. See
[Sharing and public links](sharing.md). So a move can change who can open a
file:

- A file moved into a public folder becomes public, if its status allows
  public use.
- A file moved out of a public folder loses the public link the folder gave
  it. A file that is public by its own general access keeps its link
  wherever it goes.
- A folder moved under a public folder makes the eligible files inside it
  public. A folder moved out from under one stops those links.

The rules for such a move:

- **Nothing changes without a confirmation.** A move that would start or
  stop a public link answers `409 CONFLICT` with reason
  `VISIBILITY_CHANGE` and changes nothing. `details` holds:
  - `becomePublic`: how many files would become public,
  - `stopPublic`: how many public links would stop,
  - `publicVia`: `{id, name}` of the public folder that shares the
    destination, or `null`.
- Sending the same request again with `confirmVisibilityChange: true`
  applies the move.
- **Only owners and admins make files public by a move.** A member's move
  that would make any file public is refused with `403 FORBIDDEN`, reason
  `MAKES_FILES_PUBLIC`. `details.becomePublic` counts the files. The
  refusal comes whether or not the request confirmed, and nothing is moved.
- **Stopping links needs only the confirmation.** Any member who may move
  the item may confirm a move that only stops public links.
- **A move that changes nothing about access needs no confirmation.** A file
  whose status does not allow public use can be moved into a public folder
  by anyone who may move it: it stays restricted.
- A move that both makes some files public and stops other links follows
  the stricter rule: it needs an owner or admin, and the confirmation.

Through a credential:

- A move that would make files public needs the scope `files:approve` in
  addition to `files:write`. Without it the answer is `403 FORBIDDEN` with
  reason `INSUFFICIENT_SCOPE` and `details.requiredScopes`
  `["files:approve"]`.
- The credential's member must be an owner or admin. A credential that
  holds `files:approve` for a plain member is refused with
  `MAKES_FILES_PUBLIC`.
- The member's email must be verified: otherwise `403 EMAIL_NOT_VERIFIED`.
- The confirmation is still needed.
- A move that only stops links needs `files:write` and the confirmation.

What each caller gets for a move that would make one file public:

| Caller | Without `confirmVisibilityChange` | With `confirmVisibilityChange: true` |
| --- | --- | --- |
| Member, in a browser | `403 FORBIDDEN` `MAKES_FILES_PUBLIC` | `403 FORBIDDEN` `MAKES_FILES_PUBLIC` |
| Owner or admin, in a browser | `409 CONFLICT` `VISIBILITY_CHANGE` | Moved. The file is public. |
| Credential with `files:write` only | `403 FORBIDDEN` `INSUFFICIENT_SCOPE` | `403 FORBIDDEN` `INSUFFICIENT_SCOPE` |
| Credential with `files:approve`, acting for a member | `403 FORBIDDEN` `MAKES_FILES_PUBLIC` | `403 FORBIDDEN` `MAKES_FILES_PUBLIC` |
| Credential with `files:approve`, acting for an owner or admin | `409 CONFLICT` `VISIBILITY_CHANGE` | Moved. The file is public. |

In every refused case the file or folder stays where it was.

### File names

- A file name is 1 to 200 characters long, after spaces at the start and
  end are removed.
- A name must not contain a control character.
- A name must not contain `/` or `\`. A file goes into a folder by its
  `folderID`, never by its name. Any other character is allowed.
- The rule holds wherever a name is set: an upload, a rename and a
  suggestion that renames. Only a name being set is checked: a file whose
  name holds `/` or `\` keeps it, and everything else about the file can
  still be changed.
- File names need not be unique. Two files in one folder can have the same
  name.
- The name includes the extension, and renaming can change it. The
  extension of the name does not change the file's type: the type comes
  from the bytes of the current version.
- A rename keeps the file's ID, its versions and its links. A public link
  keeps working under the new name, and old addresses with the old name in
  them keep working too.
- A trashed file cannot be renamed.

### Details: description, caption, alt text

| Detail | Rule |
| --- | --- |
| Description | Up to 2,000 characters. Line breaks are allowed. |
| Caption | Up to 500 characters. Line breaks are allowed. |
| Alt text | Up to 1,000 characters. No line breaks or other control characters. |

- Each is optional and starts empty.
- Spaces at the start and end are removed.
- Sending `null` or blank text clears a detail.
- A detail you leave out of a request stays as it is.
- All three are searchable.
- Over the API, alt text can be set on any file. The app offers the field
  for images only.

### Tags

- A tag is a short label on files. Tags belong to one workspace or to the
  organization folder.
- A file has at most 50 tags.
- A tag name is 1 to 50 characters after it is normalized: trimmed, runs of
  spaces made one, lower case. "Brand", " brand " and "BRAND" are the same
  tag, `brand`.
- A tag name must not contain a control character.
- A tag holds no comma. A tag with one answers `422 VALIDATION_FAILED` with
  the message "a tag cannot contain a comma": on `tags` when it is set on a
  file or named in an `add_tag` or `remove_tag` item of a suggestion, on
  `name` when a tag is renamed to it. In the app a comma separates tags, so
  none can be typed into one.
- A tag is created by naming it on a file. There is no separate step.
- A file's tags are sent as the complete list. Tags you leave out are
  removed from the file. Naming the same tag twice counts once.
- Renaming a tag changes it on every file that carries it. Renaming it to a
  name another tag has answers `409 CONFLICT`, reason `NAME_TAKEN`.
- Deleting a tag removes it from every file.
- Renaming and deleting a tag need an owner or admin: of the workspace or
  the organization for a workspace's tag, of the organization for the
  organization folder's. A plain member gets `403 FORBIDDEN`. Tagging a file
  stays with whoever may change the file. In the app, tags are renamed and
  deleted on the settings page "Tags" of the workspace or the organization
  folder.
- Renaming or deleting a tag moves the `lockVersion` of every file that
  carried it.
- The tag list shows each tag with the number of live files that carry it.
- More about tags is in [Fields and tags](fields-and-tags.md).

### Lock versions

Every file and every folder has a `lockVersion`, a number that moves each
time it changes. It protects against overwriting someone else's work.

- Every change to a file's details or place, and every trash, sends
  `expectedLockVersion`: the `lockVersion` you last read.
- If it is still current, the change is applied and `lockVersion` goes up
  by one.
- If it is not, the answer is `409 STALE_LOCK_VERSION` with
  `details.currentLockVersion`, and nothing changes. Read the item again,
  look at what changed, and send your change with the new number.
- A file's `lockVersion` moves when its name, description, caption, alt
  text, tags, folder or field values change, when it is trashed or
  restored, when a tag it carries is renamed or deleted, and when a field
  or choice it had a value for is deleted.
- A file's `lockVersion` does not move when the file gets a new version.
  Replacing a file has its own check. See
  [Versions and history](versions.md).
- A folder's `lockVersion` moves when it is renamed, moved, trashed or
  restored.
- A request that names nothing to change succeeds and leaves `lockVersion`
  as it is.
- A request that sets a value to what it already is counts as a change.
- More in [The REST API](../agents/rest-api.md#lock-versions).

### Favorites

- A favorite is a star you put on a file or a folder, for yourself.
- Favorites are private. Nobody else sees or changes yours, admins
  included.
- Favorites are kept per workspace and for the organization folder separately.
- Anyone who can read a workspace or the organization folder can star what
  is in it. A member who cannot change the organization folder can still
  star its files.
- A new favorite goes to the end of your list.
- Starring something you already starred changes nothing and returns the
  existing favorite.
- Only a live file or folder of that workspace or organization folder can be
  starred. Anything else answers `404 NOT_FOUND`.
- A favorite follows its target: it shows the target's current name, and a
  folder favorite carries the folders above it.
- A favorite of a trashed file or folder is hidden. It comes back when the
  target is restored.
- When the target is deleted for good, the favorite is gone for good.
- You can reorder your favorites by sending all of them in the new order.
- Removing a favorite does nothing to the file or folder.

### Listing files

A listing returns files of one workspace or of the organization folder, 50 a
page (1 to 100 with `limit`), with a `nextCursor` while there are more.

Where to look:

| Parameter | Lists |
| --- | --- |
| none | Every live file, in every folder. |
| `folderID` | Files directly in that folder. |
| `root=true` | Files at the top level. |
| `under` | Files in that folder and in every live folder below it. |

- Only one of `folderID`, `root` and `under` can be used at a time. Two of
  them answer `422 VALIDATION_FAILED`.
- Every listed file carries `folderPath`: the folders from the top level
  down to its own folder, each with `id` and `name`. It is empty for a file
  at the top level.
- Trashed files are never listed here. `trash=true` lists them instead. See
  [Trash and restore](trash.md).

### Search

- `q` holds the words to look for.
- The words are matched in a file's name, description, caption, alt text,
  tags and the values of text fields.
- Every word must match. "spring poster" finds files that have both.
- A word matches from the start of a word: "quart" finds "quarterly".
  It does not match in the middle: "port" does not find "report".
- Upper and lower case do not matter.
- Punctuation separates words, in what you type and in file names:
  `prometheus-future-city.jpg` is found by "future", by "city" and by
  "jpg".
- The first 10 words of a query count. Further words are ignored.
- A query without any letter or digit filters nothing.
- Search does not look inside files. It does not match folder names,
  status names, or the values of number, date and select fields.
- Search looks through the whole workspace or organization folder, unless
  you also name a folder.
- Search does not reorder the results. They come in the order of the chosen
  sort.
- A change is searchable at once.

### Filters

| Parameter | Keeps |
| --- | --- |
| `type` | Files whose current version is of that kind: `image`, `video`, `font`, `pdf`, `design` or `other`. |
| `status` | Files with that status ID, or `none` for files without a status. |
| `field` | Files with those field values: `{fieldID}:{choiceID}` for a choice, `{fieldID}:none` for no value. Several entries are separated by commas. |
| `tag` | Files that carry the tag with that ID. |
| `duplicates=true` | Files whose bytes are the same as another live file's in the same workspace or organization folder. |

- Filters combine: a file must pass every one of them, and the search too.
- `type` goes by the current version:
  - `image`: JPEG, PNG, GIF, WebP, AVIF, SVG, ICO, HEIC, HEIF, Photoshop
    and raw photos,
  - `video`: MP4, WebM and QuickTime,
  - `font`: WOFF, WOFF2, TrueType and OpenType,
  - `pdf`: PDF,
  - `design`: Illustrator, EPS, InDesign and Figma,
  - `other`: CSV, Word, Excel, Markdown and text.
- In `field`, entries of the same field match any of them, and every field
  named must match. A field or choice of another workspace, of the
  organization folder under a workspace, or of another organization answers
  `422 VALIDATION_FAILED`: each workspace and the organization folder has
  its own fields.
- A tag ID of another workspace filters everything out. It is not an error.
- `duplicates` compares current versions only, within one workspace or the
  organization folder, and ignores trashed files.

### Sorting

- `sort=updated` is the default: most recently updated first.
- `sort=name` orders by name, the way a person would: upper and lower case
  are sorted together.
- A file's "updated" time moves when its details or place change, when it
  gets a new version and when it is trashed or restored.
- There is no descending-by-name or oldest-first order.
- Folders are always listed by name.

## In the app

### Getting around

Files & Assets has its own navigation beside the listing:

- "All files" opens the top level of the open workspace or organization folder.
- "Suggestions" and "Trash" are described in
  [The organization folder and suggestions](library-and-suggestions.md) and
  [Trash and restore](trash.md).
- "Favorites" lists your starred files and folders. It reads "No favorites
  yet" while you have none.
- "Folders" is a tree. Its root is the organization, which is the folder
  shared across the organization: below it come your workspaces of that
  organization as workspace folders, each with its folders, and then the
  organization folder's own folders.
  - A folder shows the number of files directly in it.
  - Clicking the arrow opens or closes a folder in the tree. Clicking the
    name opens it in the listing. Clicking the organization's name opens
    the organization folder.
  - The arrow keys move through the tree. Right and Left open and close a
    folder. Enter or Space opens it in the listing, or closes or opens the
    organization.
  - The tree is how you get from one workspace to another and to the
    organization folder.
- On a narrow window the navigation becomes a row, and "Folders" opens the
  favorites and the tree in a panel that closes when you open a folder.

Above the listing, the breadcrumb "Folder path" shows where you are: "Files
& Assets", then the workspace's name, then the folders. In the organization
folder it reads "Files & Assets", the organization's name, "Organization
folder", then the folders; the organization's name is not a link.

- When more than one folder lies between, the older ones fold into a "..."
  menu.
- The last crumb is the open folder. It is a button, "Folder actions for
  {name}", that opens the folder's menu.
- A folder's address holds the folders above it. When the folder, or one
  above it, was moved since, the app finds the folder where it is now,
  opens it and corrects the address.
- If the folder in the address is in the trash or was deleted, the app says
  "This folder was deleted." with the link "Go to the top level".

### Grid and list

The view switch has "Grid view" and "List view". The grid is the default.

- **Grid.** Folders come first as small cards with their counts, such as
  "2 folders, 14 files". Files follow as tiles with a thumbnail or a type
  icon and two lines: the name, then the status and the size, such as
  "Approved for public use · 2.4 MB". A colored dot leads the status: green
  when it allows public use, amber when it does not. A file without a
  status shows only its size, and a long status name is cut short before
  the size is. The tile does not name the file's type.
- **List.** One row per item, with the columns "Name", "Status", "Size" and
  "Modified". Clicking "Name" or "Modified" sorts by it. A file's row also
  shows its tags. Hovering the modified time shows "Updated by {name}".
- Both show a file's status, as a badge in the list and in the tile's
  second line in the grid, and "Public" or "Public via folder" when anyone
  with the link can open it. On a tile that badge sits on the thumbnail.
- Folders always come before files.
- 50 files are shown at first. "Load more" shows the next 50.
- The view, the sort, the filters and the search are part of the page's
  address. A copied address opens the same view.

Empty listings say why they are empty:

| Text | When |
| --- | --- |
| "No files yet. Upload files to start." | The top level is empty and you may upload. |
| "No files yet." | The top level is empty and you may not upload. |
| "This folder is empty." | The open folder holds nothing. |
| "No files match." | A search, status, field or tag filter matches nothing. |
| "No images here.", "No videos here.", "No PDFs here.", "No fonts here.", "No design files here." | A type filter matches nothing. |
| "No duplicates here." | The duplicates filter matches nothing. |

"Clear search and filters" is offered under "No files match." and "No
duplicates here." It empties the search and turns every filter off. It
keeps the open folder, the sort and the view.

### Searching

- Type into "Search files". The results appear a moment after you stop
  typing, or at once when you press Enter.
- Search looks through every folder of the open workspace or organization
  folder, not only the open folder. The line "Showing matches from every
  folder." says so.
- Results list files only, not folders. Each result says where it is: "In
  {folder} / {subfolder}".
- "Clear search" empties the box.

### Filtering and sorting

The "Filter" menu has these groups:

| Group | Choices |
| --- | --- |
| "Type" | "All types", "Images", "Videos", "PDFs", "Fonts", "Design" |
| "Status" | "All statuses", "No status", then each status of the open workspace or organization folder |
| One group per select or multi-select field of the open workspace or organization folder | "Any", "Not set", then the field's choices |
| "Show" | "All files", "Duplicates" |
| "Tag" | "All tags", then each tag. Shown when there is at least one tag. |

- The button shows how many filters are on, and reads "Filter, {n} on" to
  screen readers.
- "Clear filters" turns them all off. It keeps the search and the sort.
- The app has no filter for the API's `other` type. An address that names
  it opens the listing unfiltered.
- A type filter alone looks through the open folder and every folder below
  it.
- Search, status, field, tag and duplicates look through the whole
  workspace or organization folder.
- While any filter or a search is on, folders are hidden and each file
  says which folder it is in.

The "Sort" menu has "Recently updated", the default, and "Name". Sorting
orders files. Folders stay first, by name.

### The menu of a file or folder

Every row has a menu, from its "File actions for {name}" or "Folder actions
for {name}" button or a right-click. The folders of the open workspace in
the tree have the same menu on right-click.

| Item | Who sees it |
| --- | --- |
| "Open" | Everyone |
| "Download" | Everyone. See [Downloading](downloading.md). |
| "Share" | Everyone. See [Sharing and public links](sharing.md). |
| "Make public" or "Make restricted" | Owners and admins |
| "Copy link" | Everyone |
| "Rename" | Whoever may change the item |
| "Move" | Whoever may change the item |
| "Move to parent folder" | Whoever may change the item, when it is inside a folder |
| "Set status" | Owners and admins. See [Statuses](statuses.md). |
| "Add to favorites" or "Remove from favorites" | Everyone |
| "Move to trash" | Whoever may change the item. See [Trash and restore](trash.md). |

- "Whoever may change the item" is every member in a workspace, and owners
  and admins in the organization folder.
- "Copy link" copies the address of the file's page in the app. For a
  public folder it copies the folder's gallery link. The app confirms with
  "Copied the link".

### Selecting several items

Where you may change files, every row has a checkbox, "Select {name}".

- A folder's row in the list view always shows its checkbox. A folder's
  card and a file show theirs when you point at them or reach them with the
  Tab key; on a card the folder's icon turns into the checkbox. On a touch
  screen every checkbox shows. Once something is selected, every item shows
  its checkbox.
- Shift-click selects everything between the last item you picked and this
  one.
- Cmd+A on a Mac, or Ctrl+A elsewhere, selects everything shown. The
  command palette offers the same as "Select all".
- Escape clears the selection.
- A bar appears at the bottom of the listing with "Select all", "{n}
  selected" and the actions "Download", "Move", "Set status", "Set field",
  "Move to trash" and "Clear selection". It floats over the listing, so
  the rows do not move.
- "Select all" in the bar selects everything shown. It is a checkbox: a
  dash while only some rows are selected, a tick once all are. Unticking it
  clears the selection.
- When everything shown is selected and there is more, the app says "All
  {count} on this page are selected." above the bar and offers "Select
  everything here".
- "Select everything here" selects up to 1,000 more files each time. When
  more remain, the app says "{count} selected so far. Choose "Select
  everything here" again to add the rest." and keeps the offer.
- The selection is cleared when you open another folder or change the
  search, a filter or the sort.

### Creating a folder

1. Choose "New folder": the button at the top, the icon beside "Folders",
   a right-click on empty space, or the command palette.
2. The dialog "New folder" has the field "Name" and the button "Create
   folder".
3. The folder is created in the folder you have open, or at the top level.
   The app says "Created folder {name}".

- A blank name shows "Enter a name of 1 to 200 characters without a slash."
- A name another folder there has shows `A folder named "{name}" already
  exists here. Choose another name.`
- At the depth limit the dialog shows "Folders nest at most 16 levels
  deep."

### Renaming

- **A folder.** Choose "Rename" in its menu. The dialog "Rename folder" has
  "Name", filled in, and the button "Rename". An open folder can also be
  renamed in the Details pane, in the form "Folder name".
- **A file.** Choose "Rename" in its menu or press R with one item
  selected. The dialog "Rename file" has "Name" and "Rename". A blank name
  shows "Enter a name of 1 to 200 characters." A file can also be renamed
  on its page, in the section "Details".
- The same messages as for creating a folder apply to folder names.

### Moving

There are four ways to move things. All end the same way.

- **The Move dialog.** Choose "Move" in a menu or in the selection bar, or
  press M. The dialog "Move {name}", or "Move 3 files" for several, says
  "Open the folder to move to, then choose Move here."
  - It shows the folders of the same workspace or organization folder. Click
    one to open it; "Parent folder" goes back up.
  - A folder that is being moved is disabled, as "{name} (being moved)".
  - "Move here" moves the items into the folder you have open in the
    dialog. It is disabled where the items already are.
  - "No subfolders here." is shown in a folder without folders.
- **Drag and drop.** Drag a row onto a folder's row, onto a folder in the
  tree, or onto a crumb of the breadcrumb. Dragging a selected row drags the
  whole selection, with the number of items shown beside the pointer.
  Dropping onto a workspace or "Organization folder" in the tree moves to
  that top level, but only within the same workspace or organization folder.
  The organization at the tree's root takes no drops.
- **"Move to parent folder"** in an item's menu moves it one level up.
- **"Details".** Beside a listing and on a file's page, "Location" shows
  where an item is, with "Move".

After a move the app says "Moved {name} to {destination}" with "Undo".

- "Undo" is offered for 8 seconds, and Cmd+Z or Ctrl+Z does the same.
- Undo puts each item back where it was. The app says "Moved {name} back".
- If some items cannot be put back: "Some items could not move back. Move
  them by hand."
- When several items are moved and some fail, the ones that moved stay
  moved, and the app says what went wrong with the first that did not.
- There is no way to move items to another workspace or between a
  workspace and the organization folder.

Messages when a move is refused:

| Text | When |
| --- | --- |
| "A folder cannot move into itself or one of its subfolders." | The destination is the folder itself or inside it. |
| `A folder named "{name}" already exists here. Choose another name.` | A folder of that name is already at the destination. |
| "Folders nest at most 16 levels deep." | The move would go past the depth limit. |
| "{name} changed since the list loaded. The list is up to date now; try again." | Someone changed the item first. |
| "This file no longer exists." or "This folder no longer exists." | The item is gone. |
| "This file is in the trash." or "This folder is in the trash." | The item was trashed meanwhile. |
| "The destination folder no longer exists." | The folder you chose was trashed or deleted meanwhile. |
| "Only organization owners and admins can change the organization folder." | You may not change the organization folder. |

### When a move changes who can open files

If a move would start or stop public links, the app first moves the items
it can move without changing access. For the rest it asks once:

- The dialog is titled "Change who can open these files?".
- It says what would happen, for example "3 files will become public via
  Press kit." or "2 public links will stop working."
- "Move" applies it. "Cancel" leaves those items where they were.

A member is never asked to make files public. Instead the app says "That
would make 1 file public. Only an owner or admin can make files public."
and moves nothing that would become public. With several files the text
reads "That would make 3 files public. ...".

Undo of a move that changed access puts the items back and restores the
access they had, without asking again. A member who moved a file out of a
public folder cannot undo that: putting it back would make it public, so
the app shows the same refusal.

### Favorites in the app

- On a file's page, the star beside the name reads "Add to favorites" or
  "Remove from favorites".
- For a file or a folder in a listing, the same two items are in its menu.
- Favorites are listed under "Favorites" in the navigation, in the order
  you added them. A file favorite opens the file's page. A folder favorite
  opens the folder.
- The workspace and the organization folder have separate lists. Each shows
  while you are in that workspace or in the organization folder.
- The app has no control to reorder favorites.
- If starring or unstarring is refused, the app says "Could not add to
  favorites. Try again." or "Could not remove from favorites. Try again."
  and the star stays as it was.

### The Details pane

Beside the listing, "Details" shows the open folder, or the workspace or
organization folder at the top level. On a narrow window it opens from the
"Details" button, or with Cmd+I or Ctrl+I, and closes with Escape.

- "Folder details" shows the name, how many folders and files are inside,
  and who can open it: "Restricted", "Every workspace" (the organization
  folder), "Public" or "Public, from {folder}".
- Inside a folder, "About" holds the form "Folder name" with "Rename",
  "Sharing" holds the general access, and "Location" shows the folders
  above with "Move".
- "Statuses" counts the files per status. Inside a folder, owners and admins
  find "Set status" at its bottom. "People" shows who can open the workspace
  or organization folder. "Recent activity" lists the files changed last in
  the folder and below it.

### Editing a file's details

A file's page has the form "File details" under the preview, in the
section "Details".

The form holds:

| Field | Notes |
| --- | --- |
| "Name" | Required. |
| "Description" | Several lines. |
| "Caption" | Several lines. |
| "Alt text" | One line. Shown for images only. "Describe the image for people who cannot see it." |
| "Tags" | "Separate tags with commas." |

- "Save details" saves the form. It is enabled only while there is
  something to save.
- Beside the button the form says "Unsaved changes", then "Saved".
- Tags are tidied when saved: " Spring Launch , q3" becomes "q3, spring
  launch".
- Only the fields you changed are sent.
- The "Fields" section in "Details" has its own "Save fields". Saving one
  keeps what you typed in the other. See [Fields and tags](fields-and-tags.md).
- If you leave the page with unsaved changes, they are kept for that
  browser tab and are back when you return to the file. Closing or
  reloading the tab asks before discarding them, whichever file they are
  for. A reload keeps them; the browser cannot tell the two apart, so it
  asks either way.
- Someone who may only read sees "Description", "Caption", "Alt text" and
  "Tags" as text, each "None" when empty.

Messages under a field:

| Text | When |
| --- | --- |
| "Enter a name of 1 to 200 characters." | The name is blank, too long or holds `/` or `\`. |
| "A description can be up to 2,000 characters." | The description is refused. |
| "A caption can be up to 500 characters." | The caption is refused. |
| "Alt text can be up to 1,000 characters." | The alt text is refused. |
| "Remove the tab or other character that cannot be saved." | The name, description, caption or alt text holds a control character that is refused there, for example a tab pasted into "Name" or "Alt text". |
| "Use at most 50 tags of 1 to 50 characters each." | The tags are refused. |

Other failures show in the form: "This file is in the trash.", "Only
organization owners and admins can change the organization folder." or
"Could not save the details. Try again."

### When someone else changed it first

The app never overwrites another person's change.

- **On a file's page.** If the file changed since you opened it, your save
  is not applied. The page shows "This file changed since you opened it.
  Reloading keeps your unsaved edits." with the button "Reload latest".
  - What you typed stays in the fields.
  - "Save details", "Save fields", "Replace file", "Move" and "Move to
    trash" are disabled until you reload.
  - "Reload latest" loads the current file. Fields you changed keep your
    text. Fields you did not touch show the other person's values.
  - Your next save then applies.
  - A page without unsaved edits follows the file by itself. When a change
    made elsewhere reaches it, such as a field set on a selection in the
    browser, its fields show the new values and your next save applies.
- **In a listing.** A rename, move or trash of an item that changed since
  the list loaded is refused with a message such as "This file changed
  since the list loaded. The list is up to date now; try again." The list
  refreshes by itself. A rename or move dialog stays open: choosing
  "Rename" or "Move here" again applies the change to the current item.
- Nothing is retried silently.

### Keyboard shortcuts

| Key | Action | When |
| --- | --- | --- |
| G then F | "Go to Files & Assets" | In a workspace |
| R | "Rename" | One item is selected or a file is open |
| M | "Move" | At least one item is selected or a file is open |
| Cmd+Backspace or Ctrl+Backspace | "Move to trash" | At least one item is selected or a file is open |
| Cmd+A or Ctrl+A | "Select all" | A listing you may change shows files or folders |
| Cmd+I or Ctrl+I | "Toggle details" | The Details pane is a drawer |
| A | "Review suggestion" or "Hide duplicate warning" | The Suggestions page shows a card in "To decide" ([The queue](library-and-suggestions.md#the-queue-to-decide)) |
| S | "Not now" | The Suggestions page shows a card and another could come forward |
| Cmd+Z or Ctrl+Z | "Undo" | While an Undo is offered |
| Escape | Clear the selection | Something is selected |

- Single keys do nothing while you type in a field or while a dialog or
  menu is open.
- The command palette also offers "New folder", "Go to Organization folder",
  "Download" and "Share".

## For agents

### Operations

| Operation | Capability ID | MCP tool | Scope |
| --- | --- | --- | --- |
| `GET W/files` | `workspace.files.search` | `workspace_files_search` | `files:read` |
| `GET W/files/{fileID}` | `workspace.files.get` | `workspace_files_get` | `files:read` |
| `PATCH W/files/{fileID}` | `workspace.files.update` | `workspace_files_update` | `files:write` |
| `GET W/folders` | `workspace.folders.list` | `workspace_folders_list` | `files:read` |
| `POST W/folders` | `workspace.folders.create` | `workspace_folders_create` | `files:write` |
| `PATCH W/folders/{folderID}` | `workspace.folders.update` | `workspace_folders_update` | `files:write` |
| `GET W/tags` | `workspace.tags.list` | `workspace_tags_list` | `files:read` |
| `PATCH W/tags/{tagID}` | `workspace.tags.rename` | `workspace_tags_rename` | `files:write` |
| `DELETE W/tags/{tagID}` | `workspace.tags.delete` | `workspace_tags_delete` | `files:write` |
| `GET W/favorites` | `workspace.favorites.list` | none | `files:read` |
| `POST W/favorites` | `workspace.favorites.add` | none | `files:read` |
| `PUT W/favorites/order` | `workspace.favorites.reorder` | none | `files:read` |
| `DELETE W/favorites/{favoriteID}` | `workspace.favorites.remove` | none | `files:read` |

Every operation exists for the organization folder too: replace `W` with `L`,
`workspace.` with `library.` and `workspace_` with `library_`.

### Requests and answers

| Operation | Body or parameters | Success |
| --- | --- | --- |
| List files | `q`, `folderID`, `root`, `under`, `tag`, `type`, `status`, `field`, `duplicates`, `sort`, `cursor`, `limit` | `200` with `items` and `nextCursor` |
| Read a file | none | `200` with the file |
| Change a file | `expectedLockVersion` (required), and any of `name`, `description`, `caption`, `altText`, `tags`, `folderID`, `fields`, `confirmVisibilityChange` | `200` with the file and its new `lockVersion` |
| List folders | `parentID` (the top level when left out), `cursor`, `limit` | `200` with `items` and `nextCursor` |
| Create a folder | `name` (required), `parentID`, `requestID` | `201` with the folder |
| Change a folder | `expectedLockVersion` (required), and any of `name`, `parentID`, `confirmVisibilityChange` | `200` with the folder |
| List tags | `cursor`, `limit` | `200` with tags by name, each `id`, `name`, `fileCount` |
| Rename a tag | `name` | `200` with the tag |
| Delete a tag | none | `204` |
| List favorites | none | `200` with your favorites in your order |
| Add a favorite | `kind` (`file` or `folder`) and `targetID` | `201` when new, `200` when it already existed |
| Reorder favorites | `favoriteIDs`: every favorite once, in the new order | `200` |
| Remove a favorite | none | `204` |

- A folder holds `id`, `name`, `parentID`, `folderCount`, `fileCount`,
  `lockVersion`, `visibility`, `publicURL`, `publicVia`, `createdAt`,
  `updatedAt`, `deletedAt` and `purgeAfter`.
- There is no operation that reads one folder by its ID. List the folders
  of its parent.
- A favorite holds `id`, `kind`, `targetID`, `name`, `createdAt`, `file`
  (a file summary, for a file) and `folderPath` (for a folder).
- What a file holds, and every argument of the tools, is in
  [MCP](../agents/mcp.md#files).

### Worked example: make a folder and move a file into it

Create the folder:

```sh
curl -s -X POST "$TALEWRIGHT/v1/workspaces/$WORKSPACE/folders" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Press kit 2026", "requestID": "press-kit-folder-1"}'
```

```json
{
  "id": "0192f0c3-8b50-7244-ad99-6dab4a5c1f34",
  "name": "Press kit 2026",
  "parentID": null,
  "folderCount": 0,
  "fileCount": 0,
  "lockVersion": 1,
  "visibility": "restricted",
  "publicURL": null,
  "publicVia": null,
  "createdAt": "2026-11-14T10:00:00Z",
  "updatedAt": "2026-11-14T10:00:00Z",
  "deletedAt": null,
  "purgeAfter": null
}
```

Move the file, sending the `lockVersion` you last read:

```sh
curl -s -X PATCH "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedLockVersion": 3,
    "folderID": "0192f0c3-8b50-7244-ad99-6dab4a5c1f34"
  }'
```

The answer is the file with `lockVersion` 4 and the new `folderPath`.

If the destination were a public folder and the file's status allowed
public use, the answer would instead be:

```json
{
  "error": {
    "code": "CONFLICT",
    "message": "...",
    "details": {
      "reason": "VISIBILITY_CHANGE",
      "becomePublic": 1,
      "stopPublic": 0,
      "publicVia": {
        "id": "0192f0c3-8b50-7244-ad99-6dab4a5c1f34",
        "name": "Press kit 2026"
      }
    }
  },
  "requestID": "..."
}
```

An agent does not confirm that by itself. It shows the counts to a person
and, on their yes, repeats the request with `confirmVisibilityChange:
true`. That works only for a credential that holds `files:approve` and acts
for an owner or admin.

### Worked example: find files

```sh
curl -s -G "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  --data-urlencode "q=spring poster" \
  --data-urlencode "type=image" \
  --data-urlencode "sort=name"
```

The answer lists the images whose name, description, caption, alt text,
tags or text fields hold a word starting with "spring" and a word starting
with "poster", by name, with each file's `folderPath`.

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| A folder "Brand" exists and someone creates "bRAND" beside it | `409 CONFLICT`, reason `NAME_TAKEN`. | Sibling names are unique, ignoring case. |
| The same name is used in another folder | It works. | Uniqueness is per place. |
| A folder is trashed and a new one takes its name | It works. | A trashed folder frees its name. See [Trash and restore](trash.md) for what the restore does then. |
| A folder name contains `/` | `422 VALIDATION_FAILED` on `name`. | `/` separates folders in a path. |
| A folder name is blank, 201 characters long or ends in a line break | `422 VALIDATION_FAILED` on `name`. | The naming rules. |
| A 17th level is created | `422 VALIDATION_FAILED` on `parentID`. | Folders nest at most 16 deep. |
| A folder with subfolders is moved so that its deepest folder would be at level 17 | `422 VALIDATION_FAILED` on `parentID`. Nothing moves. | The whole moved tree must fit. |
| A folder is moved into itself or into a folder below it | `409 CONFLICT`, reason `CYCLE`. | A folder cannot contain itself. |
| Two people move two folders into each other at the same moment | One move succeeds. The other gets `409 CONFLICT`, reason `CYCLE`. | Moves are handled one after the other. |
| A folder is moved to a place where a folder of its name exists | `409 CONFLICT`, reason `NAME_TAKEN`. | Sibling names are unique. Rename one of them first. |
| A file is moved to a folder of another workspace | `422 VALIDATION_FAILED` on `folderID`, the same as for an unknown ID. | Moves stay within one workspace or the organization folder. |
| A file is moved to a folder in the trash | `422 VALIDATION_FAILED` on `folderID`. | The destination must be live. |
| A file is moved into a folder at the very moment that folder is trashed | Either the move lands first and the file goes to the trash with the folder, or the trash lands first and the move gets `422` on `folderID`. | A file is never left live inside a trashed folder. |
| A file is moved to the folder it is already in | It succeeds and `lockVersion` goes up by one. | Naming a value counts as a change. |
| Two files with the same name end up in one folder | Both stay. | File names need not be unique. |
| A member moves a file whose status allows public use into a public folder | `403 FORBIDDEN`, reason `MAKES_FILES_PUBLIC`, `becomePublic` 1. The file stays where it was. | Only owners and admins make files public. |
| A member moves a file with the status "Internal use only" into a public folder | It moves, without a confirmation. It stays restricted. | The move makes nothing public. |
| That file later gets a status that allows public use | That is a status change, with its own confirmation. See [Statuses](statuses.md). | A file in a public folder is public once its status allows it. |
| A member moves a public file out of a public folder | First `409 CONFLICT`, reason `VISIBILITY_CHANGE`, `stopPublic` 1. With the confirmation it moves and its link stops. | Stopping a link needs only the confirmation. |
| A member moves a folder holding one eligible file under a public folder | `403 FORBIDDEN`, reason `MAKES_FILES_PUBLIC`, `becomePublic` 1. The folder stays. | The files inside would become public. |
| An empty folder is moved under a public folder by a member | It moves. | Nothing becomes public. |
| An owner moves a folder under a public folder without confirming | `409 CONFLICT`, reason `VISIBILITY_CHANGE`, with the counts. | Owners are asked too. |
| A file that is public by its own general access is moved | It moves without a confirmation and keeps its link. | Its link does not depend on where it is. |
| A restricted subfolder sits inside a public folder | Its files are public like the rest. | A folder below a public folder is shared with it. |
| A credential with `files:write` only moves an eligible file into a public folder | `403 FORBIDDEN`, reason `INSUFFICIENT_SCOPE`, `requiredScopes` `["files:approve"]`. | Making files public needs `files:approve`. |
| A plain member of a workspace asks for an API key with `files:approve` that lists it | `403 FORBIDDEN`. | Granting it needs the effective role owner or admin in every workspace the key lists. See [Credentials and scopes](../agents/credentials.md). |
| A file is renamed from `logo.png` to `logo.jpg` | The name changes. The file is still a PNG. | The type comes from the bytes, not the name. |
| A file is renamed to a name with `/` or `\` | `422 VALIDATION_FAILED` on `name`. In the app: "Enter a name of 1 to 200 characters." | A name holds no path. An upload refuses the same on `fileName`. |
| A file's name holds `/` and its alt text is changed | The change is saved and the name stays. A request that sends that name again as `name` is refused. | Only a name being set is checked. |
| A public file is renamed | Its public link keeps working, with the old name in it and with the new one. | The name in a link is only a label. |
| A description is sent as blank text | The description is cleared. | Blank clears. |
| Alt text contains a line break | `422 VALIDATION_FAILED` on `altText`. | Alt text is one run of text. |
| A tab is pasted into "Alt text" or "Name" in the app | The save is refused with "Remove the tab or other character that cannot be saved." under that field. | A name and an alt text hold no control character. A description and a caption may hold tabs and line breaks. |
| A file is given 51 tags | `422 VALIDATION_FAILED` on `tags`. | A file has at most 50 tags. |
| 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 as they were. | The comma separates tags in the app. |
| A tag of 51 characters is given | `422 VALIDATION_FAILED` on `tags`. | A tag is 1 to 50 characters. |
| "Brand" and " brand " are both given as tags | The file gets one tag, `brand`. | Tags are normalized. |
| A tag is renamed to the name of another tag | `409 CONFLICT`, reason `NAME_TAKEN`. Tags are not merged. | Tag names are unique in a workspace or the organization folder. |
| A plain member of a workspace renames or deletes one of its tags | `403 FORBIDDEN`. Tagging files still works. | Renaming and deleting a tag changes every file that carries it, so it needs an owner or admin of the workspace or the organization. |
| A tag is renamed while you edit a file that carries it | Your save gets `409 STALE_LOCK_VERSION`. | A tag rename moves the `lockVersion` of its files. |
| A change is sent with an old `expectedLockVersion` | `409 STALE_LOCK_VERSION` with `details.currentLockVersion`. Nothing changes. | Someone changed the item first. |
| A change is sent without `expectedLockVersion` | `422 VALIDATION_FAILED`. | It is required. |
| A file gets a new version while you edit its details | Your save applies. | A new version does not move `lockVersion`. |
| A trashed file or folder is renamed or moved | `409 CONFLICT`, reason `IN_TRASH`. | Restore it first. |
| `folderID` and `root=true` are both given in a listing | `422 VALIDATION_FAILED`. | Use one of `folderID`, `root` and `under`. |
| `under` names a folder with trashed subfolders | Files of the live folders are listed. | Trashed folders and their files are left out. |
| A search has 12 words | The first 10 count. | The limit on words. |
| A search is only punctuation, such as "---" | Every file is listed. | It holds no word to match. |
| A file's alt text is cleared | It is no longer found by the words that were in it. | Search follows every change at once. |
| A search word is in a file of another workspace | It is not found. | Search stays within one workspace or the organization folder. |
| Someone outside the workspace lists its files or folders | `404 NOT_FOUND`, as for an unknown workspace. | Outsiders cannot tell it exists. |
| A member of the organization changes an organization folder file | `403 FORBIDDEN`. | Only owners and admins change the organization folder. |
| A favorite is added twice | The second answer is `200` with the same favorite. Its place in the list does not change. | Adding is safe to repeat. |
| A favorite's file is trashed | The favorite disappears from the list. It returns with a restore. | Favorites of trashed items are hidden. |
| A favorite names a file of another workspace | `404 NOT_FOUND`. | Favorites are kept per workspace and organization folder. |
| A reorder leaves out one favorite, or names one twice | `422 VALIDATION_FAILED` on `favoriteIDs`. | A reorder names every favorite once. |
| Someone else asks to remove your favorite by its ID | `404 NOT_FOUND`. | Favorites are private. |
| You bookmarked a folder's address and the folder, or a folder above it, was moved | The folder opens at its new place and the address is corrected. | The address holds the path of folders as it was, so the app looks the folder up again. |
| You bookmarked a folder's address and the folder was trashed or deleted | The app says "This folder was deleted." | There is no live folder to open. |

## 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 | Changing the organization folder, or renaming or deleting a tag, without being an owner or admin there. | Ask an owner or admin. |
| `FORBIDDEN`, reason `MAKES_FILES_PUBLIC` | 403 | A move would make files public and the caller is not an owner or admin. `details.becomePublic` counts them. | Ask an owner or admin to move it, or move it somewhere that is not public. |
| `FORBIDDEN`, reason `INSUFFICIENT_SCOPE` | 403 | A credential lacks the scope the operation needs, or a move would make files public and it lacks `files:approve`. | Use a credential with the scope. |
| `EMAIL_NOT_VERIFIED` | 403 | A credential's move would make files public and its member's email is not verified. | Verify the email address. |
| `NOT_FOUND` | 404 | The workspace, organization, file, folder, tag or favorite is unknown or out of reach; a `parentID` to list is not a live folder. | Check the IDs. |
| `STALE_LOCK_VERSION` | 409 | `expectedLockVersion` is no longer current. `details.currentLockVersion` holds the current one. | Read the item again and repeat the change. |
| `CONFLICT`, reason `NAME_TAKEN` | 409 | A sibling folder has the name, ignoring case; or another tag has the name. | Choose another name. |
| `CONFLICT`, reason `CYCLE` | 409 | A folder is moved into itself or below itself. | Choose another destination. |
| `CONFLICT`, reason `IN_TRASH` | 409 | The file or folder is in the trash. | Restore it first. |
| `CONFLICT`, reason `VISIBILITY_CHANGE` | 409 | A move would start or stop public links and was not confirmed. `details` holds `becomePublic`, `stopPublic` and `publicVia`. | Show the counts to a person, then repeat with `confirmVisibilityChange: true`. |
| `CONFLICT`, reason `REQUEST_REUSED` | 409 | A `requestID` repeated with another body when creating a folder. | Use a new `requestID`. |
| `VALIDATION_FAILED` | 422 | `name`, `description`, `caption`, `altText` or `tags` breaks its rule; `folderID` or `parentID` is not a live folder here or would nest too deep; more than one of `folderID`, `root` and `under`; an unknown `type`, `sort`, `status`, `field`, `cursor` or `limit`; `favoriteIDs` incomplete. `details.field` names the field. | Correct the field. |
| `RATE_LIMITED` | 429 | A credential passed its request limit. | Wait for `Retry-After` seconds. |

The shape of every error is in [Errors](../reference/errors.md).

## Limits

| What | Value |
| --- | --- |
| Folder name | 1 to 200 characters, no `/`, no control characters, unique among siblings ignoring case |
| Folder depth | 16 levels |
| File name | 1 to 200 characters, no control characters, no `/` or `\`, need not be unique |
| Description | Up to 2,000 characters |
| Caption | Up to 500 characters |
| Alt text | Up to 1,000 characters, one run of text |
| Tags on one file | Up to 50 |
| Tag name | 1 to 50 characters once normalized, no control characters, no comma |
| Search words in one query | The first 10 count |
| Page size of a listing | 1 to 100, default 50 |
| Folders in a workspace or organization folder | No limit |
| Files in a folder | No limit |
| Favorites | No limit |
| Undo in the app | Offered for 8 seconds |

See [Limits](../reference/limits.md#files) for every limit in one place.

## Questions and answers

**Can I move files between workspaces?**
No. A file moves only within its own workspace, or within the organization
folder. To have a file in another workspace, download it and upload it
there. The copy is a new file: it starts with version 1 and without the
first file's details.

**Can I move a file from a workspace into the organization folder?**
Not by moving. Upload it to the organization folder, which needs an owner or
admin.

**Can two files have the same name?**
Yes, even in the same folder.

**Can two folders have the same name?**
Not in the same place, and case does not matter. In different places, yes.

**How deep can folders go?**
16 levels.

**What happens to the files when I move a folder?**
They move with it. Nothing about them changes, except who can open them if
the folder moves into or out of a public folder.

**Why does the app ask "Change who can open these files?"**
The move would make files public or stop public links, because the place
you move them to, or from, is shared with anyone who has the link. Nothing
moves until you choose "Move".

**Why can't I move this file into that folder?**
The folder is public and the file's status allows public use, so the move
would make the file public. Only an owner or admin can do that. Ask one of
them to move it.

**I moved a file out of a public folder by mistake. Can I undo it?**
An owner or admin can, with "Undo" or by moving it back. A member cannot,
because moving it back would make it public again.

**Does renaming a file break its links?**
No. The file's page in the app and its public link both keep working.

**Does renaming change the file type?**
No. A PNG renamed to `logo.jpg` is still a PNG.

**What does search look at?**
The name, description, caption, alt text, tags and text fields of each
file. It does not look inside the file.

**Why doesn't search find my file by a word in the middle of its name?**
Search matches from the start of each word. "port" does not find
"report", but "rep" does. Names are split into words at punctuation, so
`annual-report.pdf` is found by "report".

**Does search look in the open folder only?**
No. It looks through the whole workspace or organization folder, and each
result says which folder it is in.

**How do I find duplicates?**
Choose Filter > "Show" > "Duplicates". It lists the files whose bytes are
the same as another file's in the same workspace or organization folder.

**How do I see only images?**
Click the "Images" card above the listing, or choose Filter > "Type" >
"Images". Raw photos, Photoshop files and SVG count as images.

**Can I sort by size or by date created?**
No. Files sort by "Recently updated" or by "Name".

**Are my favorites visible to others?**
No. They are yours alone.

**What is the difference between a caption, a description and alt text?**
All three are text about a file. The description is the longest, the
caption is a short text to show with the file, and alt text describes an
image for people who cannot see it.

**The app says the file changed since I opened it. Did I lose my text?**
No. Choose "Reload latest". Your text stays in the fields you changed, and
you can save again.

**Can I undo a move?**
Yes, for 8 seconds, with "Undo" in the message or Cmd+Z / Ctrl+Z. After
that, move the items back yourself.

**Can an agent organize files?**
Yes, with a credential that holds `files:write`: it creates folders, moves
and renames files and folders, and sets details and tags. It cannot make
files public by a move unless it also holds `files:approve` and acts for an
owner or admin.

**How does an agent avoid overwriting a person's change?**
It sends the `lockVersion` it read as `expectedLockVersion`. If the file
changed in between, the change is refused with `STALE_LOCK_VERSION` and the
agent reads the file again.

## Related pages

- [Files & Assets overview](overview.md)
- [Uploading](uploading.md)
- [Versions and history](versions.md)
- [Trash and restore](trash.md)
- [Downloading](downloading.md)
- [Statuses](statuses.md)
- [Sharing and public links](sharing.md)
- [Fields and tags](fields-and-tags.md)
- [The organization folder and suggestions](library-and-suggestions.md)
- [MCP](../agents/mcp.md) and [The REST API](../agents/rest-api.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

