# Backups: Mosaic API reference

> Backups in Mosaic’s local REST API: 4 routes, each with its method, path, fields, what it returns and the errors it names.

Source: https://mosaicbrowser.com/docs/api/backups

**Housekeeping** REST API

## Backups

Snapshots of the store, taken daily and before anything irreversible. The undo for the route above.

- [GETList snapshots](#list-backups)
- [POSTTake a snapshot now](#create-backup)
- [GETSee what a restore would do](#preview-restore)
- [POSTRestore profiles from a snapshot](#restore-backup)

## [List snapshots](#list-backups)

GET`/api/v1/backups`

Newest first. A snapshot holds `mosaic.json` and every `profiles/*.json` — the index, the settings, the projects, the proxies, and each profile’s fingerprint, proxy binding, locale, notes and tags. It deliberately does **not** hold `profile-data/`, the Chromium user-data directories: measured on one machine those are 384 MB against 672 KB of metadata, 570 times the size and mostly cache, so copying them before every delete would turn a safety net into a disk-filling background job. The consequence is stated rather than buried — **a restore brings back the identity, not the session**, so a restored profile has its fingerprint and its proxy and is logged out. `reason` is `daily` for the once-a-day floor, `safety` for one taken immediately before a purge, and `manual` for one somebody asked for. `profiles` and `bytes` are counted off the directory at read time, never stored, so they cannot disagree with what is actually there.

#### Returns

`{ total, backups: BackupEntry[] }` — each `{ id, takenAt, reason, profiles, bytes }`.

## [Take a snapshot now](#create-backup)

POST`/api/v1/backups`

Takes one immediately, with `reason: "manual"`, and prunes anything past the retention window afterwards. Worth doing before a bulk edit or an import, which are the two operations that change many profiles at once and have no undo of their own. Cheap enough not to think about: about twelve kilobytes per profile.

#### Returns

The `BackupEntry` that was created.

#### Errors

- `500` — there was no store file to copy.

## [See what a restore would do](#preview-restore)

GET`/api/v1/backups/:id`

Changes nothing. Splits the snapshot’s profiles into `missing` — in the snapshot and no longer in the library, which is what recovery means — and `present`, which exist in both. That distinction is the whole reason this route exists: restoring a missing profile brings work back, and restoring a present one **writes over** whatever was done to it since the snapshot was taken. Two different actions wearing one verb, so the caller gets to see which one they are about to perform.

#### Path parameters

| Field | Type | What it is |
| --- | --- | --- |
| `id`required | `string` | The snapshot id from `GET /backups`. |

#### Returns

`{ id, takenAt, missing: [{ id, name, projectId }], present: [{ id, name }] }`

#### Errors

- `404` — no snapshot with that id.

## [Restore profiles from a snapshot](#restore-backup)

POST`/api/v1/backups/:id/restore`

Additive by default, and that is the safety property rather than a convenience. A snapshot is normally restored because something was deleted — and the profiles that were *not* deleted have been edited, launched and re-proxied since it was taken, so writing the old copies over those would make the undo for one mistake into a second, larger one. Profiles that still exist are therefore **skipped** unless `overwrite: true` names the intent, and `ids` narrows it further for the caller who wants one profile back out of many. A profile whose project no longer exists lands in the active project rather than being dropped, because a profile restored into a project nothing lists is a restore that looks like it failed. A safety snapshot taken next to a purge holds rows still marked deleted; those come back **live**, not in the trash, or the next retention sweep would take them again. Taking a snapshot of the current state first is automatic, so a restore is itself undoable.

#### Path parameters

| Field | Type | What it is |
| --- | --- | --- |
| `id`required | `string` | The snapshot id from `GET /backups`. |

#### Body

| Field | Type | What it is |
| --- | --- | --- |
| `ids` | `string[]` | Only these profile ids. Omit for all of them. |
| `overwrite` | `boolean` | Also replace profiles that still exist, discarding changes made since the snapshot. Default `false`. |

#### Returns

`{ restored, overwritten, skipped, note }` — three arrays of profile ids, and a sentence saying that cookies are not included. `skipped` means *considered and declined* — a profile that still exists and was not overwritten — never a profile the caller did not name, so restoring one row out of fifty-five answers with an empty `skipped` rather than fifty-four ids that look like failures.

#### Errors

- `404` — no snapshot with that id.
- `400` — an unknown field, or an empty `ids` array.

```
curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"ids":["'$PROFILE'"]}' "$BASE/backups/$BACKUP/restore"
```

## Run the API on your own profiles

The REST API and the MCP server are part of Pro: $49 a month, with the first 14 days free. Free has every browser feature and no API key.

Mosaic is a desktop app

Email yourself the link and open it on your computer.