Backup destinations API

Manage the storage targets (S3-compatible, SFTP, local, or another Openship server) that backups are written to, and run a connectivity preflight.

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.

Base path & auth

All paths are relative to your instance, under /api — e.g. https://your-host/api/backup-destinations. Send a personal access token as a bearer header (Authorization: Bearer <token>), created with openship token create. The dashboard uses your session cookie instead. See the API overview and the auth model for details.

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).

Endpoints

Method & path	Permission	What it does
`GET /api/backup-destinations`	`backup_destination:list`	List the org's destinations (secrets masked).
`POST /api/backup-destinations`	`backup_destination:write`	Create a destination.
`GET /api/backup-destinations/:id`	`backup_destination:read`	Get a single destination.
`PATCH /api/backup-destinations/:id`	`backup_destination:write`	Update a destination's fields or credentials.
`DELETE /api/backup-destinations/:id`	`backup_destination:admin`	Delete a destination.
`POST /api/backup-destinations/:id/preflight`	`backup_destination:write`	Verify connectivity (write + read + delete a probe).

Create a destination

POST /api/backup-destinations

Prop

Type

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).

curl -X POST https://your-host/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":"..."}'

# Same thing from the CLI:
openship backup destination create \
  --name prod-s3 --kind s3_compatible \
  --bucket my-backups --region us-east-1 \
  --access-key-id AKIA... --secret-access-key ...

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.

PATCH /api/backup-destinations/:id

Prop

Type

curl -X PATCH https://your-host/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.

POST /api/backup-destinations/:id/preflight

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

# Same thing from the CLI:
openship backup destination preflight bkd_123

A failed check is still a 200

Preflight returns 200 with {"ok": false, "reason": "..."} when the target is unreachable or misconfigured — the reason (bad credentials, DNS failure, permission denied) is in the body, not the HTTP status. A 404 here means the :id doesn't belong to your organization.

Errors you might see

400 — validation failed

The body is missing a field required for its kind (e.g. an S3 destination without a bucket or credentials), the name is blank / over 80 chars or duplicates an existing destination, or you passed an unsupported kind. http_upload is defined but not yet supported.

400 — local destinations disabled

A local destination requires BACKUP_ALLOW_LOCAL_DESTINATION=true and a configured BACKUP_LOCAL_ROOT, and the endpoint must resolve to an absolute path inside that root. Local destinations are always rejected in cloud mode.

404 on a per-destination route

The :id doesn't belong to your organization (or was deleted). List your destinations with GET /api/backup-destinations to get valid IDs.

Endpoints

Create a destination

Update a destination

Preflight (verify connectivity)

Errors you might see

On this page