Restoring a backup

A .rewind file created by Exporting and backups can be restored into any Rewind workspace. The restore flow is preview-first and creates an automatic safety backup before touching your data.

How to restore

1. Click Import in the top bar.
2. Click the Rewind backup tab.
3. Click Choose file and pick a .rewind (or legacy .json workspace export) file.
4. The dialog parses the archive and shows a one-line preview: <N> collections, <M> requests, <K> attachments, <H> history entries plus, if anything is missing, ; missing X items.
5. If the archive was created with includeSecrets: true or includeResponseBodies: true, the dialog asks for explicit confirmation.
6. If you have unsaved changes in any open tab, a checkbox is shown: "Discard unsaved tab changes and replace the current workspace." Tick it to confirm.
7. Click Restore workspace.

The dialog shows a status line — "Workspace and attachments restored." or an error message — when the import finishes.

What the server does

The restore endpoint is POST /api/v2/workspace/archive/restore. Internally, it:

1. Validates the archive format. The manifest.json must be format: "rewind-workspace", version: 1, and the workspaceVersion inside workspace.json must be 2. Other versions are rejected with a clear error.
2. Verifies every file's checksum. Every file listed in manifest.files is SHA-256-checked against the bytes in the archive. A mismatch aborts the restore.
3. Verifies path safety. Every archive path is checked for .. traversal, absolute paths, and Windows-style separators. The current implementation extracts into a temp directory, so this is mostly a defense-in-depth check.
4. Checks attachment references. The set of attachmentId values referenced from any request body and from network settings is compared to the attachments present in the archive. Anything missing is listed in the preview as attachment:<id>.
5. Creates a safety backup. Before touching your data, the server runs a complete export of the current workspace (with secrets and response bodies) and writes it as rewind.backup in the workspace's backups/ directory. This file is a normal .rewind archive; you can restore from it later.
6. Replaces the workspace. The server calls importWorkspace on the new content, swaps in the attachments, swaps in the response bodies, and runs an attachment garbage-collection pass.
7. On failure, rolls back. If anything in step 6 throws, the server restores the in-memory snapshot of the previous workspace, attachments, and response bodies, and re-throws. The rewind.backup safety archive is still on disk.

Confirming secrets and response bodies

The restore endpoint takes two query parameters:

• confirmSecrets=true — required to restore an archive whose manifest says includes.secrets: true. Without it, the server returns a 400.
• confirmResponseBodies=true — required to restore an archive whose manifest says includes.responseBodies: true. Same 400.

The dialog sets both automatically when it sees a manifest that needs them; the underlying API is also callable directly from scripts. See the API surface for the exact contract.

What is not restored

• Local dev server state — the in-memory OAuth token cache, in-flight executions, and the local session cookie. Those are not part of the archive.
• Local browser state — the active environment ID stored in localStorage is not part of the archive. After restore, the first available environment becomes active.
• Open tabs in the UI — restoring a workspace does not re-open the tabs you had open. The UI starts fresh and reloads collections and environments from the server.

Common pitfalls

• "Archive checksum failed for …" — the file is corrupted or was edited after export. Try the export again from the source workspace.
• "Unsafe archive path: …" — the file contains entries with .., absolute paths, or Windows separators. This is a hard reject; the archive is not safe to use.
• "Archive has missing items: attachment:att_abc" — the archive references an attachment that isn't in the file. Re-export from the source workspace, or attach the missing file manually.
• "Restoring secrets requires explicit confirmation" — the archive was created with includeSecrets: true but the request didn't set confirmSecrets=true. Re-run with the flag.

What's next?

• Exporting and backups — creating the archive in the first place
• Data and storage — where the safety backup lives
• API surface — the underlying restore endpoint