Talewright Docs Open the app

The organization folder and suggestions

Summary

Every organization has one organization folder (the API's library). It is a shared place for files that every workspace of the organization uses: logos, brand guides, fonts, anything that belongs to the whole organization and not to one brand or client. Every member of the organization reads the organization folder. Only the organization's owners and admins change it.

A suggestion is a batch of proposed changes to files - tags to add or remove, moves, new names and alt texts - that somebody prepares and a person reviews. Nothing changes until a person applies it in the app. Suggestions exist in every workspace and in the organization folder. They are how an agent tidies files without changing anything on its own.

In the API and in MCP a suggestion is called a library proposal. The name is the same for workspaces and for the organization folder: a proposal in a workspace is also a "library proposal".

This page covers what the organization folder is and how it differs from a workspace, and suggestions in full: what one can hold, who makes, applies and rejects it, its states, its expiry and what applying does.

Who can do what

"In a workspace" means the effective role in that workspace. "In the organization folder" means the role in the organization. See Roles and permissions.

ActionIn a workspaceIn the organization folderSessionCredential (scope)
Open it and read its files, folders and tagsEveryone who can open the workspaceEvery member of the organizationYesYes (files:read)
Download filesEveryone who can open the workspaceEvery member of the organizationYesYes (files:read)
Star a file or folder as a favoriteEveryone who can open the workspaceEvery member of the organizationYesYes (files:read), REST only
List the duplicate groupsEveryone who can open the workspaceEvery member of the organizationYesYes (files:read)
Hide a duplicate warning for yourself, or show it againEveryone who can open the workspaceEvery member of the organizationYesYes (files:read), REST only
Upload, rename, describe, tag, move, trash and restore files; create, rename, move, trash and restore foldersEveryone who can open the workspaceOrganization owner or adminYesYes (files:write)
Rename and delete tagsOwner or adminOrganization owner or adminYesYes (files:write)
Manage the statuses, custom fields and their choicesOwner or adminOrganization owner or adminYesNo
Set a status on filesOwner or adminOrganization owner or adminYesYes (files:approve)
Change general access of a file or folderOwner or adminOrganization owner or adminYesNo
Delete a trashed file or folder for good, empty the trashOwner or adminOrganization owner or adminYesNo
List and read suggestionsEveryone who can open the workspaceEvery member of the organizationYesYes (files:read)
Make a suggestionEveryone who can open the workspaceOrganization owner or adminYesYes (files:write)
Reject items of a suggestionEveryone who can open the workspaceOrganization owner or adminYesYes (files:write)
Apply items of a suggestionEveryone who can open the workspaceOrganization owner or adminYesNo
Apply a move that makes files publicOwner or adminOrganization owner or adminYesNo
  • A credential acts for one member. Its scope is not enough by itself: the member must also hold the role the row asks for. A plain member's key with files:write cannot change the organization folder.
  • A credential that tries to apply a suggestion gets 403 FORBIDDEN with details.reason HUMAN_APPROVAL_REQUIRED.
  • Someone who is not a member of the organization gets 404 NOT_FOUND for the organization folder and everything in it, the same answer as for an organization that does not exist.

How it works

The organization folder

  • Every organization has exactly one organization folder.
  • The organization folder belongs to the organization, not to a workspace. Every workspace of the organization shows the same organization folder.
  • The organization folder holds files with their versions, folders, tags, a trash, uploads and suggestions of its own, just like a workspace.
  • Every member of the organization reads the organization folder: lists and searches its files, opens them, reads their versions and downloads them. This needs no workspace membership.
  • Only organization owners and admins change the organization folder. They upload, rename, describe, tag, move, trash and restore its files, manage its folders and rename or delete its tags.
  • A plain member who tries to change the organization folder gets 403 FORBIDDEN. Nothing changes.
  • A member's role in a workspace gives nothing in the organization folder. Someone who is owner of a workspace but a plain member of the organization still only reads the organization folder.
  • There is no operation that deletes the organization folder. It exists as long as the organization does. See Deleting and restoring.

How the organization folder differs from a workspace

A workspaceThe organization folder
How manyAny number per organization, at least oneOne per organization
Who readsOrganization owners and admins, and the workspace's membersEvery member of the organization
Who changes files and folders, and tags filesEveryone who can open itOrganization owners and admins
Who manages statuses, fields and tags, sets statuses, changes general access and deletes for goodIts owners and adminsOrganization owners and admins
Where its statuses, fields and tags are managedIts pages "Statuses", "Custom fields" and "Tags" under "Files & Assets", in its own settings navigation under "File spaces"The same three pages of "Organization folder" under "File spaces" in the settings navigation
The role that countsThe effective role in the workspaceThe role in the organization
REST path/v1/workspaces/{workspaceID}/.../v1/organizations/{organizationID}/library/...
MCP toolsworkspace_..., with workspaceIDlibrary_..., with organizationID
What a credential reachesOnly the workspaces it listsAlways the organization folder of its own organization
Badge on an item that is not public"Restricted""Every workspace"
Can be deletedYes, and restored for 30 daysNo

Everything else works the same way in both. The operations have the same inputs and the same answers. The pages Uploading, Folders, moving and finding, Versions and history, Trash and restore and Downloading apply to the organization folder as they do to a workspace.

What the organization folder shares with workspaces, and what it keeps apart

  • Statuses and fields are separate. The organization folder and each workspace have their own statuses and custom fields. An organization folder file carries only the organization folder's status and field values; a status, field or choice of a workspace is refused there with 422 VALIDATION_FAILED, and the other way round. See Statuses and Fields and tags.
  • Folders are separate. The organization folder has its own folder tree. A folder of the organization folder is not listed in any workspace, and a workspace folder is not listed in the organization folder.
  • Tags are separate. A tag belongs to the organization folder or to one workspace. The organization folder's tags are not offered in a workspace. See Fields and tags.
  • Files are separate. An organization folder file cannot be read through a workspace path, and a workspace file cannot be read through the library path. Both answer 404 NOT_FOUND.
  • Files do not move between the two. A file cannot be moved from a workspace into the organization folder, from the organization folder into a workspace or from one workspace into another. Naming a folder of another place as the destination answers 422 VALIDATION_FAILED.
  • The trash is separate. The organization folder has its own trash. Only organization owners and admins trash and restore organization folder files, and only they delete them for good or empty the organization folder's trash, in a browser. The rest is as described in Trash and restore.
  • Favorites are separate and private. Each person has their own favorites in the organization folder and in each workspace. A member who only reads the organization folder can still star its files and folders.
  • Suggestions are separate. A suggestion belongs to the organization folder or to one workspace and names only files of that place.
  • Duplicates are found across both. A file's details name other live files with the same content in the same place, in the organization folder and in the other workspaces you can open. See Duplicate groups.
  • The audit trail records organization folder changes for the organization, without a workspace. See Audit trail.

Public sharing of organization folder files

  • An organization folder file or folder is "Restricted" or public, with the same rule as in a workspace: a file is public only while its status allows public use, it is live, and it or a folder above it is shared. See Sharing and public links.
  • An organization folder item that is not public can be opened by every member of the organization. The card "Folder details" shows the badge "Every workspace" for it where a workspace folder reads "Restricted", and an organization folder file's "Sharing" section says "Only people in the organization can open it."
  • Organization owners and admins change general access of organization folder files and folders, in a browser. No credential can.
  • Organization owners and admins set statuses on organization folder files, in a browser or through a credential with files:approve. See Statuses.

Suggestions

  • A suggestion is a list of proposed changes to files, with a one-line summary of what it is about.
  • A suggestion belongs to one place: one workspace, or the organization folder. Every file it names is in that place.
  • Making a suggestion changes no file. Each proposed change waits as an item with the state pending.
  • A person reviews the items in the app and applies the ones they choose. They can also change an item's value before applying it, or reject items.
  • Applying is done by a person in a browser. No API key and no connected app can apply a suggestion, whatever its scopes.
  • A suggestion cannot change a status, general access, a description, a caption, a custom field, a version or anything outside its place. It cannot trash, restore or delete a file. See What a suggestion can hold.
  • The app has no form for making a suggestion. Suggestions are made through the REST API or MCP, typically by an agent with a files:write key.
  • A suggestion stays open for 14 days. Then it expires and nothing more of it can be applied.
  • A suggestion cannot be edited or deleted. To withdraw one, reject its pending items. To change one, reject it and make a new one.

What a suggestion can hold

A suggestion holds 1 to 500 items. Each item names one file, one action and the action's payload.

ActionPayloadWhat applying it does
add_tag{"tag": "name"}Adds the tag to the file. The tag is created in that place if it does not exist yet.
remove_tag{"tag": "name"}Takes the tag off the file. The tag itself stays.
move{"folderPath": ["Brand", "Logos"]}Moves the file into that folder, named from the top level down. [] is the top level. Folders that do not exist are created.
rename{"name": "new name"}Gives the file that name.
set_alt_text{"altText": "text"}Sets the alt text. null or blank text clears it.
  • A payload must fit its action exactly. A missing key, an extra key or a value of the wrong kind answers 422 VALIDATION_FAILED on payload.
  • Payloads are stored in their normalized form. A tag is trimmed, its inner spaces are collapsed and it is put in lower case, so "Logo" is stored as "logo". Names and alt text are trimmed. Blank alt text is stored as null.
  • A tag is 1 to 50 characters once normalized and holds no comma. See Fields and tags.
  • A folderPath names at most 16 folders. Each name is 1 to 200 characters and has no /.
  • A file name is 1 to 200 characters and has no / or \.
  • Alt text is at most 1,000 characters. See Fields and tags.
  • No value may contain a control character such as a tab or a line break.
  • An item can carry a rationale: why the change is proposed, in 1 to 2,000 characters on one line. The app shows it under the item. Leave it out or send null when there is none; a blank string is refused.
  • A suggestion can hold several items for the same file, also several of the same action.
  • Items keep the order they were sent in. That is the order they are shown and applied in.

Making a suggestion

  • In a workspace, everyone who can open the workspace makes suggestions. In the organization folder, organization owners and admins do.
  • A credential needs files:write, and its member needs that same role.
  • A suggestion needs a summary of 1 to 500 characters on one line, and 1 to 500 items.
  • Every item must name a live file of the same workspace or organization folder. A file in the trash, a file of another place and an unknown ID are all refused the same way: 422 VALIDATION_FAILED on items. One such item refuses the whole suggestion.
  • Each item records the file's lockVersion it is based on, as baseLockVersion. When the request leaves it out, the file's current lockVersion is used.
  • baseLockVersion must be at least 1. It is not compared with the file's current lockVersion when the suggestion is made. A value that does not match shows only when the item is applied: the item then ends stale.
  • Several items for one file that leave baseLockVersion out all get the same value. They still all apply, one after the other. See Applying.
  • The answer is 201 with the suggestion and its items. The suggestion is open, every item is pending, and expiresAt is 14 days after createdAt.
  • A request can carry a requestID so that a retry does not make a second suggestion. Over REST it is optional. Over MCP it is required. See Safe retries.
  • Nobody is notified by email when a suggestion is made. It shows in the app at once.

States

A suggestion is in one of three states:

StateIn the appMeaning
open"Open"It has not expired, and not every item is decided. Items can be applied and rejected.
closed"Closed"Every item was decided before the suggestion expired.
expired"Expired"14 days passed while at least one item was still pending.

An item is in one of four states:

StateIn the appMeaning
pending"Pending"Not decided yet.
applied"Applied"A person applied it. The file was changed.
rejected"Rejected"Somebody rejected it. The file was not changed.
stale"Changed since suggested", or "Expired"It could not be applied because its file changed ("Changed since suggested"), or the suggestion expired before anyone decided it ("Expired"). The file was not changed.
  • A suggestion closes by itself the moment its last pending item is applied, rejected or found stale. Nobody closes a suggestion by hand.
  • It also closes the moment its last pending item disappears because its file was deleted for good. Nothing is left to decide then.
  • closedAt is the time that happened. It is null while items are pending.
  • A closed suggestion stays closed for good. It does not turn expired after 14 days.
  • allowedActions lists what the caller who reads the suggestion may do to it now. It is [] once the suggestion is closed or expired.
  • While it is open, a person in the browser who may decide it sees ["apply", "reject"]. A credential with files:write acting for such a person sees ["reject"], because applying needs a browser.
  • A credential without files:write, and a member reading an organization folder suggestion, see [].
  • A decided item never changes again. Applying or rejecting an item that is not pending answers 409 CONFLICT with reason ITEM_DECIDED.
  • decidedAt and decidedBy say when an item was decided and by whom. Both are null while it is pending.

Expiry

  • A suggestion expires 14 days after it was made, at expiresAt, if any of its items is still pending then.
  • From that moment it reads expired, and applying or rejecting answers 409 CONFLICT with reason CLOSED.
  • Within about an hour after that, its pending items are marked stale. They get a decidedAt but no decidedBy, since no person decided them. closedAt is set at the same time. The suggestion keeps reading expired.
  • Until that happens, an expired suggestion can still show items as pending. They can no longer be decided.
  • The app calls both kinds "Expired": a pending item of an expired suggestion, and a stale item nobody decided.
  • Items that were applied or rejected before the expiry keep their state. Their changes stay.
  • The 14 days cannot be extended. Make a new suggestion for what is left.

Applying

Applying is the step that changes files.

  • Only a person signed in with a browser applies. In a workspace that is everyone who can open it. In the organization folder it is the organization's owners and admins.
  • The person chooses which pending items to apply: 1 to 500 of them, each named once. Items that are not chosen stay pending and can be decided later.
  • The person can change the value of an item before applying it. The changed payload must fit the item's action, like a new one. What was applied is then kept on the item as appliedPayload, next to the original payload. appliedPayload is null when the item was applied as suggested.
  • Chosen items are applied in the suggestion's order, whatever order the request names them in.
  • Before an item is applied, its file is checked. The file must be live in that place, and its lockVersion must be the one the item expects. Otherwise the item becomes stale and the file is left alone. See Changed since suggested.
  • An item expects its baseLockVersion, or, when earlier items of the same suggestion were applied to the same file, the lockVersion the last of them left. This is why two items for one file both apply, in one go or one after the other.
  • Each applied item raises the file's lockVersion by one. The item records the new value as resultLockVersion.
  • An applied item counts as a change by the person who applied it. The file reads as last changed by them, and each applied item is recorded in the audit trail as a file change that names the suggestion.
  • The answer is 200 with applied (how many items were applied), stale (how many were found stale) and the suggestion as it is now.
  • The suggestion closes when no item is pending any more.

What each action does when it is applied:

  • add_tag adds the tag. If the file already has it, the tags stay as they are and the item still counts as applied.
  • remove_tag takes the tag off. If the file does not have it, nothing is removed and the item still counts as applied.
  • move finds the destination folder by its names, from the top level down, ignoring case: "brand" finds the folder "Brand". A folder on the path that does not exist is created, with the name as the suggestion spells it, by the person applying. Folders in the trash do not count: a new folder of that name is created. Two items that move files to the same new folder create it once.
  • rename sets the name. The file's public link, if it has one, keeps working: the name in a link is only decoration.
  • set_alt_text sets the alt text, or clears it when the value is null or blank.

When a chosen item is refused, the whole request changes nothing. No item of it is applied, none is marked stale, and every chosen item stays pending. This happens when:

  • a changed payload does not fit its action or breaks a naming rule (422 VALIDATION_FAILED),
  • adding the tag would give the file more than 50 tags (422 VALIDATION_FAILED on tags),
  • a move would make files public and the person applying is not an owner or admin (403 FORBIDDEN with reason MAKES_FILES_PUBLIC),
  • a chosen item was already decided (409 CONFLICT, reason ITEM_DECIDED), or an ID is not an item of this suggestion (422 VALIDATION_FAILED on items).

Leave the refused item out, or reject it, and apply the rest.

What applying never does:

  • It never changes a file's status or its general access setting.
  • It never changes a member's role or anybody's access to a workspace.
  • It never touches the file's content or versions.
  • It never changes a file that is not named by a chosen item.

Moves that change access

A move can change who can open a file, because a file in a shared folder is public while its status allows public use. See Public folders.

  • A plain move asks for a confirmation when it would start or stop public links. Applying a suggestion is that confirmation: the person applying sees each move and its destination, and the move goes ahead without a second question.
  • A move that only stops public links - the file leaves a shared folder - is applied by everyone who may apply the suggestion.
  • A move that makes files public is applied only by an owner or admin. When a plain member of a workspace applies such an item, the whole request is refused with 403 FORBIDDEN, reason MAKES_FILES_PUBLIC, and details.becomePublic, the number of files the selected moves together would make public. Nothing is applied.
  • The item stays pending. An owner or admin can apply it, or the member can reject it and apply the rest.
  • In the organization folder this refusal does not occur, since only owners and admins apply there.
  • The general rule, with every case, is in Moves and restores that change access.

Rejecting

  • Rejecting marks pending items rejected. Their files do not change.
  • In a workspace, everyone who can open it rejects. In the organization folder, organization owners and admins do.
  • A credential with files:write can reject, for a member with that role. This is how an agent withdraws its own suggestion.
  • A request names the items to reject in itemIDs: 1 to 500 pending items, each once. Without itemIDs, every pending item is rejected.
  • Rejecting the last pending item closes the suggestion.
  • A rejected item cannot be applied later. Suggest the change again in a new suggestion.
  • Rejecting a suggestion that is closed or expired answers 409 CONFLICT with reason CLOSED. Naming an item that is already decided answers ITEM_DECIDED, and nothing is rejected.
  • Anyone who may reject can reject any suggestion of that place, not only their own.

Changed since suggested

"Changed since suggested" is what the app calls an item in the state stale. A stale item changed nothing and never will.

An item becomes stale when it is applied and:

  • its file was changed after the suggestion was made: renamed, moved, tagged, described, given a field value, trashed and restored, or changed in any other way that raises its lockVersion,
  • a tag the file carries was renamed or deleted, or a custom field or choice the file had a value for was deleted, since those raise its lockVersion too,
  • its file is in the trash,
  • the item was sent with a baseLockVersion that does not match the file.

An item also becomes stale when the suggestion expires while it is pending.

  • A new version of the file does not raise its lockVersion. Replacing a file's content alone does not make items stale.
  • A stale item found while applying records the person who applied as decidedBy. One made stale by expiry has no decidedBy.
  • When one item of a file is stale, later items of the same suggestion for that file are stale too when they are applied, since the file is no longer what they expect.
  • The way forward is a new suggestion based on the file as it is now.

Duplicate groups

A duplicate group is a set of live files whose current versions have the same bytes. The organization folder and each workspace can list their groups.

  • Files are compared by their bytes, never by their names. Only the current version of a file counts.
  • A place lists a group when at least one copy is in that place and the reader can open at least two copies in all.
  • The copies can be anywhere the reader can open: the same workspace or organization folder, the organization folder, and the reader's other workspaces. So a file with one copy in a workspace and one in the organization folder is a group in both.
  • A copy in a workspace the reader cannot open is not named and is not counted. Two people can see different copies of the same group, or one of them can see no group at all.
  • A credential sees only the workspaces it lists, and the organization folder.
  • Copies in another organization are never compared.
  • Files in the trash are not copies. Trashing a copy takes it out of its group, and a group left with one copy is no longer a group. Restoring the file brings it back.
  • A group has digest (the SHA-256 of the shared bytes, as sha256: and 64 hex digits), fileCount (the copies the reader can open), hidden and files.
  • files names up to 20 copies: the copies of this place first, then the organization folder's, then other workspaces'. Within each, oldest file first.
  • Each copy has id, name, workspaceID (null for the organization folder), fileSpaceName (the workspace's name, or "Library", which the app shows as "Organization folder"), folderPath (from the top folder down; empty at the top level) and sizeBytes.
  • Groups come newest first: the group whose newest copy was created last leads.
  • The list is paged. It also answers totalCount, the groups the reader has not hidden, and hiddenCount, the groups they have. Both cover every page and do not change with the hidden filter.
  • hidden=true lists only the groups the reader hid. hidden=false lists only the others. Without it every group is listed.
  • This is the same comparison as duplicates on a file and on an upload. See Uploading.
  • The file listing's duplicates=true filter is narrower. It keeps files with another copy in the same workspace or organization folder only. See Folders, moving and finding.
  • Nothing is merged or removed automatically. A group is information.

Hiding a duplicate warning

Each person can hide the warning of a group for themselves.

  • Hiding is private. It changes nothing for anyone else: other people still see the group as not hidden, and admins neither see nor change someone else's hides.
  • Everyone who can read the place can hide there. A member who only reads the organization folder can hide an organization folder file's warning.
  • A hide is for the whole group, not for one file. It is made through any live copy of the group, and it then applies to every copy: each copy's details read duplicatesHidden: true, in every place the person opens.
  • A hide remembers the copies the person could open when hiding.
  • A new copy shows the warning again. When a copy appears that was not there when the person hid the group, the group reads hidden: false again and counts in totalCount. A new copy is a new upload with the same bytes, a new version that makes another file identical, a copy restored from the trash that was in the trash when hiding, or a copy in a workspace the person has joined since.
  • A copy that leaves does not end the hide. Trashing a copy, or replacing its content, keeps the rest of the group hidden.
  • Hiding again after a new copy appeared hides the group with the new copy.
  • Hiding twice is not an error. Showing a group that is not hidden is not an error either.
  • Showing again removes the hide. The group reads hidden: false and counts in totalCount at once.
  • A hidden group is still listed, with hidden: true, so it can be shown again.
  • A file's duplicates are named whether hidden or not. duplicatesHidden only says that the reader hid the warning. It is false for a file without duplicates.
  • A hide made with a credential covers the copies the credential can open. If the member's browser session opens more copies, their session still sees the warning.
  • A file without any copy can be hidden too. It has no effect until a copy appears, and that first copy shows the warning.
  • Only a live file can be named when hiding or showing. A file in the trash answers 404 NOT_FOUND.
  • Hiding and showing are not recorded in the audit trail and raise no lockVersion.

In the app

Opening the organization folder

The organization folder is opened from Files & Assets of any workspace of the organization.

  • The tree "Folders" in the Files & Assets navigation starts with the name of the organization, which is the organization folder: choosing it opens the organization folder, and its arrow closes or opens the nodes below it.
  • Below it the tree has a workspace folder for each workspace of that organization you can open, then the organization folder's own folders. Choosing a workspace folder opens that workspace's files.
  • The organization folder's top level lists the same workspace folders first, marked "Workspace", then its own folders and files. A workspace folder has no menu or select box and cannot be moved, renamed or deleted there: it only opens the workspace. Search, filters and type tabs leave workspace folders out.
  • The command palette offers "Go to Organization folder".
  • The organization folder's address is https://app.usetalewright.com/w/{workspaceID}/files/library. The workspace in the address is the one you came from. The organization folder shown is the same from every workspace.
  • The breadcrumb reads "Files & Assets", the organization's name, then "Organization folder". The organization's name is not a link.
  • The organization folder's top level lists only the organization folder's own folders and files. "Upload" and "New folder" there, for owners and admins, put files and folders in the organization folder.
  • The card "Folder details" shows the badge "Every workspace" for the organization folder and for folders of the organization folder that are not public. A public one reads "Public", or "Public, from {folder}" when a folder above shares it.
  • The card "People" shows the members of the organization.
  • The organization folder has its own "All files" and "Suggestions" pages in the navigation "Files pages", a "Trash" page for owners and admins, and its own favorites.

What a member sees in the organization folder

A plain member of the organization reads the organization folder and is offered nothing that changes it:

  • no "New folder" and no "Upload",
  • no "Trash" in the navigation,
  • no checkboxes to select files,
  • a file's menu with "Open" and "Download", without "Rename", "Move" or "Move to trash",
  • a file's page with "Download", without "Save details", "Move" or "Move to trash", and without a field to change the name,
  • no "Upload files" in the command palette while the organization folder is open, and a file dropped on the organization folder page is not uploaded.

Where a change is refused anyway, for example on a page that was open while the person's role changed, the app says "Only organization owners and admins can change the organization folder." The organization folder's trash page, opened by its address, shows the same sentence to a member.

Owners and admins of the organization see the organization folder like a workspace, with every control.

The Suggestions page

"Suggestions" in the navigation "Files pages" opens the suggestions of the place that is open: the workspace's, or the organization folder's.

  • The link shows a number while something waits for a look. The number is the open suggestions of the place plus its duplicate groups you have not hidden.
  • The number counts every open suggestion of the place, however many there are and whoever may decide them. A plain member in the organization folder sees them counted too.
  • A screen reader hears the two parts apart: "Suggestions, 1 open", "Suggestions, 2 duplicates" or "Suggestions, 1 open, 2 duplicates".
  • Hiding a duplicate warning, or showing it again, changes the number at once, without a reload.
  • With no open suggestion and no duplicate group left to look at, the link shows no number.
  • The command palette offers "Go to Organization folder suggestions", which opens the organization folder's page from any workspace.
  • The page is titled "Suggestions". From the top it has the queue "To decide", the table "Duplicate files" and the closed section "Handled". See The queue "To decide", Duplicate files on the Suggestions page and "Handled".
  • In the organization folder, a plain member reads above the queue: "Organization owners and admins apply the organization folder's suggestions."

The queue "To decide"

The queue shows what waits for a decision one card at a time: the open suggestions of the place, newest first, then its duplicate groups you have not hidden, in the order of "Duplicate files".

  • A card is marked "Suggestion" or "Duplicate" and reads "1 of 4" at its end, where 4 is every open suggestion and every duplicate group you have not hidden, also those not loaded yet.
  • A suggestion's card shows its summary and a line such as "3 items to decide · by Ravi Admin". Its button "Review" opens the suggestion. A plain member in the organization folder gets "Review" too, and the suggestion opens to read.
  • A duplicate's card shows the name of the group's first copy and a line such as "2 copies, 18.4 kB each · in Sorrel Copies, Organization folder", with up to three places and "and 2 more" for the others. Its button "Hide" hides the group's warning for you, exactly as "Hide" in the table does: the app says "Duplicate warning hidden" with "Undo", and the next card comes forward.
  • "Hide" is disabled when none of the group's listed copies is in the place that is open, as in the table.
  • "Not now" puts the card at the back of the queue and brings the next one forward. It lasts until you leave the page: the next visit starts in the usual order again, and nothing is saved.
  • Once every loaded card has been put off, the queue loads the next 50 suggestions or groups, which come forward before the cards you put off.
  • With a single card and nothing more to load, "Not now" is disabled.
  • A runs the card's button ("Review" or "Hide"); S is "Not now". The keys work while no text field, dialog or menu has the keyboard. The command palette offers the same as "Review suggestion", "Hide duplicate warning" and "Not now", only while the Suggestions page shows a card.
  • With nothing to decide it reads "Nothing to decide."
  • While it loads it says "Loading what to decide". If the suggestions or the duplicates cannot be loaded it says "Could not load the open suggestions." or "Could not load the duplicates." with "Retry", and shows the cards of the other one.
  • A card that replaces another fades in quickly. With reduced motion it simply appears.

"Handled"

"Handled (3)" below "Duplicate files" opens the suggestions that are done: "Closed" and "Expired", each newest first. The number counts both.

  • It is closed when the page opens. While the number is not read yet, or could not be read, the button reads "Handled".
  • With no closed or expired suggestion it is not there at all.
  • Each row shows the summary as a link, then its progress, who made it and the time it was made. A closed one reads, for example, "1 applied, 1 rejected, 1 changed since suggested". The last part is left out when no item is stale.
  • An expired one reads, for example, "0 applied, 0 rejected, 1 not applied". "Not applied" counts the items nobody decided in time together with those whose file had changed.
  • An empty list reads "No suggestion has been closed yet." or "No suggestion has expired."
  • Each list shows the 50 newest suggestions in that state. "Load more" under a list shows the next 50, until every suggestion is listed.
  • If a list cannot be loaded it says "Could not load the suggestions."

Reviewing a suggestion

Choosing a suggestion opens the page "Suggested file changes".

  • Under the title: the summary, "suggested by {name}" and the state "Open", "Closed" or "Expired".
  • While items are pending, a line says "Nothing changes until you apply it." A plain member in the organization folder reads "Organization owners and admins apply the organization folder's suggestions." instead.
  • Each item is one sentence, for example "Rename mark.png to Brand mark.png", "Add tag badges to seal.png", "Remove tag draft from beta.png", "Move beta.png to Brand / Logos", "Move beta.png to the top level", "Set the alt text of stamp.png to Rubber stamp" or "Clear the alt text of stamp.png". The item's rationale, if it has one, is below it.
  • The file name in the sentence is the file's current name.

For someone who may decide, each pending item has a checkbox and two buttons:

  1. Tick the items to apply. With more than one pending item, "Select all changes" ticks them all.
  2. To apply an item with another value, choose "Change it" and type into "New value for {file name}". For a move, type the folder names with / between them; an empty value is the top level. Escape restores the suggested value.
  3. Choose "Apply". The button reads "Apply 1 change" or "Apply 2 changes" once items are ticked. Until then it is disabled and the page says "Select the changes to apply or reject."
  4. The page then says what happened: "2 applied", or "1 applied, 1 changed since suggested".
  • "Skip" on an item rejects that one item. The page says "1 rejected".
  • "Reject selected" rejects the ticked items.
  • Decided items stay on the page with their state at the end of the row: "Applied", "Rejected", "Changed since suggested" or, when the suggestion expired before anyone decided the item, "Expired". An applied item reads in the past tense with the value that was applied, for example "Added tag emblems to seal.png".
  • When the last item is decided, the state under the title becomes "Closed" and the buttons disappear.
  • A member who may not decide sees the same items with their states, and no checkbox, "Change it", "Skip", "Apply" or "Reject selected".

Messages when something is refused:

MessageWhen
"This suggestion is closed or expired, so nothing more applies."The suggestion closed or expired while the page was open.
"Someone decided some of these items already. The list is up to date now."Somebody else applied or rejected one of the ticked items first. Nothing of your request was applied. Tick again and repeat.
"That would make 1 file public. Only an owner or admin can make files public."A plain member applied a move into a shared folder. Nothing was applied.
"Could not update the suggestion."The request failed for a reason that is not yours, for example a lost connection. Other refusals show the reason the service gives.
"This suggestion does not exist, or you do not have access to it."The address names no suggestion of this place.
"Could not load the suggestion."The page could not be loaded.

The page does not reload when you come back to its window, so the items stay as you were reviewing them. What others changed in the meantime shows when you apply: files that changed come back as "Changed since suggested".

Duplicate files on the Suggestions page

Under the queue, the Suggestions page has the table "Duplicate files": the duplicate groups of the place that is open, newest first, one group a row. Its columns are "Files", "Copies" and "Size", then the group's button. On a narrow screen each row stacks its cells.

  • "Files" names the group's copies, one a line: the file's name as a link to its page, then "in" and where it is, such as "in Sorrel Copies / Brand" or "in Organization folder". The place is the workspace's name or "Organization folder", then the folders from the top down.
  • Copies of the open place come first, then the organization folder's, then those of your other workspaces.
  • "Copies" reads, for example, "2 copies", and "Size" "18.4 kB each". A group of more than 20 copies names the first 20 and adds a line with how many are not listed, such as "4 more not listed".
  • A copy in another workspace opens in that workspace.
  • "Hide" at the end of a row hides the group's warning for you. The group leaves the table, the number beside "Suggestions" drops by one, and the app says "Duplicate warning hidden" with "Undo".
  • "Undo" shows the group again. So does Ctrl+Z, or Cmd+Z on a Mac, while the message is on screen.
  • With no group left to look at, it reads "No duplicate files."
  • The table shows 50 groups. "Show more" under it shows the next 50.
  • While it loads it says "Loading duplicate files". If it cannot be loaded it says "Could not load the duplicate files." with "Retry".

Below the table, "Hidden (2)" opens the groups you have hidden. The number is how many there are.

  • It is closed when the page opens, and it is not there at all while you have hidden nothing.
  • Each hidden group shows its copies as above, with "Show again" in place of "Hide".
  • "Show again" returns the group to "Duplicate files" and to the number beside "Suggestions". The app says "Duplicate warning shown again".
  • Hidden groups are yours alone. Nobody else sees what you have hidden.
  • A plain member can hide and show again in the organization folder too. Hiding changes no file.
  • If a hide or a show fails, the app says "Could not hide the duplicate warning. Try again." or "Could not show the duplicate warning again. Try again." and the lists stay as they were.

The duplicate notice on a file's page

A file with copies elsewhere shows a notice marked "Duplicate" under its name. See Uploading.

  • "Hide" at the end of the notice hides the warning for you. The notice disappears and the app says "Duplicate warning hidden" with "Undo".
  • "Undo" brings the notice back.
  • The hide is for the whole group. The notice is gone from every copy's page, and the group moves under "Hidden" on the Suggestions page.
  • The notice comes back when a new copy appears, as the rules under Hiding a duplicate warning say, or when you choose "Show again" on the Suggestions page.
  • Everyone who can open the file gets "Hide", also a plain member on an organization folder file's page.
  • A hide does not change "Filter" > "Show" > "Duplicates" in a listing. It lists the file as before.

Suggestion cards

The details beside the file listing start with a card for each open suggestion of the place that is open.

  • Each card is labelled "Suggestion", shows the number of pending changes, for example "3 changes", the summary and the button "Review", which opens the suggestion.
  • At most three cards are shown, newest first. Below them a link such as "2 more suggestions" opens the Suggestions page.
  • With no open suggestion there is no card.
  • If the cards cannot be loaded, one card says "Could not load suggestions." with a way to retry.

For agents

Every operation exists twice: for a workspace and for the organization folder. The organization folder ones take organizationID where the workspace ones take workspaceID. Inputs and answers are the same.

OperationCapability ID (workspace / organization folder)MCP toolScope
POST .../library-proposalsworkspace.library_proposals.create / library.library_proposals.createworkspace_library_proposals_create / library_library_proposals_createfiles:write
GET .../library-proposalsworkspace.library_proposals.list / library.library_proposals.listworkspace_library_proposals_list / library_library_proposals_listfiles:read
GET .../library-proposals/{proposalID}workspace.library_proposals.get / library.library_proposals.getworkspace_library_proposals_get / library_library_proposals_getfiles:read
POST .../library-proposals/{proposalID}/rejectworkspace.library_proposals.reject / library.library_proposals.rejectworkspace_library_proposals_reject / library_library_proposals_rejectfiles:write
POST .../library-proposals/{proposalID}/applyworkspace.library_proposals.apply / library.library_proposals.applynonesession only

... is /v1/workspaces/{workspaceID} or /v1/organizations/{organizationID}/library. The arguments and the shape of a proposal are listed in MCP. A proposal can also be read as an MCP resource.

Reaching the organization folder

  • A credential reaches the organization folder of its own organization, whatever workspaces it lists. workspaces_list gives the organizationID to pass.
  • Every file, folder, tag and upload tool has an organization folder twin: library_files_search, library_files_get, library_folders_list, library_tags_list, library_uploads_create and so on. See MCP.
  • Reading the organization folder works for every member's credential with files:read.
  • Changing the organization folder works only when the credential's member is an owner or admin of the organization. A plain member's credential gets 403 FORBIDDEN there, also with files:write. Such a credential cannot make a library proposal either: the organization folder takes proposals from owners and admins only.

Make a proposal

Over REST, in a workspace:

curl -s -X POST \
  "$TALEWRIGHT/v1/workspaces/0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21/library-proposals" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Organize the launch assets",
    "requestID": "launch-assets-1",
    "items": [
      {
        "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
        "action": "rename",
        "payload": { "name": "alpha-logo.png" },
        "rationale": "Say what it is"
      },
      {
        "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
        "action": "add_tag",
        "payload": { "tag": "Logo" }
      },
      {
        "fileID": "0192f0b2-9c10-7e41-a2d5-6b1f0c3d4e02",
        "action": "move",
        "payload": { "folderPath": ["Brand", "Logos"] }
      },
      {
        "fileID": "0192f0b2-b7d4-7a90-9e13-0c5a8d6f7b03",
        "action": "set_alt_text",
        "payload": { "altText": "Gamma product shot on white" }
      }
    ]
  }'

The answer is 201 with the proposal:

{
  "id": "0192f1aa-3c5e-7b6d-8f20-4a9d1e2c3b40",
  "summary": "Organize the launch assets",
  "state": "open",
  "allowedActions": ["reject"],
  "createdAt": "2026-11-14T09:30:00Z",
  "createdBy": { "id": "0192e7c1-2f4b-7c10-9a8e-1d2c3b4a5f60", "fullName": "Ravi Admin" },
  "expiresAt": "2026-11-28T09:30:00Z",
  "closedAt": null,
  "items": [
    {
      "id": "0192f1aa-3c5f-7001-8a11-000000000001",
      "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
      "fileName": "alpha.png",
      "action": "rename",
      "payload": { "name": "alpha-logo.png" },
      "appliedPayload": null,
      "rationale": "Say what it is",
      "baseLockVersion": 1,
      "resultLockVersion": null,
      "state": "pending",
      "decidedAt": null,
      "decidedBy": null
    },
    {
      "id": "0192f1aa-3c5f-7001-8a11-000000000002",
      "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
      "fileName": "alpha.png",
      "action": "add_tag",
      "payload": { "tag": "logo" },
      "appliedPayload": null,
      "rationale": null,
      "baseLockVersion": 1,
      "resultLockVersion": null,
      "state": "pending",
      "decidedAt": null,
      "decidedBy": null
    }
  ]
}

(The other two items are left out here.)

  • The tag came back as "logo": payloads are normalized.
  • Both items for alpha.png have baseLockVersion 1. Both apply.
  • createdBy is the member the credential acts for.

The same over MCP, in the organization folder:

{
  "name": "library_library_proposals_create",
  "arguments": {
    "organizationID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17",
    "summary": "Tidy the library",
    "requestID": "tidy-library-1",
    "items": [
      {
        "fileID": "0192f0c4-1a2b-7c3d-8e4f-5a6b7c8d9e01",
        "action": "rename",
        "payload": { "name": "Brand mark.png" }
      },
      {
        "fileID": "0192f0c4-2b3c-7d4e-9f50-6b7c8d9e0f02",
        "action": "add_tag",
        "payload": { "tag": "badges" }
      },
      {
        "fileID": "0192f0c4-3c4d-7e5f-a061-7c8d9e0f1a03",
        "action": "set_alt_text",
        "payload": { "altText": "Rubber stamp" }
      }
    ]
  }
}

This works when the credential's member is an owner or admin of the organization.

Good practice for an agent:

  • Read each file first and send its lockVersion as baseLockVersion. Then the item is applied only if the file is still what you looked at.
  • Write a summary a person understands at a glance, and a rationale where the reason is not obvious.
  • Keep one topic per proposal. A person decides item by item, but reads the summary first.
  • Use [] as folderPath to move a file to the top level.
  • Do not wait for an answer in the same call. The proposal is applied when a person gets to it, within 14 days, or not at all.

Read it back

curl -s \
  "$TALEWRIGHT/v1/workspaces/0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21/library-proposals/0192f1aa-3c5e-7b6d-8f20-4a9d1e2c3b40" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"

After a person applied the rename and the tag, changed the alt text before applying it and left the move undecided, the items read (shortened):

{
  "state": "open",
  "allowedActions": ["reject"],
  "closedAt": null,
  "items": [
    {
      "action": "rename",
      "fileName": "alpha-logo.png",
      "payload": { "name": "alpha-logo.png" },
      "appliedPayload": null,
      "baseLockVersion": 1,
      "resultLockVersion": 2,
      "state": "applied",
      "decidedAt": "2026-11-15T08:02:11Z",
      "decidedBy": { "id": "0192e7c1-55aa-7d20-8b9f-2e3d4c5b6a70", "fullName": "Olga Owner" }
    },
    {
      "action": "add_tag",
      "fileName": "alpha-logo.png",
      "payload": { "tag": "logo" },
      "appliedPayload": null,
      "baseLockVersion": 1,
      "resultLockVersion": 3,
      "state": "applied"
    },
    {
      "action": "move",
      "fileName": "beta.png",
      "payload": { "folderPath": ["Brand", "Logos"] },
      "resultLockVersion": null,
      "state": "pending",
      "decidedAt": null,
      "decidedBy": null
    },
    {
      "action": "set_alt_text",
      "fileName": "gamma.png",
      "payload": { "altText": "Gamma product shot on white" },
      "appliedPayload": { "altText": "Gamma on white" },
      "resultLockVersion": 2,
      "state": "applied"
    }
  ]
}
  • fileName is the file's name now, so the first two items show the new name.
  • resultLockVersion went 2, then 3: one step per applied item.
  • appliedPayload holds what the person applied instead of the suggested alt text.
  • The proposal is still open, because the move is pending.

To follow many proposals, list them:

  • GET .../library-proposals returns a page, newest first. Each entry has id, summary, state, allowedActions, createdAt, createdBy, expiresAt, closedAt and the counts pending, applied, rejected and stale. It does not hold the items.
  • state filters by open, closed or expired.
  • Beside items and nextCursor the answer holds totalCount: the number of proposals in the state asked for, over all pages. Without state it counts every proposal of the workspace or organization folder.
  • limit is 1 to 100, 50 when left out. cursor takes the nextCursor of the page before. See Paging.

Reject

Withdraw what is left of a proposal:

curl -s -X POST \
  "$TALEWRIGHT/v1/workspaces/0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21/library-proposals/0192f1aa-3c5e-7b6d-8f20-4a9d1e2c3b40/reject" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
  • {} rejects every pending item. {"itemIDs": ["..."]} rejects only those.
  • The answer is 200 with the proposal. Here the move is now rejected, the state is closed and closedAt is set.
  • The MCP tools are workspace_library_proposals_reject and library_library_proposals_reject, with proposalID and optionally itemIDs.

Apply (a person, in a browser)

There is no tool that applies. For completeness, the session-only operation takes:

{
  "items": [
    { "itemID": "0192f1aa-3c5f-7001-8a11-000000000001" },
    {
      "itemID": "0192f1aa-3c5f-7001-8a11-000000000004",
      "payload": { "altText": "Gamma on white" }
    }
  ]
}

and answers 200 with {"applied": 2, "stale": 0, "proposal": {...}}.

Listing and hiding duplicates

OperationCapability ID (workspace / organization folder)MCP toolScope
GET .../duplicatesworkspace.duplicates.list / library.duplicates.listworkspace_duplicates_list / library_duplicates_listfiles:read
PUT .../files/{fileID}/duplicates/hiddenworkspace.duplicates.hide / library.duplicates.hidenonefiles:read
DELETE .../files/{fileID}/duplicates/hiddenworkspace.duplicates.show / library.duplicates.shownonefiles:read
  • The list takes hidden (true or false, optional), cursor and limit (1 to 100, default 50).
  • Hiding and showing take no body and answer 204 with no content. They act for the member the credential belongs to.
  • Hiding and showing are not MCP tools: they are a person's own preference. An agent reads the groups, and each group's hidden, with the list tool.
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/duplicates?hidden=false" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
{
  "items": [
    {
      "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "hidden": false,
      "fileCount": 3,
      "files": [
        {
          "id": "0192f1aa-3c5f-7001-8a11-0000000000a1",
          "name": "logo.png",
          "workspaceID": "0192e7c4-0b10-7a11-9c01-000000000001",
          "fileSpaceName": "Brand",
          "folderPath": [{ "id": "0192e7c4-0d20-7b12-8c02-000000000007", "name": "Logos" }],
          "sizeBytes": 48211
        },
        {
          "id": "0192f1aa-3c5f-7001-8a11-0000000000a2",
          "name": "logo-final.png",
          "workspaceID": "0192e7c4-0b10-7a11-9c01-000000000001",
          "fileSpaceName": "Brand",
          "folderPath": [],
          "sizeBytes": 48211
        },
        {
          "id": "0192f1aa-3c5f-7001-8a11-0000000000a3",
          "name": "Logo.png",
          "workspaceID": null,
          "fileSpaceName": "Library",
          "folderPath": [],
          "sizeBytes": 48211
        }
      ]
    }
  ],
  "nextCursor": null,
  "totalCount": 1,
  "hiddenCount": 0
}

Hide that group for the member, through any of its live copies in the workspace:

curl -s -X PUT \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/0192f1aa-3c5f-7001-8a11-0000000000a1/duplicates/hidden" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
  • The answer is 204. The list then reads totalCount 0 and hiddenCount 1, and the group reads hidden: true.
  • DELETE on the same path shows the warning again.
  • To clean up a group, trash the copies that are not needed (workspace_files_trash, library_files_trash). A copy in the trash leaves its group at once.

Edge cases

SituationWhat happensWhy
A plain member of the organization renames, trashes or restores an organization folder file, creates or renames a folder of the organization folder, or renames or deletes an organization folder tag403 FORBIDDEN. Nothing changes.Only organization owners and admins change the organization folder.
A member who is owner of a workspace changes the organization folder403 FORBIDDEN.The role in the organization counts in the organization folder, not a workspace role.
A member of the organization who belongs to no workspace reads the organization folder through the APIIt works.Reading the organization folder needs only membership of the organization.
Someone outside the organization asks for the organization folder, an organization folder file or a folder of the organization folder404 NOT_FOUND, exactly as for an organization that does not exist.Outsiders cannot tell the organization folder exists.
An organization folder file's ID is used in a workspace path, or a workspace file's ID in the library path404 NOT_FOUND.A file belongs to one place.
A workspace file is moved into a folder of the organization folder422 VALIDATION_FAILED. The file stays.Files do not move between places.
A key that lists one workspace reads the organization folderIt works, for the organization folder of the key's own organization.Every credential reaches its organization folder.
A plain member's key with files:write uploads to the organization folder or creates a folder of the organization folder403 FORBIDDEN.The key acts for its member, who only reads the organization folder.
An owner is made a plain member while an organization folder page is openTheir next change is refused and the app says "Only organization owners and admins can change the organization folder."The role is checked at each change.
A plain member makes a library proposal403 FORBIDDEN. An owner's or admin's is created.The organization folder takes proposals from owners and admins only.
A proposal names a file in the trash422 VALIDATION_FAILED on items. No proposal is made.Items must name live files.
A proposal names a file of another workspace, or an unknown ID422 VALIDATION_FAILED on items, the same answer for both.A foreign file must not be told apart from one that does not exist.
One of 300 items names a trashed fileThe whole proposal is refused.A proposal is made whole or not at all.
A rename item carries {"tag": "x"}422 VALIDATION_FAILED on payload.The payload must fit the action.
A payload has an extra key, such as {"name": "a.png", "note": "..."}422 VALIDATION_FAILED on payload.Unknown keys are refused.
A folderPath names 17 folders422 VALIDATION_FAILED on payload.Folders nest at most 16 levels.
A folder name in folderPath contains /, or is blank422 VALIDATION_FAILED on name.The folder naming rules.
rationale is an empty string, or holds a line break422 VALIDATION_FAILED on rationale.It is 1 to 2,000 characters on one line; leave it out when there is none.
A proposal has no items, or 501422 VALIDATION_FAILED on items.A proposal holds 1 to 500 items.
baseLockVersion is 0422 VALIDATION_FAILED on items.It must be at least 1.
baseLockVersion is older than the file's lockVersionThe proposal is made. The item ends stale when it is applied.The value is checked at apply, not at creation.
Two items rename the same file to two different namesBoth are accepted. If both are applied, the later item in the proposal's order wins.Items for one file apply one after the other.
The same requestID is sent again with the same body within 24 hours201 with the proposal the first request made, as it is now. No second proposal.Safe retries.
The same requestID is sent with another body, or for another workspace409 CONFLICT, reason REQUEST_REUSED.A requestID names one request.
A requestID used for a workspace proposal is used for a library proposal201 with a new proposal.Proposing in a workspace and proposing in the organization folder are two operations, and each keeps its own request IDs.
A request is retried with its requestID after one of its files was trashed201 with the proposal the first request made, as it is now.A retry is matched to the first request before its files are looked at.
A key tries to apply a proposal403 FORBIDDEN, reason HUMAN_APPROVAL_REQUIRED.Applying needs a person in a browser.
A file was renamed after the proposal was made, and an item for it is appliedThe item becomes stale: "Changed since suggested". The newer name stays.The file is no longer what the item was based on.
A file got a new version after the proposal was madeIts items still apply.A new version does not raise the file's lockVersion.
A file was moved to the trash after the proposal was madeIts items become stale when applied. The file stays in the trash, unchanged.Only live files are changed.
That file is restored before the items are appliedThe items still become stale.Trashing and restoring both raise the file's lockVersion.
A file named by a proposal is deleted for goodIts items are removed from the proposal. If no pending item is left, the proposal closes at that moment. A proposal can end up closed with no items at all.Nothing of a deleted file is kept, and a proposal with nothing to decide is not left open.
Two items for one file are applied togetherBoth apply. The file's lockVersion rises by two.Each item expects the lockVersion the one before left.
One item for a file is applied today and the other tomorrow, and nobody touched the file in betweenBoth apply.The second expects what the first left.
Between those two, somebody edits the fileThe second item becomes stale.The file changed outside the proposal.
add_tag for a tag the file already hasThe item is applied. The tags are the same. The file's lockVersion still rises.Applying is recorded as a change.
add_tag on a file that already has 50 tags422 VALIDATION_FAILED on tags. Nothing of the request is applied.A file has at most 50 tags, and a refused item refuses the request.
remove_tag for a tag the file does not haveThe item is applied. Nothing is removed.There is nothing to take off.
move to ["brand", "Logos"] while a folder "Brand" existsThe file goes to Brand / Logos. "Logos" is created once; "Brand" is reused.Folder names match ignoring case.
move into a folder that is in the trashA new folder with that name is created and the file goes there.Trashed folders do not count; their name is free.
move to the folder the file is already inThe item is applied. The file stays where it is.The destination is what was asked for.
A plain workspace member applies a move into a public folder, for a file whose status allows public use403 FORBIDDEN, reason MAKES_FILES_PUBLIC. Nothing of the request is applied. An owner or admin applying the same item makes the file public.Only owners and admins make files public.
A plain workspace member applies a move that takes a file out of a public folderIt is applied. The file's public link stops.Stopping links needs no special role, and applying confirms the move.
A rename is applied to a file with a public linkThe link keeps working.The name in a public link is only decoration.
The person applying changes a tag to "Emblems" with "Change it"The file gets the tag "emblems". The item keeps its payload and gets appliedPayload {"tag": "emblems"}.What was applied is recorded next to what was suggested.
The changed value is not valid, for example an empty name422 VALIDATION_FAILED. Nothing of the request is applied.A changed payload must fit its action.
Two people apply the same item at the same momentOne applies it. The other gets 409 CONFLICT, reason ITEM_DECIDED, and nothing of their request is applied.Decisions on one proposal are handled one after the other.
A request names five pending items and one decided item409 CONFLICT, reason ITEM_DECIDED. The five stay pending.A request with a decided item is refused whole.
A request names an item of another proposal, or an unknown item ID422 VALIDATION_FAILED on items.Items must belong to the proposal.
A request names the same item twice, or no item422 VALIDATION_FAILED on items.1 to 500 distinct items.
reject is sent with "itemIDs": []422 VALIDATION_FAILED on items.Leave itemIDs out to reject everything pending.
The last pending item is rejectedThe proposal is closed.A proposal closes when nothing is pending.
A closed proposal is applied or rejected409 CONFLICT, reason CLOSED.Nothing is left to decide.
A proposal passes its 14 days with items pendingIt reads expired and answers CLOSED to apply and reject. Its pending items turn stale within about an hour.Proposals do not stay open forever.
A proposal was fully decided on day 3It reads closed on day 3 and on day 30.Only a proposal with pending items expires.
A proposal of another workspace is read, applied or rejected through your own workspace404 NOT_FOUND, as for an unknown ID.A proposal belongs to one place.
A plain member opens an organization folder suggestion in the appThey read every item and its state. No checkbox, "Apply" or "Reject selected" is offered.Members read the organization folder.
A workspace is deleted while it has open suggestionsThey are unreachable with the workspace, like everything in it. A restore brings them back; their 14 days are not paused meanwhile.See Workspaces.
The same bytes are in your workspace and in a workspace you cannot openNo group is listed for you, and the file reads no duplicates.A group needs two copies the reader can open.
The same bytes are in your workspace and in the organization folderThe workspace and the organization folder both list the group, each with its own copy first.A place lists a group when one copy is there.
You hide a group, then a colleague uploads the same bytes againThe group reads hidden: false again and counts in totalCount.A hide covers the copies you could open when hiding.
You hide a group of three copies, then one copy is trashedThe group stays hidden, with two copies.A copy that leaves does not end a hide.
That copy is restored from the trashThe group stays hidden.The restored copy was one of the copies hidden.
A copy that was already in the trash when you hid the group is restoredThe group shows the warning again.That copy was not among the copies hidden.
You hide a group, then join a workspace that holds another copyThe group shows the warning again.You can now open a copy you could not when hiding.
One of two copies gets a new version with other bytesThe group is gone. Each file reads no duplicates.Only current versions are compared.
Two people hide the same group, and one shows it againIt stays hidden for the other.Hides are per person.
An owner looks at a member's duplicate groupsThe owner sees their own hidden values, never the member's.Nobody reads or changes another person's hides.
A key that lists one workspace hides a group whose third copy is in another workspace of its memberThe key sees the group hidden. The member's browser session still sees the warning.The key hid the copies it can open.
A hide is asked for a file in the trash, a file of another place, or an unknown ID404 NOT_FOUND, the same answer for all three.Only a live file of the place can be named.
A member of the organization who is in no workspace hides an organization folder file's warningIt works.Reading the organization folder is enough.
A group has 30 copiesfileCount is 30 and files names the first 20.A group names at most 20 copies.
In the app, you hide a group on the Suggestions page of a workspace, and one copy is in the organization folderThe group moves under "Hidden" on the organization folder's Suggestions page too, and the number beside "Suggestions" drops there as well.A hide is for the whole group, in every place you open.
In the app, you choose "Hide" on a file's notice and then "Undo"The notice is back, and so is the group in "Duplicate files"."Undo" shows the warning again.
In the app, you hid a warning yesterday and want it backOpen "Suggestions", then "Hidden", and choose "Show again".The message with "Undo" is gone after a few seconds; the hidden list stays.
In the app, a place has 3 open suggestions and 2 duplicate groups, one of them hiddenThe number beside "Suggestions" is 4.Hidden groups do not count.
In the app, your colleague hid a group you have notYou still see the notice and the group, and your number counts it.Hides are per person.

Errors

CodeStatusWhenWhat to do
UNAUTHENTICATED401Not signed in, or an invalid credential.Sign in or use a valid credential.
FORBIDDEN403A plain member changes the organization folder, or makes, applies or rejects a library proposal.Ask an organization owner or admin.
FORBIDDEN, reason HUMAN_APPROVAL_REQUIRED403A credential applies a proposal. Message: "Approvals need a person signed in with a browser".A person applies it in the app.
FORBIDDEN, reason INSUFFICIENT_SCOPE403The credential lacks files:read (list and read proposals; list duplicate groups, hide and show their warning) or files:write (create, reject). details.requiredScopes names the scope.Use a credential with that scope.
FORBIDDEN, reason MAKES_FILES_PUBLIC403A plain workspace member applies a move that would make files public. details.becomePublic counts them. Nothing was applied. Message: "This would make files public; only an owner or admin can do that".Have an owner or admin apply the item, or reject it and apply the rest.
NOT_FOUND404The workspace, organization or proposal is unknown or out of your reach. A duplicate warning is hidden or shown for a file that is unknown, in the trash or not in this workspace or organization folder.Check the IDs with workspaces_list and a proposal list.
CONFLICT, reason CLOSED409A closed or expired proposal is applied or rejected. Message: "This suggestion is closed or expired".Make a new proposal.
CONFLICT, reason ITEM_DECIDED409A named item is no longer pending. Message: "Some selected items were already decided". Nothing was applied or rejected.Read the proposal again and name only pending items.
CONFLICT, reason REQUEST_REUSED409A requestID is repeated with another body or for another workspace within 24 hours.Use a new requestID for a new request.
VALIDATION_FAILED on summary422The summary is blank, over 500 characters or holds a control character.Correct it.
VALIDATION_FAILED on items422Creating: not 1 to 500 items; an item names a file that is not live in this place; baseLockVersion below 1. Applying or rejecting: not 1 to 500 distinct items; an item that is not of this proposal.Correct the list.
VALIDATION_FAILED on payload422A payload does not fit its action, or folderPath names more than 16 folders.Send the payload the action takes.
VALIDATION_FAILED on tags422A tag is blank, over 50 characters or holds a control character or a comma; or applying would give a file more than 50 tags.Correct the tag, or free a tag on the file.
VALIDATION_FAILED on name422A file name or a folder name in folderPath is blank, over 200 characters or holds a control character; a file name holds / or \, or a folder name holds /.Correct the name.
VALIDATION_FAILED on altText422The alt text is over 1,000 characters or holds a control character.Shorten it.
VALIDATION_FAILED on rationale422The rationale is blank, over 2,000 characters or holds a control character.Correct it, or leave it out.
VALIDATION_FAILED on requestID422Not 1 to 64 letters, digits, - or _.Correct it.
VALIDATION_FAILED422The body is not the expected JSON, action is not one of the five, a fileID or an item ID in the body is not a UUID, or a list request has an invalid state, hidden, cursor or limit.Correct the request.
RATE_LIMITED429A credential passed its request limit.Wait for Retry-After seconds.

See Errors for the shape of every error, and CONFLICT for every reason.

Limits

WhatValue
Organization folders per organization1
Items in one suggestion1 to 500
Summary1 to 500 characters, one line
Rationale of an item1 to 2,000 characters, one line; optional
Tag in add_tag and remove_tag1 to 50 characters once normalized, no comma
Tags on one fileUp to 50
File name in rename1 to 200 characters, no / or \
Folders in a folderPathUp to 16; each name 1 to 200 characters, no /
Alt text in set_alt_textUp to 1,000 characters
Items in one apply or reject request1 to 500, each once
A suggestion stays open14 days from when it was made
Pending items of an expired suggestion turn staleWithin about an hour after the expiry
requestID1 to 64 letters, digits, - or _; remembered for 24 hours
Page size of a proposal list1 to 100, default 50
Suggestions shown per list in the appThe 50 newest, and 50 more with each "Load more"
Suggestion cards beside the file listingUp to 3
Copies needed for a duplicate group2 or more that the reader can open, at least 1 of them in the place
Copies named in one duplicate groupUp to 20; fileCount gives the full number
Page size of a duplicate group list1 to 100, default 50
Hides of one duplicate group per person1

See Limits.

Questions and answers

What is the organization folder for? Files the whole organization uses, whatever the workspace: logos, brand guides, fonts, templates. Put a file there once instead of copying it into every workspace.

Who can see the organization folder? Every member of the organization, including members who belong to only one workspace.

Who can change the organization folder? The organization's owners and admins. Everyone else reads and downloads.

I am owner of my workspace. Why can I not upload to the organization folder? The organization folder belongs to the organization. Only your role in the organization counts there, and that is member.

Why is there no "Upload" or "New folder" in the organization folder? You are a plain member of the organization. Ask an owner or admin to add the file, or to make you an admin.

Where is the organization folder in the app? In Files & Assets, choose the organization's name at the top of the tree "Folders". Or run "Go to Organization folder" from the command palette.

Is the organization folder different in each workspace? No. There is one organization folder per organization. Every workspace shows the same one.

Can I move a file from my workspace into the organization folder? No. Files do not move between a workspace and the organization folder, or between workspaces. Download the file and have an owner or admin upload it to the organization folder. That makes a new file there, with its own history and its own link; the file's details then name the other copy as a duplicate.

Are tags and folders shared between the organization folder and workspaces? No. Each has its own folders and tags, and its own statuses and custom fields.

What does "Every workspace" mean in the organization folder? The organization folder, or a folder in it, is not public. Everyone in the organization can open it, from any workspace. An organization folder file's "Sharing" section says the same in words: "Only people in the organization can open it."

Can an organization folder file have a public link? Yes, with the same rules as any file. An organization owner or admin shares it, and its status must allow public use. See Sharing and public links.

Does the organization folder have its own trash? Yes. Organization owners and admins trash, restore and delete for good there. See Trash and restore.

Can I delete the organization folder? No. It goes with the organization.

Can an agent work in the organization folder? Yes. Every credential reaches the organization folder of its organization and can read it with files:read. It can change it only when its member is an owner or admin of the organization.

What is a suggestion? A list of proposed changes to files that waits for a person. Nothing changes until someone applies it.

What is the difference between a suggestion and a library proposal? None. "Suggestion" is the word in the app. "Library proposal" is the name in the API and in MCP.

Is a "library proposal" only for the organization folder? No. Despite the name, every workspace has them too.

What can a suggestion change? Tags, the folder a file is in, a file's name and its alt text. Nothing else: not statuses, not sharing, not descriptions, captions or custom fields, and it cannot trash or delete anything.

How do I make a suggestion in the app? You do not. The app reviews suggestions; it has no form to write one. They come in through the API or MCP, usually from an agent.

Can an agent apply its own suggestion? No. Applying needs a person signed in with a browser. An agent can make suggestions, read them and reject them.

Why would an agent suggest instead of just changing the files? With files:write it can change them directly. A suggestion is for changes a person should look at first, or for the organization folder when the reviewer should decide item by item.

Who can apply a suggestion? In a workspace, everyone who can open it. In the organization folder, organization owners and admins.

Do I have to apply everything? No. Tick the items you want. The others stay pending until someone applies or rejects them, or the suggestion expires.

Can I change what is suggested before applying? Yes. "Change it" lets you type another value for that item. The suggestion keeps both what was suggested and what you applied.

What does "Changed since suggested" mean? The file was changed after the suggestion was made, or is in the trash, so the item was not applied. It is the API's stale. The file is as it was; make a new suggestion if the change is still wanted.

I applied two changes and the page says "1 applied, 1 changed since suggested". What happened? One file was edited by someone after the suggestion was made. That item was skipped to avoid overwriting their work. The other was applied.

Can I undo an applied suggestion? There is no undo for a suggestion. Each applied item is an ordinary change to a file: rename it back, move it back or change the tags again.

What happens to a suggestion nobody looks at? It expires 14 days after it was made. Its undecided items are marked as not applied and nothing changes.

Where did my expired suggestion go? It is under "Handled" > "Expired" on the Suggestions page. Its address still opens it, and the API lists it with state=expired.

Can a suggestion make a file public? Not by itself: it cannot change a status or general access. A move into a shared folder makes a file public if its status allows public use. Only an owner or admin can apply such a move.

I am a member and applying says "That would make 1 file public. Only an owner or admin can make files public." What now? Nothing was applied. Untick that move and apply the rest, or ask an owner or admin to apply it.

Can I reject a suggestion somebody else made? Yes, if you may reject in that place: everyone in a workspace, owners and admins in the organization folder.

Does anyone get an email about a suggestion? No. Open suggestions show as a count on "Suggestions" and as cards beside the file listing.

Is applying recorded? Yes. The audit trail records who made, applied and rejected a suggestion, and each applied item as a change to its file that names the suggestion.

How many changes fit in one suggestion? 500. Make several suggestions for more.

What is a duplicate group? Live files whose current versions have exactly the same bytes, in places you can open. Names do not matter.

Where do I see the duplicate files of a workspace or the organization folder? On its Suggestions page, under "Duplicate files". Each group names its copies with where they are and links to each.

Can I hide a duplicate warning I do not care about? Yes. Choose "Hide" on the notice on the file's page, or on the group under "Duplicate files" on the Suggestions page. Through the API it is PUT .../files/{fileID}/duplicates/hidden for any copy of the group. It hides the warning for you alone.

I hid a duplicate warning and it is back. Why? A new copy of the same file appeared. A hide covers the copies you could open when you hid the group, so a new copy shows the warning again.

How do I get a hidden warning back? Right after hiding, choose "Undo". Later, open "Suggestions", then "Hidden", and choose "Show again". Through the API it is DELETE .../files/{fileID}/duplicates/hidden for any live copy. Hidden groups stay in the list with hidden: true, so they can be found.

What does the number beside "Suggestions" count? The open suggestions of the place plus its duplicate groups you have not hidden.

Does hiding a duplicate warning hide it for my colleagues? No. Each person hides for themselves.

Does hiding delete or merge anything? No. Every copy stays as it is. To get rid of a copy, move it to the trash.

Which number is the count of duplicates I have not dealt with? totalCount of the duplicate group list: the groups you have not hidden.