Browse a storage backup

browse_storage_backup

Looks inside one storage backup without changing anything, a folder at a time or by searching the whole archive.

POST /v1/browse_storage_backupScopedata:readRead only

Pass a backupId from list_storage_backups and either a path to list one folder of the archive, where an empty path is the root, or a search term to find files anywhere in it whose path contains that term, ignoring upper and lower case. Search mode ignores the path, returns full keys and never compares.

Each file comes back with its key, size, visibility, when it was last modified, the kind of preview it would get, and compare: same, changed when the file is in the storage now at a different size, or missing when it is not in the storage at all. That comparison is how to tell which files were actually lost. It is by size, not by content or visibility, so a file edited to the same length reads same, and so does one that has only been made public or private since.

Pass compare false to skip the comparison on a huge folder. compared comes back false, leaving every compare null, when the live listing could not be completed, which includes a folder that now holds more than 5,000 public or 5,000 private files and folders directly inside it. Folders carry their own file count, total size and newest modified time.

It returns 100 entries a call, with nextOffset as the offset for the next page, or null at the end. restoreAccess says whether you may restore at all: permission is the Delete projects permission, plan is the paid plan, and planUnknown means the plan could not be confirmed rather than that it is free. activeRestore is the restore running right now, if any, in which case the comparison is moving under you.

It needs only workspace membership, works on any plan and never downloads anything, which happens only in the editor. A backup still being archived, one that failed, or one taken in an older format is refused with the reason, such as This backup was taken in an older format that cannot be browsed or restored. Download it instead! See Browse a storage backup.

Request

Call it with a POST to https://api.modulify.ai/v1/browse_storage_backup, sending the inputs below as a JSON object. The token needs the data:read scope.

It only reads and changes nothing, so retrying it is safe.

curl -X POST https://api.modulify.ai/v1/browse_storage_backup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","backupId":"BACKUP_ID"}'

Over MCP, the same method is the browse_storage_backup tool.

Inputs

Input	Type	Required	Description
`projectId`	string	Yes	The site the backup belongs to.
`backupId`	string	Yes	The backup to look inside, from `list_storage_backups`.
`path`	string	No	The folder of the archive to list, for example `uploads/`. Leave it out or send an empty string for the root.
`search`	string	No	Finds files whose path contains this, anywhere in the archive, ignoring case, in at most 200 characters. When set, `path` is ignored and nothing is compared with the current storage.
`offset`	integer	No	How many entries to skip, from the `nextOffset` of the previous call. Defaults to 0.
`compare`	boolean	No	False skips the comparison with the current storage, which is faster on a huge folder. Defaults to true.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.