API reference

Authentication, resource groups, and the conventions every Backup endpoint follows.

Everything the Backup dashboard does goes through this API, and the CLI calls it too — so anything you can click, you can script.

The authoritative endpoint reference is the live Swagger UI served at /swagger/ on the Backup service host. (The backend service is internally named snapdb; the customer-facing branding is "Backup".)

Endpoint paths can change. Treat the Swagger spec as the source of truth; this page documents conventions.

Authentication

Authorization: Bearer <JWT>

Short-lived org-scoped session tokens with the Backup-specific audience, minted via the auth service — see Platform → Tokens. There are no long-lived API keys for Backup today.

Resource groups

Data sources — CRUD (delete requires a confirmation field matching the datasource name and refuses while a job is in flight), PUT .../credentials (connection-URI or field-by-field mode), and POST .../verify for the connection test.
Backup policies — CRUD on the schedule/retention/destination templates. Delete refuses while attached.
Attachments — GET/POST /datasources/{id}/policies and PATCH/DELETE .../policies/{policyId} — attach, toggle enabled, set priority, detach. Duplicate attachments are rejected.
Backup jobs — list per datasource or org-wide (GET /backups with datasource_ids filter), POST .../backups/run-now (optionally with a policyId override), POST .../backups/{jobId}/download-link (15-minute presigned URL, managed storage only), and DELETE for a single backup.
Storage destinations — list/create/get/update/delete BYO destinations (create and credential updates run the verification probe first), plus POST /storage-destinations/managed/ensure to idempotently provision the managed destination.
Audit log — GET /audit-log with action/target/actor/time filters and GET /audit-log/actors.
Restore — POST /restores/target-probe (pre-flight writability check), POST /restores (start a restore; three modes, and overwrite requires confirmOverwrite: true — see Restore a backup), GET /datasources/{datasourceId}/restores (cursor-paginated history) + GET /restores/{id} (detail), and GET /restores/{id}/logs.presign (short-lived link to the run's redacted log). Restores are deliberately not billing-gated.

Conventions

Pagination

List endpoints use cursor pagination — limit and cursor query parameters in, a next-cursor out; absent when you've reached the end.

Asynchronous semantics

Mutations return quickly; the actual work is asynchronous. run-now returns a job ID immediately and the dispatcher picks the job up within seconds; deletions queue storage cleanup that completes within about a minute. Poll the job listings for state.

Connection-test and download-link responses

These two endpoints report outcomes in the body, always with HTTP 200: an ok flag plus an errorCode/errorMessage pair on failure (see test codes and download rules) — because "your database refused the connection" isn't an API error.

Errors

Everything else uses the platform error shape:

{
  "type": "VALIDATION_FAILED",
  "msg": "see fields",
  "fields": { "scheduleCron": "must be a valid cron expression" },
  "timestamp": "2026-07-10T12:00:00Z"
}

type is the stable programmatic identifier; fields appears on validation failures with per-field messages. Codes and limits: Limits and errors.