Recoverability

Why recoverability matters to a client

Deleting and replacing are the changes people regret. Whether one can be undone depends on the storage behind the share, and Foldr can’t make a file server keep what it doesn’t keep. So the API does two things: it tells your app, after the fact, where a deleted item went, and it lets an administrator refuse apps changes that can’t be undone on a share.

You can use both. Tell your user what happened in words they can act on, and don’t promise “you can get it back” where the answer says otherwise.

What a delete tells you

deleteItem answers with, besides the item that was deleted:

Field	Values
`recoverable`	`bin`: the storage keeps it in a recycle bin, trash or earlier versions, so it can be brought back there. `snapshot`: only the server’s shadow copies hold it, as of the last one, so anything changed since is lost. `none`: as far as Foldr can tell it’s gone for good.
`destination`	A stable name for where it is: `microsoft-365-recycle-bin`, `google-drive-trash`, `box-trash`, `dropbox-deleted-files`, `foldr-deleted-files`, `bucket-versions`, `azure-soft-delete`, `shadow-copies`, `shadow-copies-if-enabled`, or `unknown` (Foldr can’t tell whether this storage keeps deleted items). `null` where it’s certainly gone. The list can grow.
`where`	The same in words for a person: “the Microsoft 365 recycle bin”. Use `destination` in code and `where` in a message.
`items`	How many files and folders went.

Bins belong to the share’s storage account, not to the person. Getting something back is usually a job for whoever manages that storage, and Foldr’s API has no “undelete”. Say so to your user.

By storage

Storage	After a delete	After an overwrite or restore	Notes
Microsoft 365 (OneDrive, SharePoint, Teams)	`bin`, `microsoft-365-recycle-bin`	Earlier versions where the storage keeps them (SharePoint does)
Google Drive	`bin`, `google-drive-trash`
Box	`bin`, `box-trash`
Dropbox	`bin`, `dropbox-deleted-files`
Foldr hosted storage	`bin`, `foldr-deleted-files`: Foldr keeps deleted items for 30 days	Earlier versions are kept and listed
Amazon S3 and compatible (your own bucket)	`bin`, `bucket-versions`, only while the bucket’s versioning is on; otherwise `none`; `unknown` until Foldr has been able to ask	Earlier versions only while versioning is on	Foldr asks the bucket whether versioning is enabled
Azure Blob storage	`bin`, `azure-soft-delete`, only while the account’s soft delete is on; otherwise `none`; `unknown` until asked	Earlier versions where the account keeps them
SMB file servers	`snapshot`, `shadow-copies` where the server keeps shadow copies (“Previous Versions”); `snapshot`, `shadow-copies-if-enabled` where Foldr hasn’t asked yet; `none` where the server has none	Shadow copies, as of the last one	Changes since the last shadow copy are lost
Edge agents	`snapshot`, `shadow-copies-if-enabled`		Foldr can’t ask the customer’s own server
Local disk, FTP, SFTP	`none`	`none`
WebDAV, other	`none` with `unknown`		Some WebDAV servers have a bin, some don’t; Foldr can’t tell

Two things follow:

recoverable: "bin" is a promise about the storage, not about getting the bytes back by API. Recovery happens in the storage’s own tools.
snapshot counts as “not safely undoable”. A change made since the last shadow copy is gone for good, so Foldr treats snapshot like none when it decides whether an app may make a change.

What an administrator can refuse

For each share, an administrator can switch off Allow unrecoverable changes from connected apps (in the share’s settings). It is on by default.

On: apps with the right permission may replace, restore over and delete in the share, whatever the storage keeps. This is how people already work in Foldr, and deleteItem still tells you where the item went.
Off: where the storage could not bring the change back (anything but bin), an app’s overwrite, version restore or delete is refused with 409 not-recoverable-here and nothing is changed. Where the storage does keep a bin or versions, the switch makes no difference.
Moves are never refused for this, because a move loses nothing and moving the item back undoes it.
It affects apps only. People using Foldr itself aren’t stopped.

Handle 409 not-recoverable-here by telling your user the change isn’t available to apps on this share, and that they can make it in Foldr themselves. Retrying won’t help.

An app also needs its own permission for each of these changes, in the shares an administrator names (Getting access), and the consent page tells the person in plain words when a scope can’t be undone: “Replace the contents of files, and put back earlier versions, in the shares an administrator allows. Where the storage keeps no earlier versions, the old contents cannot be got back.”

An SMB server keeps no version of what an overwrite replaces. So a restoreVersion that writes a shadow copy over the live file loses what the live file holds now, unless a shadow copy already holds it.

Foldr refuses that overwrite with 409 not-recoverable-here when the live file has changed since the newest shadow copy of it (no shadow copy holds its time and size). Nothing is changed. The message names the safe way.
If a shadow copy holds the live file, the restore goes ahead as before. Nothing is lost then.
Send "as_copy": true in the restoreVersion body to restore as a copy. Foldr writes the chosen version’s bytes beside the file as a new file named Report (3 Nov 2026 14.02).docx (the version’s date and time, in the site’s time zone, with a full stop between hours and minutes because a colon is not allowed in a Windows file name). If that name is taken it uses the next free one (Report (3 Nov 2026 14.02) copy.docx, then ... copy 2.docx). The original is not touched. The answer is 201 with the new file and its ETag.
A copy replaces nothing, so it needs no If-Match, is not counted against the daily allowance, and is never held for approval. It still needs the app’s files.overwrite permission on the share, and write permission for the person on the file and on its folder. A legal hold on the file or its folder does not refuse it (the held file is untouched), and it is refused for a published file the person may only read.
as_copy works on every storage that keeps versions, not only SMB.
The activity log records it as files.version-restore-copy (“Restored an earlier version as a copy”), not as a restore.

Telling the person afterwards

Foldr emails the person a daily summary of what an app removed or replaced for them (“Acme Reports deleted 3 items and replaced 2 in Finance”), without a link, so an app can’t be impersonated by a mail. Your app doesn’t need to send its own confirmation for that, but it should show the user what it did when it did it.

What administrators can see (audit)

Everything an app does is recorded, as the person and naming the app:

Every call that reaches the API is an activity entry for the person (unless the site has switched that activity type off; a call refused for a bad or missing token never gets that far), in Foldr’s activity log (Settings > Activity), reads included. It records where (the share and the path as your app gave it) and what (the operation, for example getContent or deleteItem). Downloads and changes are always recorded.
It never records what a call carried or returned: no file contents, field values, recipients, messages or passwords.
Connections are listed in Settings > Connected apps (the Connections tab): who connected which app, with what access, when, and when it was last used. An administrator can disconnect any connection or revoke an app for everyone.
A person sees their own under Connected apps on the Security tab of their profile, and gets an email when an app is connected, or when an app they’d already connected is given a new right to make changes.
Administrators are alerted (by default) when an app reaches a person’s daily allowance for removing or replacing.
Held changes are approved or declined in Reviews & approvals.

The practical consequence for your app: act as the person and nothing else, and keep your own log of what you did on whose behalf. An administrator who asks “what did this app do on Tuesday?” will get the answer from Foldr, and your own records should agree with it.