Backup HTTP API

This is the reference for the two operations on the backup OpenAPI tag — GetBackupCatalog and GetBackupRestorePlan. It maps each operation to its OpenAPI schema, the ReBAC gate, and the closed Problem.code taxonomy. The wire-contract origin is api/openapi/plexsphere-v1.yaml; this doc is a map, not a duplicate contract.

The backup surface is the platform-scoped, read-only self-description of the disaster-recovery posture: what plexsphere backs up (the per-store coverage table with method, cadence, and retention), the RPO/RTO targets per plane, the explicit exclusions of what is deliberately not backed up, and the ordered restore sequence operators follow during disaster recovery. It serves the catalog; it does not take backups — the artefact streaming, snapshotting, and freshness verification live in the cmd/plexsphere-backup utility CLI, and the operator runbook is ../../operations/dr.md.

Operations

Method	Path	Operation ID	Auth	ReBAC gate	Notes
GET	/v1/platform/backup/catalog	GetBackupCatalog	operator bearer	platform#manage, checked before any data is returned	Returns the BackupCatalog — entries (per-store coverage), targets (RPO/RTO per plane), exclusions.
GET	/v1/platform/backup/restore-plan	GetBackupRestorePlan	operator bearer	platform#manage, checked before any data is returned	Returns the RestorePlan — the ordered RestoreStep sequence (order contiguous ascending from 1; each step names the store, the action, and the verification).

Both reads gate the manage relation on the platform singleton before touching any data, and each emits an audit row on its read path — platform.backup.catalog.read and platform.backup.restore_plan.read respectively — with the denial row landing audit-first on a 403.

Error taxonomy

All error responses use the shared Problem envelope (application/problem+json); the 403 path uses the richer PermissionDenied shape carrying the ReBAC denial reason, relation_path, and request correlation_id.

Status	Code	Meaning
401	unauthenticated	Request carries no authenticated principal.
403	(PermissionDenied)	The caller lacks platform#manage.
500	internal	Server-side failure path; details are logged, never surfaced.
501	backup_not_provisioned	The composition root has not wired the backup surface in this build; log scrapers alert on the deferred-wiring state.

Cross-references

• ../cli/plexctl/backup.md and ../cli/plexctl/restore.md — the matching CLI families (plexctl backup catalog, plexctl restore plan).
• ../../operations/dr.md — the disaster-recovery runbook that consumes the restore plan.
• ../../contributing/layout.md — the cmd/plexsphere-backup binary that takes, streams, and verifies the actual backup artefacts.
• ./index.md — platform-wide /v1 HTTP surface map and the tag table this surface sits in.
• ../../../api/openapi/plexsphere-v1.yaml — authoritative OpenAPI contract; this doc is a map, not a duplicate.