Snapshots

Rollback tool for provider watchlist, ratings, and history (not a full backup).

Snapshots are a rollback tool.

They capture provider datasets so you can restore them later.

Snapshots are a new, experimental feature. Use with care. Validate restores before doing destructive changes.

Snapshots are not backups

Snapshots are not the same as a full backup.

They are a best-effort export of:

• one provider

• one dataset (Watchlist, Ratings, History)

They do not include:

• provider credentials or tokens

• CrossWatch configuration

• everything your provider may store (notes, list metadata, privacy settings, etc.)

If you want a real backup, prefer provider-native export/backup features. Snapshots are the fallback when those are missing.

What snapshots are good for

Use snapshots before you:

• run destructive tools (clear watchlist/ratings/history)

• test a new provider or a new sync setup

• clean up lists in bulk

• migrate accounts

What a snapshot contains

A snapshot is a JSON export of one provider and one feature (or All features).

It includes:

• provider id (example: PLEX, TRAKT, SIMKL, ANILIST)

• feature (watchlist, ratings, history, or all)

• created timestamp and optional label

• basic stats (counts and media-type breakdown where available)

• the raw items needed to restore back into the same provider

Whitelisting impacts snapshots (media servers)

For Plex/Jellyfin/Emby, snapshots follow your library whitelists.

If you whitelist specific libraries for a feature, the snapshot includes only items from those libraries.

Example:

• History whitelist = only those libraries are exported in a History snapshot.

• Ratings whitelist = only those libraries are exported in a Ratings snapshot.

If you don’t configure whitelisting, snapshots include all visible libraries.

Guide: Library Whitelisting.

Where snapshots are stored

Snapshots are written to:

/config/snapshots/YYYY-MM-DD/

Filenames include a UTC timestamp, provider, feature, and optional label:

2026-01-27T19-12-45Z__TRAKT__watchlist__before-cleanup.json

“All features” snapshots

If you choose All features, CrossWatch creates:

• one bundle snapshot (__all__) that references child snapshots

• one child snapshot per supported feature (watchlist/ratings/history)

This keeps restore behavior predictable. It also lets you restore one dataset later.

Create a snapshot

1. Open Snapshots.

2. Select a Provider.

3. Select a Feature (Watchlist, Ratings, History, or All features).

4. Optional: set a Label.

5. Click Create snapshot.

Use short labels like before-import or after-cleanup.

Select and inspect snapshots

• The snapshot list shows up to 5 items by default.

• Click Show all to see everything.

• Click a snapshot to load its stats into the Restore panel.

• Click it again to clear the selection.

Restore a snapshot

Select a snapshot, then choose a restore mode.

Restores write to the provider. Pick the mode carefully.

Merge (safe default)

Merge adds items from the snapshot that are missing on the provider.

It does not remove items that exist on the provider already.

Clear + restore (destructive)

Clear + restore first clears the provider dataset (watchlist/ratings/history).

Then it restores the snapshot so the provider matches it as closely as possible.

This can delete a lot of data. Create a snapshot first.

Restoring “All features”

If the selected snapshot is a bundle (feature = all), Restore applies the chosen mode to each supported child feature.

Provider tools (destructive)

Tools run directly against the provider.

Available tools depend on what the selected provider supports:

• Clear watchlist

• Clear ratings

• Clear history

• Clear all

If a provider doesn’t support a feature, that tool is disabled.

Typical workflow:

1. Create a snapshot

2. Run a clear tool

3. Optional: restore a snapshot

Deleting snapshots

Snapshots can be deleted from the UI.

• Select a snapshot

• Click Delete

• Confirm

If you delete an All features bundle, CrossWatch also deletes its child snapshots.

This only deletes files on disk under /config/snapshots/.... It does not touch provider data.

Notes and limitations

• Providers differ. A restore can be best-effort, depending on provider APIs.

• If a feature/tool is disabled, the provider does not support it (or is not configured).

• Snapshots are local files. If you move hosts, copy /config/snapshots too.

Troubleshooting

Restore button disabled

You have not selected a snapshot.

Tools disabled

The provider does not support that feature, or no provider is selected.

Refresh does nothing

Confirm the backend is running and /api/snapshots/manifest responds.