# 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 FORBIDDEN` with `details.reason` `SESSION_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](../reference/permissions.md#files-in-a-workspace).

## How it works

### Moving a file to the trash

- The request names the file and its `expectedLockVersion`. See
  [Lock versions](organizing.md#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.
  - `deletedAt` is the time it was trashed.
  - `purgeAfter` is 30 days later: the time it is deleted for good.
  - Its `lockVersion` goes 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](#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 `200` with `publicLinkCount`: 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`, no `previewURL` and no `publicURL`,
  and `public` is `false`. Its own `visibility` still reads what it was.
- A trashed folder refuses renaming, moving and a change of general access
  with `409 CONFLICT`, reason `IN_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 is `null`. See [Fields and tags](fields-and-tags.md).
- The same holds for a status: a trashed file whose status is deleted comes
  back without a status. See [Statuses](statuses.md).

### 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 `folderCount` and `fileCount`: 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 `200` with 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.
- `deletedAt` and `purgeAfter` are cleared. Its `lockVersion` goes 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-restore-rule).

The checks happen in this order:

1. Not signed in: `401 UNAUTHENTICATED`.
2. The workspace or organization is unknown or out of your reach:
   `404 NOT_FOUND`.
3. The organization folder, and you are not an owner or admin: `403 FORBIDDEN`.
4. The file is unknown, or it was deleted for good, or its 30 days are
   over: `404 NOT_FOUND`.
5. The file is not in the trash: `409 CONFLICT`, reason `NOT_IN_TRASH`,
   message "The file is not in the trash".
6. The file went to the trash inside a folder: `409 CONFLICT`, reason
   `NOT_IN_TRASH`, message "The file went to the trash with its folder;
   restore the folder".
7. The restore would make the file public and you may not do that:
   `403 FORBIDDEN`. See [The restore rule](#the-restore-rule).
8. 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 `200` with 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`, reason `NOT_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`. |

- `becomePublic` counts 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](organizing.md#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`, reason `NOT_IN_TRASH`. Delete the folder.
- A live file or folder answers `409 CONFLICT`, reason `NOT_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

- `purgeAfter` is set when the item is trashed and does not move
  afterwards, except when an owner or admin deletes the item for good.
- At `purgeAfter` the 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](../reference/audit-trail.md#files).

### 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](../organizations/workspaces.md#deleting-a-workspace) and
  [Deleting and restoring](../organizations/delete-and-restore.md).

### The trash and exports

- An organization export leaves out trashed files. See
  [Export](../organizations/export.md).

### 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](#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:

1. The dialog asks "Delete {name} permanently?" and says "It cannot be
   restored afterwards."
2. "Delete permanently" confirms. "Cancel" closes the dialog.
3. The app says "Deleting {name} permanently". The row reads "Deleting
   permanently" until it disappears.

**"Empty trash"**, above the list while the trash holds anything:

1. The dialog asks "Empty the trash?" and says "Everything in the trash is
   deleted permanently and cannot be restored."
2. "Empty trash" confirms. "Cancel" closes the dialog.
3. 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 `lockVersion` of a file from the file. A folder's
  `lockVersion` comes with the folder in a folder listing.
- After a folder restore, read the answer: `name` and `parentID` say where
  the folder is now.

### Worked example

Trash a file, sending the `lockVersion` you read:

```sh
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:

```sh
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE/files?trash=true" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

Each item carries `deletedAt` and `purgeAfter`:

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

```sh
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:

```json
{
  "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](uploading.md#what-a-new-file-starts-with). |
| 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](../organizations/workspaces.md). |
| 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](../reference/errors.md#errors-on-the-files-host).

## 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](../reference/audit-trail.md#folders-trash-and-tags).

## Related pages

- [Files & Assets overview](overview.md)
- [Folders, moving and finding](organizing.md)
- [Versions and history](versions.md)
- [Downloading](downloading.md)
- [Sharing and public links](sharing.md)
- [Statuses](statuses.md)
- [The organization folder and suggestions](library-and-suggestions.md)
- [Workspaces](../organizations/workspaces.md)
- [Deleting and restoring](../organizations/delete-and-restore.md)
- [Credentials and scopes](../agents/credentials.md)
- [Audit trail](../reference/audit-trail.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

