Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Volume backups API

14 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

DELETE/retired-volumes/{retiredId}

Delete a retired Docker volume

Enqueues the removal on the server; the row disappears once the agent confirmed. 409 server_offline while the server is offline.

ParameterInTypeDescription
retiredIdrequiredpathstring
Response 202 · Accepted

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictserver_offline
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/retired-volumes

List the Docker volumes a restore swapped out

Retired volumes are unmounted but kept on the server (their data is the rollback path of a restore) until deleted.

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
RetiredVolumeListOutputBody
  • RetiredVolumeView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/volume-backup

A service's volume backup configuration

Always 200: configured: false with the defaults when none is saved. eligible: false (with ineligibleReason) for services that cannot use volume backups: managed databases (use database backups), route services and services without volumes.

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
VolumeBackupConfigView
  • configuredbooleanrequired
  • cronstringrequired
  • destinationIdstring
  • destinationKindenum: s3 | local
  • destinationNamestring
  • eligiblebooleanrequired
  • enabledbooleanrequired
  • excludesstring[] | nullrequired
  • freezeBudgetSecondsinteger (int64)required
  • ineligibleReasonstring
  • keepDailyinteger (int64)required
  • keepMonthlyinteger (int64)required
  • keepWeeklyinteger (int64)required
  • lastRunAtstring (date-time)
  • modeenum: freeze | stop | liverequired
  • nextRunAtstring (date-time)
  • VolumeBackupHook
  • VolumeBackupHook
  • repoReadybooleanrequired
    A repository password exists for this destination.
  • serviceIdstringrequired
  • timezonestringrequired
  • VolumeBackupVolumeRef[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/services/{serviceId}/volume-backup

Save a service's volume backup configuration

Destination, mode, hooks, excludes, retention and the optional schedule. 422 volume_backup_unavailable for ineligible services, invalid_cron for a bad schedule. The first backup creates the repository.

ParameterInTypeDescription
serviceIdrequiredpathstring
Request body · application/json · required
VolumeBackupConfigInput
  • cronstring
    5-field cron expression or @hourly/@daily/@weekly/@monthly/@yearly; empty = manual backups only. At most one run every 5 minutes.
  • destinationIdstringrequired
  • enabledboolean
    Run on the schedule (needs a cron).
  • excludesstring[] | null
    restic --exclude patterns relative to /vol, e.g. data/cache/**.
  • freezeBudgetSecondsinteger (int64)
    Longest pause of mode freeze (default 5). Over budget the copy is abandoned and the container thawed.
  • keepDailyinteger (int64)
    Keep the newest backup of each of the last N days (default 7, 0 = no limit).
  • keepMonthlyinteger (int64)
    Default 6, 0 = no limit. With all three at 0 nothing is ever removed.
  • keepWeeklyinteger (int64)
    Default 4, 0 = no limit.
  • modeenum: freeze | stop | live
    freeze pauses the container while the local copy is taken (default); stop stops it; live copies nothing and may be inconsistent.
  • VolumeBackupHook
  • VolumeBackupHook
  • timezonestring
    IANA zone, default UTC.
Response 200 · OK · application/json
VolumeBackupConfigView
  • configuredbooleanrequired
  • cronstringrequired
  • destinationIdstring
  • destinationKindenum: s3 | local
  • destinationNamestring
  • eligiblebooleanrequired
  • enabledbooleanrequired
  • excludesstring[] | nullrequired
  • freezeBudgetSecondsinteger (int64)required
  • ineligibleReasonstring
  • keepDailyinteger (int64)required
  • keepMonthlyinteger (int64)required
  • keepWeeklyinteger (int64)required
  • lastRunAtstring (date-time)
  • modeenum: freeze | stop | liverequired
  • nextRunAtstring (date-time)
  • VolumeBackupHook
  • VolumeBackupHook
  • repoReadybooleanrequired
    A repository password exists for this destination.
  • serviceIdstringrequired
  • timezonestringrequired
  • VolumeBackupVolumeRef[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entityvolume_backup_unavailable
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/services/{serviceId}/volume-backup

Remove a service's volume backup configuration

Turns the schedule off. Existing backups and the repository are kept.

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/services/{serviceId}/volume-backup/recovery-key

Reveal the repository password

The restic repository and password, so a backup can be restored without NebulaCtrl. Requires the admin scope; audited as volume_backup.recovery_key.reveal. 422 volume_backup_unavailable until the first backup created the repository.

ParameterInTypeDescription
serviceIdrequiredpathstring
Request body · application/json · required
RecoveryKeyInputBody
Response 200 · OK · application/json
VolumeBackupRecoveryKey
  • notestringrequired
  • passwordstringrequired
  • repositorystringrequired
    The restic repository URL or path as the agent uses it.
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entityvolume_backup_unavailable
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/volume-backups

List a service's volume backups

ParameterInTypeDescription
serviceIdrequiredpathstring
limitqueryinteger (int64)
Response 200 · OK · application/json
VolumeBackupListOutputBody
  • VolumeBackupView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/services/{serviceId}/volume-backups

Back up a service's volumes now

Needs a saved configuration and an online server. Returns 202 with a queued backup; poll it or listen for backup.updated events. 409 server_offline when it can not start; 422 volume_backup_unavailable for ineligible services or without a configuration.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
serviceIdrequiredpathstring
Request body · application/json · required
CreateVolumeBackupInputBody
Response 202 · Accepted · application/json
VolumeBackupView
  • actorstring
  • bytesAddedinteger (int64)required
  • consistencystring
    The mode the agent actually used (a stopped service is backed up without a freeze).
  • createdAtstring (date-time)required
  • destinationIdstringrequired
  • destinationKindstring
  • destinationNamestring
  • errorstring
  • filesinteger (int64)required
  • finishedAtstring (date-time)
  • freezeMsinteger (int64)required
    How long the container was paused or stopped.
  • hookOutcomestring
  • idstringrequired
  • lockedbooleanrequired
  • modestringrequired
    The requested mode.
  • objectDeletedbooleanrequired
    True once retention or a user removed the snapshot; the row stays as history.
  • restorablebooleanrequired
  • serverIdstring
  • serviceIdstringrequired
  • sizeBytesinteger (int64)required
  • snapshotIdstring
  • stageMethodenum: reflink | copy | none
  • stageMsinteger (int64)required
    How long the local copy took.
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | skipped | expiredrequired
  • triggerenum: manual | schedule | pre_restorerequired
  • volumesstring[] | nullrequired
  • warningsstring[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictserver_offline
  • 422Unprocessable Entityvolume_backup_unavailable
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/volume-restores

List a service's volume restores

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
VolumeRestoreListOutputBody
  • VolumeRestoreView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/volume-backups/{backupId}

Get a volume backup

ParameterInTypeDescription
backupIdrequiredpathstring
Response 200 · OK · application/json
VolumeBackupView
  • actorstring
  • bytesAddedinteger (int64)required
  • consistencystring
    The mode the agent actually used (a stopped service is backed up without a freeze).
  • createdAtstring (date-time)required
  • destinationIdstringrequired
  • destinationKindstring
  • destinationNamestring
  • errorstring
  • filesinteger (int64)required
  • finishedAtstring (date-time)
  • freezeMsinteger (int64)required
    How long the container was paused or stopped.
  • hookOutcomestring
  • idstringrequired
  • lockedbooleanrequired
  • modestringrequired
    The requested mode.
  • objectDeletedbooleanrequired
    True once retention or a user removed the snapshot; the row stays as history.
  • restorablebooleanrequired
  • serverIdstring
  • serviceIdstringrequired
  • sizeBytesinteger (int64)required
  • snapshotIdstring
  • stageMethodenum: reflink | copy | none
  • stageMsinteger (int64)required
    How long the local copy took.
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | skipped | expiredrequired
  • triggerenum: manual | schedule | pre_restorerequired
  • volumesstring[] | nullrequired
  • warningsstring[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/volume-backups/{backupId}

Delete a volume backup

Removes the snapshot through the agent. 409 backup_locked, backup_in_progress or server_offline.

ParameterInTypeDescription
backupIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictbackup_locked
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/volume-backups/{backupId}/files

Browse the files of a volume backup

Lists one directory of one volume inside the snapshot (at most 5000 entries). The agent reads the repository, so the server must be online (409 server_offline). Requires the deployments:write scope: backups can contain secrets. **Download.** GET /volume-backups/{backupId}/files/content?volume=&path=&archive= streams a file (Content-Disposition: attachment); a directory is downloaded as a .zip with archive=true. Audited as volume_backup.file.download.

ParameterInTypeDescription
backupIdrequiredpathstring
volumequerystringThe volume's name in the service.
pathquerystringAbsolute directory path inside the volume.
Response 200 · OK · application/json
VolumeFileListing
  • backupIdstringrequired
  • VolumeFileEntry[] | nullrequired
  • pathstringrequired
  • truncatedbooleanrequired
  • volumestringrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictserver_offline
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/volume-backups/{backupId}/lock

Lock or unlock a volume backup

Locked backups are never removed by retention or deleted.

ParameterInTypeDescription
backupIdrequiredpathstring
Request body · application/json · required
LockVolumeBackupInputBody
  • lockedbooleanrequired
Response 200 · OK · application/json
VolumeBackupView
  • actorstring
  • bytesAddedinteger (int64)required
  • consistencystring
    The mode the agent actually used (a stopped service is backed up without a freeze).
  • createdAtstring (date-time)required
  • destinationIdstringrequired
  • destinationKindstring
  • destinationNamestring
  • errorstring
  • filesinteger (int64)required
  • finishedAtstring (date-time)
  • freezeMsinteger (int64)required
    How long the container was paused or stopped.
  • hookOutcomestring
  • idstringrequired
  • lockedbooleanrequired
  • modestringrequired
    The requested mode.
  • objectDeletedbooleanrequired
    True once retention or a user removed the snapshot; the row stays as history.
  • restorablebooleanrequired
  • serverIdstring
  • serviceIdstringrequired
  • sizeBytesinteger (int64)required
  • snapshotIdstring
  • stageMethodenum: reflink | copy | none
  • stageMsinteger (int64)required
    How long the local copy took.
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | skipped | expiredrequired
  • triggerenum: manual | schedule | pre_restorerequired
  • volumesstring[] | nullrequired
  • warningsstring[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/volume-backups/{backupId}/restore

Restore a volume of a backup

mode new_volume (default) restores into a new Docker volume and stages the swap on the service: apply it with Deploy; the current volume is kept as a retired volume. mode in_place first takes a safety backup, then stops the service, overwrites the volume and starts it again; it needs confirmSlug. 409 backup_not_restorable, server_offline, backup_in_progress; 422 confirmation_required.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
backupIdrequiredpathstring
Request body · application/json · required
RestoreVolumeBackupInputBody
  • confirmSlugstring
    In-place restores: the service's slug.
  • modeenum: new_volume | in_place
    new_volume restores into a new Docker volume and stages the swap (apply it with Deploy); the current volume is kept. in_place stops the service, overwrites the volume after a safety backup and starts it again.
  • volumestringrequired
    The volume's name in the service.
Response 202 · Accepted · application/json
VolumeRestoreView
  • actorstring
  • backupIdstringrequired
  • createdAtstring (date-time)required
  • dockerNamestring
  • errorstring
  • finishedAtstring (date-time)
  • idstringrequired
  • modeenum: new_volume | in_placerequired
  • preBackupIdstring
  • serviceIdstringrequired
  • statusenum: pre_backup | restoring | succeeded | failedrequired
  • swapStagedbooleanrequired
    A restore into a new volume succeeded and the swap is staged: apply it with Deploy.
  • volumeNamestringrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictbackup_not_restorable
  • 422Unprocessable Entityconfirmation_required
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.