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 and Sharing and public links.
- The full matrix is in Roles and permissions.
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 CONFLICTwithdetails.reasonNAME_TAKENand 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_FAILEDonparentIDwith 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.
parentIDnames 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_FAILEDonparentID. - A new folder is empty, is restricted, and has
lockVersion1. - 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.
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. - A trashed folder cannot be renamed:
409 CONFLICT, reasonIN_TRASH.
Moving a folder
- A folder moves with everything inside it.
parentIDnames the new parent.nullmoves 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 CONFLICTwith reasonCYCLEand the message "A folder cannot move into itself or its subfolders". - The destination must be a live folder here: otherwise
422 VALIDATION_FAILEDonparentID. - 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
folderIDnames the folder the file moves to.nullmoves 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_FAILEDonfolderID. - 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, reasonIN_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. 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 CONFLICTwith reasonVISIBILITY_CHANGEand changes nothing.detailsholds: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, ornull.
- Sending the same request again with
confirmVisibilityChange: trueapplies 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, reasonMAKES_FILES_PUBLIC.details.becomePubliccounts 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:approvein addition tofiles:write. Without it the answer is403 FORBIDDENwith reasonINSUFFICIENT_SCOPEanddetails.requiredScopes["files:approve"]. - The credential's member must be an owner or admin. A credential that
holds
files:approvefor a plain member is refused withMAKES_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:writeand 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 itsfolderID, 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
nullor 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_FAILEDwith the message "a tag cannot contain a comma": ontagswhen it is set on a file or named in anadd_tagorremove_tagitem of a suggestion, onnamewhen 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, reasonNAME_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
lockVersionof 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.
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: thelockVersionyou last read. - If it is still current, the change is applied and
lockVersiongoes up by one. - If it is not, the answer is
409 STALE_LOCK_VERSIONwithdetails.currentLockVersion, and nothing changes. Read the item again, look at what changed, and send your change with the new number. - A file's
lockVersionmoves 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
lockVersiondoes not move when the file gets a new version. Replacing a file has its own check. See Versions and history. - A folder's
lockVersionmoves when it is renamed, moved, trashed or restored. - A request that names nothing to change succeeds and leaves
lockVersionas it is. - A request that sets a value to what it already is counts as a change.
- More in The REST API.
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,rootandundercan be used at a time. Two of them answer422 VALIDATION_FAILED. - Every listed file carries
folderPath: the folders from the top level down to its own folder, each withidandname. It is empty for a file at the top level. - Trashed files are never listed here.
trash=truelists them instead. See Trash and restore.
Search
qholds 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.jpgis 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.
typegoes 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 answers422 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.
duplicatescompares current versions only, within one workspace or the organization folder, and ignores trashed files.
Sorting
sort=updatedis the default: most recently updated first.sort=nameorders 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 and Trash and restore.
- "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
othertype. 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. |
| "Share" | Everyone. See Sharing and public links. |
| "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. |
| "Add to favorites" or "Remove from favorites" | Everyone |
| "Move to trash" | Whoever may change the item. See Trash and restore. |
- "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
- Choose "New folder": the button at the top, the icon beside "Folders", a right-click on empty space, or the command palette.
- The dialog "New folder" has the field "Name" and the button "Create folder".
- 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.
- 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) |
| 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,deletedAtandpurgeAfter. - 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) andfolderPath(for a folder). - What a file holds, and every argument of the tools, is in MCP.
Worked example: make a folder and move a file into it
Create the folder:
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"}'
{
"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:
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:
{
"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
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 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. | 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. |
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.
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 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.