Skip to main content
An agent that uses a personal access token, or an app connected through the hosted connector, can look in the trash and bring back what was deleted. It acts as the member who connected it, so it sees and restores only what that member could. This page is for members and developers. Administrators decide whether agents may write at all: see AI agents in your organization.

​
List what was deleted

Three listings show the trash. Each returns a page of results, newest deletion first, with data, pagination and metadata. They need the rootkey.read scope, and they work in a read-only organization. limit is a whole number from 1 to 100, otherwise the request gets invalid_filters. A cursor that is not valid gets invalid_cursor. An agent sees only the deleted files and vaults of the vaults its member can see: those of the member’s teams, or all of them for an owner or an administrator. It never sees anything of a Restricted vault or table.
Vaults hold files, and tables hold records. A deleted table is not in these listings, and neither are the records that were deleted with it. They come back with the table, and a table is restored only in the ROOTKey app.

​
Restore

  • Restoring a vault brings back the files deleted with it. A file that was deleted on its own before the vault stays in the trash.
  • Files the retention policy already removed for good cannot come back. They are named in skippedPurgedIds.
  • A file whose vault is deleted is refused with vault_also_deleted: restore the vault first.
  • A record whose table is deleted is refused with table_also_deleted: restore the table in the ROOTKey app first.
  • Something that is not in the trash gets file_not_deleted or record_not_deleted. A record asked for in the wrong table gets invalid_ownership.

​
What a restore needs

  • The rootkey.delete scope. A restore undoes a delete, and a write scope is not enough.
  • A role that may restore that kind of item, and, for a vault, a team that owns it (owners and administrators need none).
  • An organization that lets agents write (Full access).
A restore never needs a person’s approval, even when the organization asks for one on deletes. See Delete approvals.
An agent never restores a Restricted vault or table, or a file or record in one, even with an approval to open Restricted data. It is refused with agent_restricted_data_denied. A person restores it in the ROOTKey app.
Agents never delete records (agent_route_not_available, whatever the organization allows), so the records an agent finds in the trash were deleted by a person or by an API key. Agents can restore them.

​
In the ROOTKey MCP server

The ROOTKey MCP server has a tool for each call above, for every credential:

​
Recovery points

An agent can only list recovery points: GET /platform/recovery-point, in pages. Fetching, downloading, creating and deleting one are refused with agent_route_not_available.
  • The listing needs the rootkey.read scope, a role that may read recovery points, and a plan with data restore.
  • It shows only the recovery points whose every vault the member can read now. A recovery point that covers a Restricted vault, a deleted vault or a vault an IP rule hides is never listed, administrators included.

​
Audit reports

An agent can queue a file audit report: POST /platform/files/{fileId}/audit-report. It needs the rootkey.write scope, a role that may create audit reports and an organization with Full access. The report is delivered in the ROOTKey app. There is no endpoint to fetch it, so the agent tells the member where to look. For a file in a Restricted vault, the agent first needs an approval to open that vault: see Restricted data.

Delete approvals

Ask for your approval before an agent deletes a file or a vault.

Restricted data

Let a member open one Restricted vault or table to their own agent, for a few minutes.