Backup destinations

A backup destination is a reusable storage target — an S3-compatible bucket, an SFTP server, a local filesystem path, or another Openship server — that backup policies write their archives to. This API creates and manages those targets and runs a preflight that proves a destination is actually reachable (it writes, reads back, and deletes a probe object). Credentials are encrypted at rest; serialized destinations never return secret values, only hasX flags showing which are configured.

This module is available on both self-hosted and cloud instances. The local destination kind is self-hosted only — it is rejected in cloud mode and, on self-hosted, must be explicitly enabled (see below).

Create a destination

const result = await ship.backupDestinations.create({
  name: "prod-s3",
  kind: "s3_compatible",
  bucket: "my-backups",
  region: "us-east-1",
  accessKeyId: "AKIA...",
  secretAccessKey: "...",
});
console.log(result);

curl -X POST "$OPENSHIP_URL/api/backup-destinations" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-s3","kind":"s3_compatible","bucket":"my-backups","region":"us-east-1","accessKeyId":"AKIA...","secretAccessKey":"..."}'

Required fields depend on kind:

• s3_compatible — bucket, accessKeyId, and secretAccessKey.
• sftp — sshHost, sshUser, and one of sftpPassword / sftpPrivateKey.
• openship_server — serverId (a server in your org).
• local — endpoint (an absolute path inside BACKUP_LOCAL_ROOT).

Update a destination

Send only the fields you want to change. For credentials, undefined (omitted) leaves the stored value unchanged, null clears it, and a string replaces it. The kind cannot be changed after creation.

const result = await ship.backupDestinations.update("bkd_123", {
  pathPrefix: "nightly/",
  isDefault: true,
});
console.log(result);

curl -X PATCH "$OPENSHIP_URL/api/backup-destinations/bkd_123" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pathPrefix":"nightly/","isDefault":true}'

Preflight (verify connectivity)

Proves the destination works by writing, reading back, and deleting a small probe object. On success it stamps lastVerifiedAt; on failure it records the error in lastVerifyError.

const result = await ship.backupDestinations.preflight("bkd_123");
console.log(result);

curl -X POST "$OPENSHIP_URL/api/backup-destinations/bkd_123/preflight" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Errors

Operations