Trash and restore
Summary
Removing a file or a folder does not delete it. It moves to the trash of its workspace, or of the organization folder, and waits there for 30 days. During that time it can be restored, and it comes back as it was. After 30 days it is deleted for good, with every version.
Each workspace has its own trash. The organization folder has one too.
Moving something to the trash is an everyday action: everyone who may change a file may trash and restore it. Deleting for good before the 30 days are over is not: only owners and admins can do that, and only in a browser.
One rule deserves attention. A restore puts files back as they were. A file that was public when it went to the trash is public again after the restore, whoever restores it. But a restore never makes a file public that was not public before, unless an owner or admin does it.
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) |
|---|---|---|---|---|
| Move a file to the trash | Every member of the workspace | Owners and admins | Yes | Yes (files:write) |
| Move a folder and its content to the trash | Every member of the workspace | Owners and admins | Yes | Yes (files:write) |
| See the trash | Every member of the workspace | Every member of the organization | Yes | Yes (files:read) |
| Restore a file or a folder | Every member of the workspace | Owners and admins | Yes | Yes (files:write) |
| A restore that would make public a file that was not public when trashed | Owners and admins | Owners and admins | Yes | Yes (files:write and files:approve) |
| Delete a trashed file or folder for good | Owners and admins | Owners and admins | Yes | No |
| Empty the trash | Owners and admins | Owners and admins | Yes | No |
- "Member of the workspace" includes organization owners and admins. In a workspace the role that counts is the effective workspace role. In the organization folder it is the organization role.
- A credential that asks to delete for good or to empty the trash gets
403 FORBIDDENwithdetails.reasonSESSION_REQUIRED. Permanent deletion needs a person in a browser. - Through a credential, a restore that would make files public also needs the member's email to be verified.
- No verified email is needed to trash, to restore or to delete for good in a browser.
- A credential must list the workspace. It reaches the organization folder of its own organization.
- The full matrix is in Roles and permissions.
How it works
Moving a file to the trash
- The request names the file and its
expectedLockVersion. See Lock versions. - The answer is
204. - From that moment the file is trashed:
- It leaves every listing, search result and folder count.
- It is no longer named as a duplicate of other files.
deletedAtis the time it was trashed.purgeAfteris 30 days later: the time it is deleted for good.- Its
lockVersiongoes up by one.
- A file or folder that is not in the trash is called live.
- The file remembers where it was: its folder, its name, its status, its details, its tags and field values, its own general access and every version.
- The file also remembers whether it was public at that moment. That decides what a restore may do. See The restore rule.
- Nothing is thrown away yet.
Moving a folder to the trash
- The request names the folder and its
expectedLockVersion. - The folder goes to the trash together with every live folder and every live file inside it, at every level.
- The answer is
200withpublicLinkCount: how many public links stopped because of it. - The folder and what it took along form one item in the trash. They are restored together and deleted for good together.
- Files and folders that were already in the trash on their own stay separate items. They are not part of the folder's item.
- The folder's name is free at once. A new folder with that name can be created in the same place.
- Each file inside remembers whether it was public, as a single file does.
- An empty folder can be trashed like any other.
What a trashed file can and cannot do
| Still works | Refused |
|---|---|
Reading the file by its ID. deletedAt and purgeAfter are set. | Changing its name, details, tags, folder or field values: 409 CONFLICT, reason IN_TRASH |
| Listing its versions | Setting its status: 409 CONFLICT, reason IN_TRASH, for the whole batch |
| Downloading a version through the API | Making it public or restricted: 409 CONFLICT, reason IN_TRASH |
Listing it with trash=true | Replacing it: 409 CONFLICT, reason IN_TRASH |
| Restoring it | Trashing it again: 409 CONFLICT, reason IN_TRASH |
Asking for a temporary link to it: 409 CONFLICT, reason IN_TRASH | |
Including it in a ZIP download: 404 NOT_FOUND |
- A trashed file has no
thumbnailURL, nopreviewURLand nopublicURL, andpublicisfalse. Its ownvisibilitystill reads what it was. - A trashed folder refuses renaming, moving and a change of general access
with
409 CONFLICT, reasonIN_TRASH. - Listing the subfolders of a trashed folder answers
404 NOT_FOUND. - Favorites of a trashed file or folder are hidden until it is restored.
- A trashed file keeps a field value only while the field and the option exist. Deleting a custom field, or an option of one, clears the value on the files in that workspace's or the organization folder's trash as well as on its live files. A restored file comes back without it.
- The field list tells how many such files a deletion reaches: every field
and option reads
trashedFileCount, the files in that workspace's or the organization folder's trash that have a value for the field, or that option. It is a number only for an owner or admin of that workspace or the organization folder signed in to the app. For a member and for every credential it isnull. See Fields and tags. - The same holds for a status: a trashed file whose status is deleted comes back without a status. See Statuses.
What happens to links
- Public links stop. The public link of a trashed file answers "not found", exactly like a link that never existed. This holds whether the file was public by itself or through a public folder.
- The address is kept. After a restore, the same public link works again, if the file is public again.
- Temporary links stop for good. A temporary download or preview link made before the file was trashed stops working at once. It does not come back with a restore. Ask for a new one.
- ZIP downloads leave it out. A ZIP link made earlier still downloads, without the files that were trashed since.
- A public folder that is trashed loses its gallery page, and the public links of the files inside stop. A restore brings both back.
The trash listing
- The trash of a workspace or of the organization folder lists what was trashed on its own: single files, and folders with what they took along.
- A file that went to the trash inside a folder is not listed separately. The folder stands for it.
- Trashed files come newest first. Trashed folders come most recently trashed first.
- A trashed folder shows
folderCountandfileCount: how many folders and files it took along, at every level. - Both come 50 a page (1 to 100 with
limit). - An item whose 30 days are over, or that was deleted for good on request, is no longer listed, even if its removal is still under way.
Restoring a file
- Restoring needs no
expectedLockVersion. - The answer is
200with the restored file. - The file returns to the folder it was in, with its name, status, details, tags, field values, own general access and every version.
- If that folder is no longer live, because it was trashed or deleted for good in the meantime, the file returns to the top level.
deletedAtandpurgeAfterare cleared. ItslockVersiongoes up by one.- It is listed, searchable and counted again at once.
- File names need not be unique, so a restore never fails because of a name.
- Whether it is public again is decided by the restore rule.
The checks happen in this order:
- Not signed in:
401 UNAUTHENTICATED. - The workspace or organization is unknown or out of your reach:
404 NOT_FOUND. - The organization folder, and you are not an owner or admin:
403 FORBIDDEN. - The file is unknown, or it was deleted for good, or its 30 days are
over:
404 NOT_FOUND. - The file is not in the trash:
409 CONFLICT, reasonNOT_IN_TRASH, message "The file is not in the trash". - The file went to the trash inside a folder:
409 CONFLICT, reasonNOT_IN_TRASH, message "The file went to the trash with its folder; restore the folder". - The restore would make the file public and you may not do that:
403 FORBIDDEN. See The restore rule. - Otherwise it is restored.
Restoring a folder
- Restoring a folder brings back the folder and exactly what it took along: every subfolder and file that went to the trash with it, in the same arrangement.
- It does not bring back items that were trashed on their own before the folder was. Those stay in the trash as their own items.
- The answer is
200with the restored folder. - The folder returns into its parent folder, if that is live and the result still fits within 16 levels. Otherwise it returns to the top level.
- Only a folder trashed on its own can be restored. A subfolder that went
along with its parent answers
409 CONFLICT, reasonNOT_IN_TRASH: restore the parent. - A restore is all or nothing. If it is refused, nothing comes back.
Name conflicts on restore
- While a folder is in the trash, its name is free. Someone may have created another folder with that name in the same place.
- A restore is not refused for that. The restored folder gets a numbered name instead: "Campaigns" comes back as "Campaigns (2)". If that is taken too, "Campaigns (3)", and so on.
- Case does not matter: a live "campaigns" is enough to make "Campaigns" come back as "Campaigns (2)".
- The folder that took the name keeps it. Nothing else is renamed.
- If the numbered name would be longer than 200 characters, the original name is shortened to make room.
- You can rename the restored folder afterwards.
- Files never get numbered names. Two files with the same name can sit in one folder.
- The subfolders that come back inside a restored folder keep their names.
The restore rule
A restore puts files back as they were.
- A file that was public when it was trashed comes back public, at the
same public link, for anyone who may restore it. That includes a member
of the workspace and a credential with only
files:write. Nobody is asked to confirm. - This covers a file that was public by its own general access and a file that was public through a public folder, also when that folder went to the trash with it.
- A restore that would make any other file public is refused for a
member, and for a credential without
files:approve. Such a file was not public when it was trashed, but would be public where it comes back to. For example, while the file was in the trash:- its folder was moved under a public folder, or
- its folder, or a folder above it, was made public, or
- its status started to allow public use, and it belongs in a public folder.
- Owners and admins restore without being asked. For them a restore always goes through, and the files that end up public are public.
- A file that was public and no longer can be comes back restricted. If its status stopped allowing public use while it was in the trash, or its folder is no longer public, it is restored without a public link. That is never a reason to refuse the restore.
- A restore that makes nothing public is never refused for this reason.
What a refused restore answers:
| Caller | Answer |
|---|---|
| Member, in a browser | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC. details.becomePublic counts the files that would newly become public. |
Credential without files:approve | 403 FORBIDDEN, reason INSUFFICIENT_SCOPE, details.requiredScopes ["files:approve"]. |
Credential with files:approve, acting for a member | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC. |
Credential with files:approve, acting for an owner or admin whose email is not verified | 403 EMAIL_NOT_VERIFIED. |
becomePubliccounts only the files that would newly become public. Files that were public when trashed are not counted.- A refused restore restores nothing. For a folder that holds one file that was public and one that would newly be public, the whole folder stays in the trash until an owner or admin restores it.
- The same rule guards moves. See Moves that change who can open files.
Deleting for good
Owners and admins can delete a trashed item for good without waiting for
the 30 days. Deleting for good is also called purging: the API's
operations are named purge, and purgeAfter is the time after which a
trashed item is purged by itself.
- Only something that is in the trash can be deleted for good. There is no way to delete a live file for good in one step.
- It needs an owner or admin, in a browser.
- The answer is
202: the deletion is accepted and carried out in the background. - From that moment the item is gone for everyone:
- It leaves the trash listing.
- Reading the file, its versions and their content answers
404 NOT_FOUND. - It can no longer be restored:
404 NOT_FOUND.
- Then the file is removed with every version, its previews and its stored content.
- Deleting a trashed folder for good deletes the folder and everything it took along.
- A file that went to the trash inside a folder cannot be deleted for good
by itself:
409 CONFLICT, reasonNOT_IN_TRASH. Delete the folder. - A live file or folder answers
409 CONFLICT, reasonNOT_IN_TRASH. - Deleting for good cannot be undone.
Emptying the trash does the same for everything in the trash of one
workspace, or of the organization folder, in one step. It answers 202. An
empty trash can be emptied: nothing happens.
After 30 days
purgeAfteris set when the item is trashed and does not move afterwards, except when an owner or admin deletes the item for good.- At
purgeAfterthe item can no longer be restored and leaves the trash listing. - Shortly after, it is removed for good, as if it had been deleted on request: the file with every version, its previews and its stored content.
- A trashed folder is removed once the files it took along are removed.
- An item that was trashed on its own and whose folder is removed in this way is not lost with it. Restoring it puts it at the top level.
- Restoring an item and trashing it again starts a new 30 days.
- A file that was restored before its time is never deleted by the earlier countdown.
- Removal for good is recorded in the audit trail without a person. See Audit trail.
The trash and deleted workspaces
- The trash belongs to its workspace. Deleting the workspace hides its trash with everything else.
- The 30 days of a trashed file keep running while its workspace or its organization is deleted. When they end, the file is deleted for good, also then.
- A workspace that is restored comes back with whatever is still in its trash.
- See Workspaces and Deleting and restoring.
The trash and exports
- An organization export leaves out trashed files. See Export.
Trash in the organization folder
- The organization folder has its own trash, separate from every workspace.
- Only organization owners and admins move organization folder files and folders to the trash, restore them, delete them for good and empty the organization folder's trash.
- Every member of the organization can read the organization folder's trash through the API, as they can read the organization folder.
- The rules are otherwise the same as in a workspace.
- An organization folder file's public link stops and comes back in the same way.
In the app
Moving to the trash
"Move to trash" is offered wherever you may change an item:
- in the menu of a file or folder, from "File actions for {name}", "Folder actions for {name}" or a right-click,
- in the bar "Selected files", for everything selected,
- on a file's page, above the preview,
- in the command palette,
- with Cmd+Backspace on a Mac or Ctrl+Backspace elsewhere, for the selection or the open file.
There is no confirmation. The item is trashed at once. When the answer takes longer than 300 ms, for example for a large folder, the app says "Moving {name} to Trash…" (or "Moving 3 files to Trash…") until it is done; a quicker answer shows nothing in between. The same notice shows for "Moving {name}…" when items are moved, and "Setting the status of {n} files…" when a status is set on several files. Then the app says:
- "Moved {name} to Trash" for one item,
- "Moved 3 files to Trash", "Moved 2 folders to Trash" or "Moved 5 items to Trash" for several,
- and below it, when public links stopped: "1 public link stopped working until restored." or "{n} public links stopped working until restored."
The message offers "Undo" for 8 seconds. Cmd+Z or Ctrl+Z does the same.
- "Undo" restores what was just trashed. The app says "Restored {name}".
- If something cannot be restored that way: "Some items could not be restored. Restore them from Trash."
- If undoing would make files public and you may not do that, the app shows the refusal described under Restoring in the app.
After trashing:
- A file's page closes and the app opens the folder the file was in.
- An open folder that you trashed from its own menu is replaced by its parent folder.
- The selection is cleared.
When a selection holds several items, each is trashed by itself. If some fail, the others are still trashed, and the app says what went wrong:
| Text | When |
|---|---|
| "{name} changed since you opened it. It is up to date now; try again." | Someone changed the item first. |
| "Only organization owners and admins can change the organization folder." | You may not change the organization folder. |
| "Could not delete {name}." | Another failure. |
On a file's page, a file that changed since you opened it shows "This file changed since you opened it. Reloading keeps your unsaved edits." with "Reload latest" instead, and "Move to trash" is disabled until you reload.
An item that someone else trashed a moment before you is not trashed again. The app says "Already in Trash: {name}" (or the count, for several) and offers no "Undo" for it: "Undo" restores only what you trashed yourself. The page still moves on as after a trash of your own.
The Trash page
"Trash" is in the navigation of Files & Assets, below "All files" and "Suggestions". It opens the trash of the workspace you are in. In the organization folder it opens the organization folder's trash, and is shown to owners and admins.
- Trashed folders are listed first, then trashed files.
- A file's line reads, for example: "Image · From Campaigns / Spring ·
Deleted Nov 14, 2026, 3:05 PM · Kept until Dec 14, 2026".
- The first part is the kind of file: "Image", "Video", "PDF", "Font", "Design file" or "File".
- "From {folders}" is where it was. A file from the top level reads "From the top level".
- "Kept until" is the day it is deleted for good.
- A folder's line reads, for example: "Folder · 2 folders · 14 files · Deleted ... · Kept until ...". The counts are what it took along.
- A folder is one row. The files inside it are not listed.
- 50 files are shown at first. "Load more" shows the next 50.
- An empty trash says "Trash is empty."
- If the trash cannot be loaded: "Could not load the trash." with "Retry".
Restoring in the app
- Each row has "Restore". The app says "Restored {name}".
- To restore several, tick their boxes ("Select {name}") and choose "Restore" in the bar "Selected items". Shift-click selects a range, and "Clear selection" or Escape clears it.
- A restored file is back in its folder. A restored folder is back with everything that was in it.
- If a folder's name was taken meanwhile, it comes back with a number, such as "Campaigns (2)". The app does not point this out.
A trashed file also has its own page. It says "This file is in the trash. It will be deleted permanently on {date and time}." and offers "Restore". The page shows no preview, no form "File details" and no "Download" button. Its "Details" still show "Location" on the left, "Properties" on the right and "History" last, across both columns. On a narrow window they are one column in that order.
When a folder above the file is in the trash, the page says "This file and its folder {folder} are in the trash." and offers "Restore folder" instead. That restores the folder with everything it took along. A file that was trashed by itself before its folder stays in the trash then, and its page offers "Restore".
Messages when a restore is refused:
| Text | When |
|---|---|
| "That would make 1 file public. Only an owner or admin can make files public." | The restore would make a file public that was not public when it was trashed. With several: "That would make 3 files public. ...". |
| "{name} is no longer in the trash." | Someone else restored it, or it is not a trash item of its own. |
| "You cannot restore {name}." | The restore was refused in a workspace. |
| "Only organization owners and admins can change the organization folder." | The restore was refused in the organization folder. |
| "Could not change {name}. Try again." | Another failure. |
| "Could not restore the file." or "Could not restore the folder." | On the trashed file's own page, another failure. |
When a restore is refused for making files public, the item stays in the trash. Ask an owner or admin to restore it.
Deleting for good in the app
Owners and admins see two more controls on the Trash page.
"Delete permanently" on a row:
- The dialog asks "Delete {name} permanently?" and says "It cannot be restored afterwards."
- "Delete permanently" confirms. "Cancel" closes the dialog.
- The app says "Deleting {name} permanently". The row reads "Deleting permanently" until it disappears.
"Empty trash", above the list while the trash holds anything:
- The dialog asks "Empty the trash?" and says "Everything in the trash is deleted permanently and cannot be restored."
- "Empty trash" confirms. "Cancel" closes the dialog.
- The app says "Emptying the trash". Every row reads "Deleting permanently" until it disappears.
- Members do not see "Delete permanently" or "Empty trash".
- If a member's request is refused all the same, the app says "Only owners and admins can delete files permanently."
- If emptying fails: "Could not empty the trash. Try again."
- There is no way to select several rows and delete them permanently together. Delete them one by one, or empty the trash.
The organization folder's trash in the app
- Owners and admins see "Trash" while they are in the organization folder. The page is titled "Organization folder trash" and works like a workspace's trash.
- Other members see no "Trash" link in the organization folder and no "Move to trash" on organization folder files.
- A member who opens the organization folder's trash by its address sees the list without any controls, and the line "Only organization owners and admins can change the organization folder."
For agents
Operations
| Operation | Capability ID | MCP tool | Scope |
|---|---|---|---|
DELETE W/files/{fileID}?expectedLockVersion= | workspace.files.trash | workspace_files_trash | files:write |
POST W/files/{fileID}/restore | workspace.files.restore | workspace_files_restore | files:write |
GET W/files?trash=true | workspace.files.search | workspace_files_search | files:read |
DELETE W/folders/{folderID}?expectedLockVersion= | workspace.folders.trash | workspace_folders_trash | files:write |
POST W/folders/{folderID}/restore | workspace.folders.restore | workspace_folders_restore | files:write |
GET W/folders?trash=true | workspace.folders.list | workspace_folders_list | files:read |
POST W/files/{fileID}/purge | workspace.files.purge | none | session only |
POST W/folders/{folderID}/purge | workspace.folders.purge | none | session only |
POST W/trash/empty | workspace.trash.empty | none | session only |
Every operation exists for the organization folder too: replace W with L,
workspace. with library. and workspace_ with library_.
What they take and return
| Operation | Takes | Success |
|---|---|---|
| Trash a file | expectedLockVersion in the query | 204 |
| Trash a folder | expectedLockVersion in the query | 200 with {"publicLinkCount": n} |
| Restore a file | nothing | 200 with the file |
| Restore a folder | nothing | 200 with the folder, under its new name and place if they changed |
| List trashed files | trash=true, and the usual cursor and limit | 200 with file summaries; deletedAt and purgeAfter are set |
| List trashed folders | trash=true; not together with parentID | 200 with folders; folderCount and fileCount count what each took along |
| Delete a file for good | nothing | 202 |
| Delete a folder for good | nothing | 202 |
| Empty the trash | nothing | 202 |
- An agent can trash and restore. It cannot delete for good: that is left to a person in a browser, so a mistake by an agent stays recoverable for 30 days.
- An agent reads the
lockVersionof a file from the file. A folder'slockVersioncomes with the folder in a folder listing. - After a folder restore, read the answer:
nameandparentIDsay where the folder is now.
Worked example
Trash a file, sending the lockVersion you read:
curl -s -X DELETE \
"$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE?expectedLockVersion=4" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY" -i
HTTP/1.1 204 No Content
See what is in the trash:
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files?trash=true" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
Each item carries deletedAt and purgeAfter:
{
"items": [
{
"id": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
"name": "logo-usage.md",
"lockVersion": 5,
"deletedAt": "2026-11-14T15:05:00Z",
"purgeAfter": "2026-12-14T15:05:00Z"
}
],
"nextCursor": null
}
Restore it:
curl -s -X POST \
"$TALEWRIGHT/v1/workspaces/$WORKSPACE/files/$FILE/restore" \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
The answer is the file with deletedAt: null, purgeAfter: null and
lockVersion 6.
If the restore would make the file public and the credential holds only
files:write, the answer is:
{
"error": {
"code": "FORBIDDEN",
"message": "...",
"details": {
"reason": "INSUFFICIENT_SCOPE",
"requiredScopes": ["files:approve"]
}
},
"requestID": "..."
}
The file stays in the trash. Tell the person, and leave the restore to an owner or admin.
Edge cases
| Situation | What happens | Why |
|---|---|---|
A file is trashed with an old expectedLockVersion | 409 STALE_LOCK_VERSION. The file stays. | Someone changed it first. |
A file is trashed without expectedLockVersion | 422 VALIDATION_FAILED. | It is required. |
| A file that is already in the trash is trashed again | 409 CONFLICT, reason IN_TRASH. The app says "Already in Trash: {name}" without "Undo". | It is already where you wanted it, and undoing would restore what someone else trashed. |
| A custom field or one of its options is deleted while files in the trash have a value for it | Those files lose the value too. The app counts them before the deletion: "7 files will lose this value, and so will 2 files in the trash." | A deletion clears every file's value, also in the trash. trashedFileCount counts them for owners and admins of the workspace or the organization folder. |
| A folder is trashed while it holds a file that was trashed on its own before | The file stays its own trash item. A restore of the folder does not bring it back. | Only live content goes along with a folder. |
| A folder with a public file in a subfolder is trashed | publicLinkCount is 1 and the link stops. Restricted files are not counted. | The count is the number of public links that stopped. |
| A trashed folder's name is taken by a new folder, and the trashed folder is restored | It comes back as "{name} (2)". | A restore never fails for a name and never renames the other folder. |
| A new folder "campaigns" was created while "Campaigns" was in the trash | "Campaigns" comes back as "Campaigns (2)". | Names are compared without regard to case. |
| A folder is trashed, then its parent is trashed, then the folder is restored | It comes back at the top level. | Its parent is not live. |
| A folder is restored into a place where it would end deeper than 16 levels | It comes back at the top level. | The depth limit holds. |
| A file is trashed, its folder is trashed, and the file is restored | The file comes back at the top level. | Its folder is not live. |
| A file is trashed, its folder is deleted for good, and the file is restored | The file comes back at the top level. | The folder no longer exists. |
| A file that went to the trash inside a folder is restored by itself | 409 CONFLICT, reason NOT_IN_TRASH, "The file went to the trash with its folder; restore the folder". | It is part of the folder's trash item. |
| A subfolder that went along with its parent is restored by itself | 409 CONFLICT, reason NOT_IN_TRASH. | The same rule. |
| A live file is restored | 409 CONFLICT, reason NOT_IN_TRASH. | There is nothing to restore. |
| A folder is restored twice, for example from two browsers | The second gets 409 CONFLICT, reason NOT_IN_TRASH. The app says "{name} is no longer in the trash." | It is already live. |
| A file is moved into a folder at the 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 is refused with 422 on folderID. | A file is never left live inside a trashed folder. |
| A file is uploaded into a folder that is trashed before the upload is ready | The file is created at the top level. | See Uploading. |
| A member trashes a public file and restores it | It is public again at the same link. | It was public when it was trashed. |
A credential with only files:write trashes a public file and restores it | It is public again. | The same rule. No files:approve is needed to put back what was there. |
| A member trashes a public folder's file together with the folder, then restores the folder | The file is public again. | It was public when it was trashed, through the folder that went with it. |
| A restricted file is trashed, its folder is moved under a public folder, and a member restores the file | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC, becomePublic 1. It stays in the trash. | It would become public for the first time. |
| An owner restores that same file | It is restored and is public. No confirmation is asked. | Owners and admins may make files public. |
| A folder holding a file that was public and a file that would newly become public is restored by a member | 403 FORBIDDEN, reason MAKES_FILES_PUBLIC, becomePublic 1. Neither file comes back. | The count names only the new one, and a restore is all or nothing. |
| A file's status is "Internal use only" and its folder became public while it was in the trash | Anyone who may restore it can. It comes back restricted. | Its status does not allow public use, so nothing becomes public. |
| A public file is trashed and its status stops allowing public use meanwhile | A member can restore it. It comes back restricted. | A file that can no longer be public is restored without its link. |
| A public file is trashed and restored | Its public link works again. Temporary links made before the trash do not. | Public links are kept; temporary links are ended. |
| A member asks to delete a trashed file for good | 403 FORBIDDEN. The file stays in the trash. | Only owners and admins delete for good. |
| A credential asks to delete for good, whatever its scopes | 403 FORBIDDEN, reason SESSION_REQUIRED. | Permanent deletion needs a person in a browser. |
| A live file is deleted for good | 409 CONFLICT, reason NOT_IN_TRASH. | Trash it first. |
| A file is deleted for good and then restored | 404 NOT_FOUND. | It is gone from the moment the deletion is accepted. |
| A file is deleted for good and read before its removal has finished | 404 NOT_FOUND, for the file, its versions, their content and temporary links. | It is gone for everyone at once. |
| A file is deleted for good whose bytes another file also has | The other file is untouched. | Each file keeps its own content. |
| A restore arrives just before the 30 days end | The file is restored and is not deleted. | A restored file leaves its countdown behind. |
| A restore arrives just after the 30 days end | 404 NOT_FOUND. | The time is over, even if removal has not happened yet. |
| A file is trashed, restored and trashed again | The second trashing starts a new 30 days. | purgeAfter is set at each trashing. |
| The trash is emptied while someone restores an item | Each item is either restored or deleted, never half of each. | The two are handled one after the other. |
| A file's workspace is deleted while the file is in the trash | The file's 30 days keep running. | See Workspaces. |
A trashed file is searched for with trash=true and q | It is found. | Search works in the trash listing too. |
| A trashed file is among the IDs of a status change | The whole change is refused with 409 CONFLICT, reason IN_TRASH. | A batch is all or nothing. |
| You starred a file and it is trashed | It leaves your favorites. It returns when the file is restored. | Favorites of trashed items are hidden. |
| Someone outside the workspace asks for its trash | 404 NOT_FOUND. | Outsiders cannot tell the workspace exists. |
| A member of the organization trashes an organization folder file | 403 FORBIDDEN. | Only owners and admins change the organization folder. |
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 | Trashing or restoring in the organization folder without being an owner or admin; deleting for good or emptying the trash without being an owner or admin. | Ask an owner or admin. |
FORBIDDEN, reason SESSION_REQUIRED | 403 | A credential asks to delete for good or to empty the trash. | A person does this in a browser. |
FORBIDDEN, reason MAKES_FILES_PUBLIC | 403 | A restore would make public a file that was not public when trashed, and the caller is not an owner or admin. details.becomePublic counts those files. | Ask an owner or admin to restore it. |
FORBIDDEN, reason INSUFFICIENT_SCOPE | 403 | A credential lacks files:write; or a restore would make files public and the credential lacks files:approve. | Use a credential with the scope, or leave it to a person. |
EMAIL_NOT_VERIFIED | 403 | A credential's restore would make files public and its member's email is not verified. | Verify the email address. |
NOT_FOUND | 404 | The item is unknown or out of reach; it was deleted for good; its 30 days are over. | Nothing to do: it cannot be restored. |
STALE_LOCK_VERSION | 409 | Trashing with an expectedLockVersion that is no longer current. | Read the item again and repeat. |
CONFLICT, reason IN_TRASH | 409 | Trashing or changing something that is already in the trash. | Restore it first, or leave it. |
CONFLICT, reason NOT_IN_TRASH | 409 | Restoring or deleting for good something that is live, or that went to the trash inside a folder. | Restore or delete the folder that took it along. |
VALIDATION_FAILED | 422 | expectedLockVersion is missing; trash together with parentID in a folder listing; an invalid cursor or limit. | Correct the request. |
RATE_LIMITED | 429 | A credential passed its request limit. | Wait for Retry-After seconds. |
On the files host, a public link to a trashed file answers 404, and a
temporary link made before the trash answers 403. See
Errors.
Limits
| What | Value |
|---|---|
| Time in the trash before deletion for good | 30 days from the moment of trashing |
| Items in the trash | No limit |
| Page size of the trash listings | 1 to 100, default 50 |
| Undo in the app | Offered for 8 seconds |
| Longest name of a restored folder | 200 characters, the number included |
Questions and answers
I deleted a file by mistake. Can I get it back? Yes, for 30 days. Open "Trash" and choose "Restore". Right after deleting, "Undo" does the same.
How long do files stay in the trash? 30 days. The Trash page shows the date for each item as "Kept until".
Does a restored file come back exactly as it was? Yes: the same name, folder, status, details, tags and versions. If its folder is gone, it comes back at the top level.
Do public links keep working while a file is in the trash? No. They stop at once. After a restore the same link works again, if the file is public again.
The app said "1 public link stopped working until restored." What does that mean? The file you trashed was public. Anyone who had its link now gets "not found". Restoring the file brings the link back.
Why can't I restore this file? It says it would make files public. While the file was in the trash, the place it belongs to became public. The file was not public before, so restoring it would publish it. Only an owner or admin can do that. Ask one of them to restore it.
I trashed a public file. Can I restore it myself? Yes. A file that was public when it went to the trash comes back public for anyone who may restore it.
Can I delete a file for good right away? Only an owner or admin can: first move it to the trash, then choose "Delete permanently" on the Trash page.
Can I undo "Delete permanently" or "Empty trash"? No. That is the one thing that cannot be undone.
Who can empty the trash? Owners and admins.
Why is there no "Delete permanently" for me? You are a member. Members trash and restore. Owners and admins delete for good.
What happens to the files in a folder I move to the trash? They go with it and come back with it. The trash shows the folder as one item, with the number of folders and files inside.
Can I restore one file out of a trashed folder? No. Restore the folder, then trash what you did not want back.
My restored folder is called "Campaigns (2)". Why? Another folder took the name "Campaigns" while yours was in the trash. Rename either of them.
Is there a limit on what the trash holds? No. Any number of items can be in the trash.
Do other workspaces see my trash? No. Each workspace has its own trash, and the organization folder has its own.
What happens to the trash when a workspace is deleted? It is hidden with the workspace. The 30 days of the items in it keep running.
Is a trashed file still found by search? No. Search, listings, counts and duplicates leave trashed files out.
Can an agent delete files?
An agent with files:write can move files and folders to the trash and
restore them. It cannot delete them for good or empty the trash.
Can an agent see what is in the trash?
Yes, with files:read: workspace_files_search and
workspace_folders_list, each with trash: true.
Is it recorded who trashed, restored or deleted something? Yes, in the audit trail. See Audit trail.