A small, explicit API.

Authentication

Routes are relative to /api/v1. Send JSON with Content-Type: application/json. Authenticate with a signed-in browser session or an API key from your dashboard: Authorization: Bearer bs_…. A bearer header always wins over cookies, even when it is invalid.

API keys can list sources, storage, backups, logs and restore checks, save sources and storage, create, run and remove backup plans, cancel jobs, and queue backups, connection checks, network checks and restore checks. Hosts, source links, encryption keys, reach settings, storage access and API keys themselves need the signed-in owner. Each route below says which applies.

Errors are JSON: { error, details? }. Common statuses: 400 invalid JSON, 401 not signed in or not allowed with a key, 403 a cross-site browser request or an account still on the waitlist, 404 not yours or not found, 409 a conflict such as a busy or unlinked host or a change that needs confirm: true, 413 too large, 415 wrong content type, 422 invalid fields, 503 not configured or not available. Send a UUID requestId when you queue work; retrying with the same one returns the same job.

From host to first backup

1. Enroll a host. On Private hosts, or with POST /runners { action: "create", name }, get an enrollment code and install the runner on your server. The databases it may back up are the targets in its runner.json.
2. Save the source. POST /sources with the example below.
3. Link it. POST /source-runners { action: "bind", sourceId, runnerId, target }. You can also pass runnerId and target when you create the plan.
4. Create a plan. POST /backup-plans names the storage and schedule. scheduleMinutes is 15 to 43200, or 0 for manual only.
5. Run and poll. Run the plan, then poll GET /backups?sourceId=… and GET /backups/{id}/logs until the job finishes.

POST /api/v1/sources
{
  "name": "App database",
  "kind": "database",
  "engine": "postgres",
  "host": "db.example.test",
  "user": "backup",
  "database": "app",
  "storageMode": "hosted",
  "daily": 7, "weekly": 4, "monthly": 3
}

POST /api/v1/backup-plans
{
  "sourceId": "…",
  "name": "Nightly",
  "destinationIds": ["…"],
  "scheduleMinutes": 1440,
  "dumpStreams": 2
}

POST /api/v1/backup-plans
{ "action": "run", "id": "<plan id>", "requestId": "<uuid>" }

Plan storage is SSH or directory storage, up to eight; each backup is copied to each one. Bucket storage is set in the host's own runner.json. selection leaves schemas or tables out (runner 1.9.0 or later). dumpStreams is 1 to 8 (runner 1.10.0 or later). coordinatorId runs the plan on another host the source is available on. Only one backup of a database runs at a time; a second returns 409.

An API key can do all of this. POST /backups { sourceId } also queues a one-off backup on the source's main host, outside any plan, and the same polling applies. New storage starts unverified and becomes verified after a host reaches it in a storage check, a connection check or a committed copy.

Routes

Restore checks and their limits

A check restores one validated archive in a container on the host that made it. The host needs the restore runtime enabled locally (sudo backupsanity-setup --enable-restore-checks). The sandbox has no network, no host mounts and no source credentials. It restores, queries every user table and is removed. Default limits: a 64 MiB compressed archive, 768 MiB RAM, 512 MiB scratch and ten minutes. A missing runtime or a check already running on that host returns 409.

The signed-in owner can set a source's automatic policy to daily or every backup. A successful backup, from any trigger or host the source is linked to, then queues a check of that exact archive on the host that ran it. Daily mode waits at least 24 hours between checks.

A passing check proves the archive decodes and restores into PostgreSQL with readable tables. It does not test your application, prove an offsite copy, or keep the recovered database. Keeping a recovery is a manual restore into a separate database.

For agents, see MCP setup.