Backup API

REST endpoints for creating, listing, inspecting, verifying, restoring, rotating, and deleting backup bundles. All routes live under /api/v1/admin/backups and are gated by the authed + wsCtx middleware chain. Handlers additionally re-check the workspace role (canRole(role, "manage")) — only OWNER and ADMIN pass. Every mutation writes one row to audit_log. Routes are registered in internal/api/router_admin.go (domain split in May 2026); handlers live in internal/api/backup.go.

Every endpoint requires authentication, workspace context, and OWNER or ADMIN on the workspace. The metrics endpoint is stricter still — see its authorisation warning.

Authentication and response contract

Every request uses the authenticated workspace context; no endpoint accepts a workspace ID in its body. Requests without a body are marked explicitly below, and path-based operations take path as a query parameter. Statuses: successful JSON operations return 200 or 201, successful deletion returns 204, and invalid input, authentication, authorization, conflicts, and server failures use the status codes listed in each operation’s error table.

Endpoints

Method	Endpoint	Purpose
POST	`/api/v1/admin/backups`	Create a new bundle
GET	`/api/v1/admin/backups`	List bundles for the current workspace
GET	`/api/v1/admin/backups/status`	Inspect the per-workspace advisory lock
DELETE	`/api/v1/admin/backups/status`	Force-release the lock
GET	`/api/v1/admin/backups/metrics`	Process-lifetime counters (instance OWNER only)
GET	`/api/v1/admin/backups/inspect`	Read the plaintext MANIFEST
GET	`/api/v1/admin/backups/verify`	Recompute sealed-payload SHA-256
POST	`/api/v1/admin/backups/rotate`	Apply retention policy
GET	`/api/v1/admin/backups/download`	Stream bundle bytes
POST	`/api/v1/admin/backups/restore`	Restore a bundle
POST	`/api/v1/admin/backups/self-test`	Run a backup self-test (round-trip create + verify)
DELETE	`/api/v1/admin/backups`	Delete a bundle from disk

Path-based endpoints (inspect, verify, download, restore, delete) validate that the supplied path lives under ~/.crewship/backups and belongs to the caller’s workspace. Symlinks are explicitly rejected during path validation — no escape via ln -s to read files outside the backup directory. Paths from other workspaces return 404 Not Found rather than 403, so the endpoint does not confirm existence of bundles outside the caller’s scope.

Create and list

Create new bundles and enumerate the ones already on disk for the current workspace.

POST /api/v1/admin/backups

Create a new backup bundle. Runs inline (seconds to minutes); no async job queue.

Request

{
  "scope": "workspace",
  "scope_level": "standard",
  "crew_id": "",
  "passphrase": "correct horse battery staple",
  "recipient": "",
  "no_encrypt": false,
  "output_dir": ""
}

Field	Type	Notes
`scope`	`"workspace"` \| `"crew"`	Required. `"instance"` is reserved for the CLI-only flow and rejected by the API.
`scope_level`	`"quick"` \| `"standard"` \| `"full"`	Optional. Defaults to `backup.DefaultScopeLevel` when omitted. Invalid values rejected with 400.
`crew_id`	string	Required when `scope == "crew"`. Whitespace-only values are rejected.
`passphrase`	string	AGE passphrase. Exactly one of `passphrase` / `recipient` / `no_encrypt` must be supplied.
`recipient`	string	AGE X25519 public key (`age1…`). Parsed with `age.ParseX25519Recipient`.
`no_encrypt`	bool	Plaintext payload. Use for test / CI only.
`output_dir`	string	Optional override. Must resolve under `~/.crewship/backups`; symlinks rejected.

Response — `201 Created`

{
  "path": "/home/admin/.crewship/backups/crewship-workspace-acme-2026-04-15T12-05-01Z.tar.zst",
  "size_bytes": 13421772,
  "payload_sha256": "b5f7…",
  "format_version": 3,
  "scope": "workspace",
  "scope_level": "standard",
  "created_at": "2026-04-15T12:05:01Z",
  "encrypted": true
}

scope_level is omitted when the bundle has no explicit level recorded in its manifest.

contents.crews[].memory_included means “the crew and per-agent memory trees under /crew are in this bundle” only from format_version 3. At v1 and v2 the flag was set unconditionally for any crew that had a container, and the section behind it held /output, not memory. Read it together with format_version, or use the CLI, which already does. From v3 every per-crew inclusion flag is derived from what the collector observed writing: memory_included (files inside a .memory directory), crew_files_included (any file in the /crew section, memory or not), output_included (/output), workspace_included, volumes_included, system_included.memory_included counts FILES, not tar entries, and only those inside a .memory directory. The runtime creates crews/<id>/shared and crews/<id>/agents at container creation, so an entry count would report memory for every provisioned crew regardless of whether an agent ever wrote one.

New bundles are written at format_version 3 (backup.FormatVersion, bumped v2→v3 on 2026-08-03 when the payload gained the crew/<slug> section carrying the crew and per-agent memory trees). Restore enforces an N-2 compatibility window: this binary reads format_version in [MinSupportedFormatVersion, FormatVersion] = [1, 3]. A bundle newer than the reader returns ErrFormatTooNew (400); older than the window returns ErrFormatTooOld (400).

Errors

Status	Condition
`400`	Invalid body, invalid scope, invalid `scope_level`, missing `crew_id`, multiple or zero encryption selectors, invalid AGE recipient, `output_dir` escapes the default directory.
`401`	Missing or invalid auth.
`403`	Role < ADMIN.
`409`	Another backup already holds the lock (`ErrLockHeld`) or an agent run is active (`ErrAgentRunning`).
`500`	DB dump, tar, or encryption failure.

Audit action: backup.create.

GET /api/v1/admin/backups

List bundles from ~/.crewship/backups filtered to the caller’s workspace (bundles of other workspaces are hidden from the response).

Response — `200 OK`

{
  "data": [
    {
      "path": "/home/admin/.crewship/backups/crewship-workspace-acme-2026-04-15T12-05-01Z.tar.zst",
      "file_name": "crewship-workspace-acme-2026-04-15T12-05-01Z.tar.zst",
      "size_bytes": 13421772,
      "scope": "workspace",
      "scope_level": "standard",
      "encrypted": true,
      "created_at": "2026-04-15T12:05:01Z",
      "format_version": 3
    }
  ]
}

Entries are sourced from backup_catalog first (reconciled against disk on each call); a missing/empty catalog falls back to a filesystem scan. scope_level is omitted when the source manifest did not record it.

Locking and metrics

Inspect or force-release the per-workspace advisory lock, and read process-lifetime backup counters.

GET /api/v1/admin/backups/status

Report the workspace’s advisory lock.

Response — `200 OK`

{
  "held": true,
  "workspace_id": "ws_abc123",
  "acquired_by": "user_def456",
  "acquired_at": "2026-04-15T12:04:58Z",
  "expires_at": "2026-04-15T13:04:58Z"
}

held: false omits the detail fields. The lock TTL is 1 hour (backup.DefaultLockTTL). Missing workspace context returns 400 (not 401).

DELETE /api/v1/admin/backups/status

Force-release the per-workspace lock regardless of owner. Intended as an emergency escape hatch when a crashed backup left a stale lock behind. Returns 204 No Content. Audit action: backup.unlock.

GET /api/v1/admin/backups/metrics

Return a point-in-time snapshot of process-lifetime counters for the backup subsystem — created / failed / restored totals, size bytes, approximate duration quantiles, and per-workspace lock-hold seconds. Counters reset on every restart; persistent reporting should read audit_log instead.

Authorisation is stricter than the other backup endpoints. This route is gated by backup.IsInstanceOwner, which checks CREWSHIP_OWNER_EMAIL — a server-level env var, not the workspace role. A workspace OWNER / ADMIN on their own is refused with 403 Forbidden ({"error": "instance owner required"}). The env is intentionally not stored in the database so a compromised SQL session cannot grant itself access.

Response — `200 OK`

{
  "created_total":                5,
  "created_by_scope":             { "workspace": 4, "crew": 1 },
  "failed_total":                 0,
  "failed_by_reason":             {},
  "restored_total":               2,
  "size_bytes_total":             67108864,
  "duration_seconds_p50":         4.1,
  "duration_seconds_p95":         12.7,
  "duration_seconds_mean":        6.3,
  "lock_held_seconds_by_workspace": { "ws_abc123": 0 }
}

Duration quantiles are approximated from an in-memory ring buffer (tens-to-hundreds of samples between restarts) — adequate for a dashboard tile, not a general-purpose histogram.

Errors

Status	When
`401 Unauthorized`	No authenticated session.
`403 Forbidden`	Authenticated, but email does not match `CREWSHIP_OWNER_EMAIL`.

Inspect, verify, and self-test

Read a bundle’s manifest, recompute its checksum, or run an end-to-end canary without leaving a bundle on disk.

POST /api/v1/admin/backups/self-test

Per-crew round-trip canary: collect → destroy a canary marker inside the crew container → restore → verify → cleanup. Used by the seed CLI and CI harness to validate the backup pipeline end-to-end without leaving a bundle on disk. Lightweight: no encryption, no DB dump. Gated by workspace OWNER/ADMIN (canRole(role, "manage")), the same as the other backup admin endpoints — not by CREWSHIP_OWNER_EMAIL. Request body:

{ "crew_id": "crew_abc123" }

Field	Required	Notes
`crew_id`	✓	Crew within the caller’s workspace. Whitespace-only is rejected.

Response: 200 OK — backup.SelfTestResult JSON (collect/restore/verify status and timing for each phase).

Status	Condition
`400 Bad Request`	Malformed body or missing `crew_id`.
`401 Unauthorized`	No workspace context.
`403 Forbidden`	Role < ADMIN on this workspace.
`404 Not Found`	Crew not found in the caller’s workspace.
`503 Service Unavailable`	`dockerOps` not wired (no Docker daemon).
`500 Internal Server Error`	Canary insert/destroy/restore/verify failed.

GET /api/v1/admin/backups/inspect

Return the plaintext MANIFEST for a bundle without decrypting the payload.

Query

The request has no body. Response: 200 OK with the manifest JSON.

Parameter	Required	Notes
`path`	✓	Absolute path. Must live under `~/.crewship/backups` and belong to the caller’s workspace.

Response — `200 OK`

Returns the manifest JSON as produced by backup.Inspect (internal/backup/manifest.go).

GET /api/v1/admin/backups/verify

Recompute the sealed-payload SHA-256 and compare against the MANIFEST. Does not decrypt. Streams the payload from a temp file so peak heap is bounded by the zstd decoder window.

Query

The request has no body. Response: 200 OK with the verification object.

Parameter	Required	Notes
`path`	✓	Absolute path. Subject to the same path-safety checks as `inspect`; bundles outside the caller’s workspace return `404`.

Response — `200 OK`

{
  "valid": true,
  "size_bytes": 13421772,
  "manifest": { "format_version": 3, "scope": "workspace", "…": "…" },
  "error": ""
}

valid: false sets error to a human-readable reason (checksum mismatch, truncated payload, unreadable bundle, …).

Retention, transfer, and restore

Apply retention policy, stream bundles off-box, restore into the current workspace, or delete bundles from disk.

POST /api/v1/admin/backups/rotate

Apply retention policy to the caller’s workspace. Per-workspace only — another workspace’s bundles are never enumerated.

Request

{ "keep_last": 10, "keep_days": 30, "dry_run": false }

At least one of keep_last / keep_days must be positive (0 disables the rule). Negatives are rejected.

Response — `200 OK`

{
  "deleted": [
    "/home/admin/.crewship/backups/crewship-workspace-acme-2025-12-01T…tar.zst"
  ],
  "dry_run": false
}

With dry_run: true the paths are returned but the files stay on disk and no audit rows are written. Audit action (per deleted bundle, non-dry-run only): backup.rotate.

GET /api/v1/admin/backups/download

Stream the raw bundle bytes over HTTP for scp-free transfer off-box. The request has no body. Response: 200 OK with an application/zstd attachment; 400 is returned for a missing or unsafe path, 404 for a bundle outside the workspace or no longer on disk, and 500 for a file error. Response headers:

Content-Type: application/zstd
Content-Disposition: attachment; filename="<file>"
Cache-Control: no-store
X-Content-Type-Options: nosniff

Audit action: backup.download.

POST /api/v1/admin/backups/restore

Restore a bundle into the current workspace.

Request

{
  "path": "/home/admin/.crewship/backups/crewship-workspace-acme-…tar.zst",
  "passphrase": "correct horse battery staple",
  "identity": "",
  "as_workspace": "",
  "as_crew": "",
  "replace": false,
  "files_only": false,
  "dry_run": false
}

Field	Notes
`path`	Required. Subject to the same path-safety checks as `inspect`.
`passphrase`	Required for passphrase-encrypted bundles. Empty for `--no-encrypt` or recipient-encrypted bundles.
`identity`	AGE X25519 secret key (`AGE-SECRET-KEY-1…`) for bundles sealed with `--recipient`. Parsed with `age.ParseX25519Identity`; invalid values return 400.
`as_workspace`	Land the workspace under a new slug. Docker phase is skipped; finish with `files_only` (below).
`as_crew`	Land the crew under a new slug (crew-scope bundles only). Docker phase is skipped; finish with `files_only`.
`files_only`	Land ONLY per-crew container state into crews that already exist; no database rows are written. Permitted only when the caller’s workspace was created by restoring this bundle — matched on the payload digest recorded in `backup_restore_origins` at rename time. Rejected with 403 otherwise, and 400 if combined with `as_workspace` / `as_crew` / `replace`. That provenance authorises only this mode: a restore of the same bundle into the same workspace WITHOUT `files_only` is refused, because it would address the crews the manifest names — the source crews on a same-instance restore — and overwrite their live data.
`replace`	When `true`, wipe existing target rows matching the bundle’s workspace (by id OR slug) before INSERT. Disaster-recovery path: after a `nuke` the fresh-bootstrap workspace has a new CUID but the same slug — `replace` clears the conflicting target so the bundle lands with its original IDs.
`dry_run`	Decrypt + replay the DB transaction, then roll back. No workspace / crew / agent writes are applied.

Response — `200 OK`

{
  "manifest": { "format_version": 3, "scope": "workspace", "…": "…" },
  "restored_ws": "acme",
  "restored_workspace_id": "ws_abc123",
  "crews_count": 4,
  "crews_restored": 4,
  "rows_inserted": 312,
  "docker_phase_skipped": false,
  "dropped_crew_filesystems": [],
  "security_level_clamped": 1,
  "security_level_clamps": [
    { "credential_id": "cred_abc123", "name": "deploy-key", "from": "0", "to": 4 }
  ]
}

docker_phase_skipped: true when as_workspace / as_crew rewrote the slug — container state is not landed. dropped_crew_filesystems names the crews that lost it. Finish the restore by starting each of them (POST /api/v1/crews/{crewId}/container-start) and then calling this endpoint again with files_only: true and the new workspace in context. It must be container-start and not /provision: files_only writes each section by exec’ing into the crew’s container, so the container has to be running, and provision only builds the image. Re-calling WITHOUT files_only after a rename does not work and is not the recovery: the forked workspace matches neither the bundle’s id nor its slug, so the tenant guard returns 403 — and its rows are already present under new ids anyway. crews_count is what the bundle describes; crews_restored is how many crews actually received container state. The two differ whenever a crew carries no filesystem sections or has no provisioned container on this instance. A files_only call that would land nothing is rejected rather than returning 200 with the bundle’s count — an operation reporting success without having written anything is the failure mode this whole area exists to have stopped. security_level_clamped counts the restored credentials whose security_level was not one of the defined tiers (L1–L4) and were therefore written at the strictest tier instead — every other writer of that column validates it, so restore does too. security_level_clamps is a bounded sample naming the affected credentials and the value the bundle carried; the full list of what happened is also written to the journal as credential.security_level.clamped. On a dry_run both fields report what would be clamped. Re-set each affected credential with PATCH /api/v1/credentials/{id} (security_level) or crewship credential update <name> --security-level N.

Errors

Status	Condition
`400`	Invalid path, format too new/old (`ErrFormatTooNew`, `ErrFormatTooOld`), invalid manifest, invalid checksum, decryption failure (wrong passphrase / corrupted bundle).
`403`	Bundle is not bound to the caller’s current workspace (by id or slug) and the instance already has at least one workspace. The cross-tenant write guard (`allowRestore`) refuses the restore; restore on the source instance or use a fresh instance for cross-tenant DR.
`404`	Bundle file does not exist on disk (`ErrBundleNotFound`).
`409`	`ErrNoOpRestore` — bundle would insert zero rows; treated as “nothing to do”.
`500`	Unexpected failure during extraction / replay, or the cross-tenant authorization probe failed.

Audit action: backup.restore (or backup.restore.dry_run for dry_run: true).

DELETE /api/v1/admin/backups

Delete a bundle from disk. Returns 204 No Content. The request has no body. Response: 204 No Content; 400 indicates a missing or unsafe path, 404 indicates a bundle outside the workspace, and 500 indicates a delete failure.

Query

Parameter	Required	Notes
`path`	✓	Absolute path. Must live under `~/.crewship/backups` and belong to the caller’s workspace.

Audit action: backup.delete.

Error mapping

internal/api/backup.go:statusForBackupError maps sentinel errors to HTTP status using errors.Is, so the backup package can rework error wording without breaking HTTP contracts:

Sentinel	Status
`backup.ErrAdminRequired`	`403`
`backup.ErrAgentRunning`, `backup.ErrLockHeld`	`409`
`backup.ErrFormatTooNew`, `backup.ErrFormatTooOld`, `backup.ErrSchemaTooOld`, `backup.ErrInvalidManifest`, `backup.ErrInvalidScope`	`400`
`backup.ErrDecryption`, `backup.ErrInvalidChecksum`	`400`
`backup.ErrNoOpRestore`	`409`
any other	`500`

​Backup API

​Authentication and response contract

​Endpoints

​Create and list

​POST /api/v1/admin/backups

​Request

​Response — 201 Created

​Errors

​GET /api/v1/admin/backups

​Response — 200 OK

​Locking and metrics

​GET /api/v1/admin/backups/status

​Response — 200 OK

​DELETE /api/v1/admin/backups/status

​GET /api/v1/admin/backups/metrics

​Response — 200 OK

​Errors

​Inspect, verify, and self-test

​POST /api/v1/admin/backups/self-test

​GET /api/v1/admin/backups/inspect

​Query

​Response — 200 OK

​GET /api/v1/admin/backups/verify

​Query

​Response — 200 OK

​Retention, transfer, and restore

​POST /api/v1/admin/backups/rotate

​Request

​Response — 200 OK

​GET /api/v1/admin/backups/download

​POST /api/v1/admin/backups/restore

​Request

​Response — 200 OK

​Errors

​DELETE /api/v1/admin/backups

​Query

​Error mapping

​See also

Backup API

Authentication and response contract

Endpoints

Create and list

POST /api/v1/admin/backups

Request

Response — `201 Created`

Errors

GET /api/v1/admin/backups

Response — `200 OK`

Locking and metrics

GET /api/v1/admin/backups/status

Response — `200 OK`

DELETE /api/v1/admin/backups/status

GET /api/v1/admin/backups/metrics

Response — `200 OK`

Errors

Inspect, verify, and self-test

POST /api/v1/admin/backups/self-test

GET /api/v1/admin/backups/inspect

Query

Response — `200 OK`

GET /api/v1/admin/backups/verify

Query

Response — `200 OK`

Retention, transfer, and restore

POST /api/v1/admin/backups/rotate

Request

Response — `200 OK`

GET /api/v1/admin/backups/download

POST /api/v1/admin/backups/restore

Request

Response — `200 OK`

Errors

DELETE /api/v1/admin/backups

Query

Error mapping

See also