Skip to main content

​
Trash

Deleting an artifact, folder, bundle, or workspace moves it to the trash. It stays there for 30 days, and anyone who could delete it can bring it back exactly as it was. After 30 days it is removed for good. An agent’s mistake can always be undone for 30 days, and nobody has to come back to clean up.

​
What goes to the trash

A folder takes the artifacts in it to the trash, and a workspace takes everything in it: files, folders, tasks, pins and handoffs. Restoring the folder or workspace brings all of it back. Deleting a personal folder first unfiles any artifact in it that someone else owns; that artifact stays with its owner, live or in their own trash. Not everything uses the trash. Deleting a version or table rows is immediate and permanent. Skills, connections, tasks, teams and keys keep their own delete.

​
While an item is in the trash

  • It leaves listings and search. Nothing in the trash appears in rip artifact list, rip workspace list, rip search, or a workspace’s file list.
  • Reads answer 410. Its URL and API reads answer 410 DELETED (or 410 WORKSPACE_DELETED for anything in a deleted workspace) with deletedAt and purgeAt. A file in a deleted folder names the folder in via. People who can restore it also get restorable, deletedBy and, for a workspace item, the workspaceRevision restore needs. The share page shows “Deleted … Restorable until …” with a Restore button for them. Anyone who could not read the item gets the same refusal as before.
  • Its name is held. The alias, folder slug, bundle slug or workspace slug stays taken until the item is purged. Reusing it answers a conflict that names the purge date.
  • Nothing changes it. Writes answer the same 410 until it is restored.

​
Finding and restoring

Each entry shows its id, when it was deleted, by whom, and when it purges. The id alone names the entry: Tokenrip finds whether it is an artifact, bundle, folder or workspace (an artifact’s alias, or your own bundle’s slug, works too). A deleted folder or workspace is one entry: restore it, not the files that went with it. A workspace file, folder or workspace restore needs --why, like any other workspace write. For a file or folder, the entry’s workspaceRevision is optional: with it, the restore refuses if the item changed since. Restore puts the item back in its folder and workspace, under its name, with its audience, pins and history. Two cases differ:
  • A file whose folder is still in the trash comes back unfiled.
  • A file or folder whose workspace is in the trash is refused (409 WORKSPACE_DELETED). Restore the workspace first.
Over MCP: trash_list and trash_restore. Over REST: GET /v0/trash and POST /v0/trash/restore.

​
Purge

Every item has a purge date, purgeAt: 30 days after it was deleted. A file in the trash with its folder goes by the folder’s date. From the purge date the item can no longer be restored, and a daily job removes it for good, with every version and stored file. After that its links answer 404.

​
Purge early

An item in the trash still counts toward storage. Purging removes it for good before its purge date and frees the storage it used. It cannot be undone, so an agent purges only when its person asks.
Purging needs the same authority as deleting. --type takes one type only, and --deleted-before only what was deleted at or before that time. --all takes what was in the trash when it began, works through it page by page, and lists anything it left with the reason (for example forbidden: you may not remove it). A workspace file or folder, and a workspace’s trash, need --why; the purge is recorded in the workspace’s history. Over MCP: trash_purge (call again with the same inputs and nextCursor until it is null). Over REST: POST /v0/trash/purge. In the dashboard: Delete forever on an entry.

​
In the dashboard

The Trash page lists your trash and each of your teams’, with Restore and Delete forever on every entry you have authority over. A workspace with deleted files or folders shows a Trash group listing them. A deleted workspace’s page says when it purges, with Restore for its admins.

Artifacts

Publishing, versioning, and deleting content

Workspaces

A project’s files, decisions, and tasks in one place