Backup destination API

Creates an unverified backup destination.

Send a supported destination type and its complete storage definition.

To register an existing S3-compatible archive bucket, send this body:

{
  "name": "payments-archive",
  "type": "s3",
  "endpoint": "https://objects.example.com",
  "bucket": "infra-backups",
  "prefix": "payments/",
  "region": "eu-west",
  "addressing_style": "path",
  "credential_secret_id": "sec_backup_access"
}

addressing_style accepts path or virtual_host, with default virtual_host. An optional ca_bundle_secret_id supplies approved trust for a private endpoint. TLS verification cannot be disabled through this request. Bucket creation is outside the destination workflow.

Returns 201 with destination ID and revision, initially unverified. Invalid URLs, secret references, or residency declarations return 422 before creation.

Starts a capability test through the backup worker path.

Requires backups:write and returns 202 with a capability-test operation. It checks write, read, managed temporary deletion, and required multipart behavior through the actual worker path.

A completed result distinguishes authentication, TLS trust, object access, retention restrictions, and cleanup failure. A test that wrote an object but failed to delete it identifies the retained object for cleanup.

Updates destination credentials, trust, name, or enabled state.

Requires its current If-Match. Name, credential reference, CA reference, and enabled state can change. Endpoint, bucket, and prefix cannot be replaced while retained manifests depend on them; create another destination for a new object identity.

Publishing a secret revision and applying it to the consumer are separate steps. Inspect observed credential revision before revoking old provider access.

Returns configuration without secret values, last test, active runs, retained point count, and pending cleanup references. Requires backups:read. Disabling prevents new scheduled selection without canceling active transfers.

Deletes a destination after its retained dependencies are resolved.

Deletion requires the current ETag and no active run, retained recovery point, hold, or unresolved managed object cleanup. Otherwise it returns 409 destination_in_use. Deleting configuration does not delete a provider bucket.

See backup destinations, Backup Run API, and retention holds.