Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Backups API

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

GET/backup-destinations

List backup destinations

Response 200 · OK · application/json
DestinationListOutputBody
  • DestinationView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

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

POST/backup-destinations

Add a backup destination

An S3-compatible bucket or a directory on the database's host (local; not off-site). Credentials are write-only. Requires the admin scope. Recommended S3 permissions: s3:PutObject, s3:GetObject, s3:DeleteObject, s3:ListBucket, s3:AbortMultipartUpload on a bucket-scoped key.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
Request body · application/json · required
CreateDestinationInputBody
  • accessKeystring
    Write-only.
  • bucketstring
  • compatModeboolean
    Limit SDK checksums for non-AWS stores. Default: on when an endpoint is set.
  • endpointstring
    S3-compatible endpoint URL; empty means AWS S3.
  • kindenum: s3 | localrequired
  • localDirstring
    Local destinations: relative sub-directory of the agent's backup directory.
  • namestringrequired
  • pathStyleboolean
    Use path-style addressing (MinIO, SeaweedFS, Garage, most self-hosted stores).
  • prefixstring
    Key prefix inside the bucket or directory.
  • regionstring
  • secretKeystring
    Write-only.
Response 201 · Created · application/json
DestinationView
  • accessKeySetbooleanrequired
  • bucketstring
  • compatModebooleanrequired
  • createdAtstring (date-time)required
  • endpointstring
  • idstringrequired
  • inUseBySchedulesinteger (int64)required
  • kindenum: s3 | localrequired
  • lastTestAtstring (date-time)
  • lastTestMessagestring
  • lastTestOkboolean
  • localDirstring
  • namestringrequired
  • offSitebooleanrequired
    False for local directories: a backup on the database's own host does not survive the loss of that host.
  • pathStylebooleanrequired
  • prefixstring
  • regionstring
  • secretKeySetbooleanrequired
  • storedBackupsinteger (int64)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

PATCH/backup-destinations/{destinationId}

Update a backup destination

ParameterInTypeDescription
destinationIdrequiredpathstring
Request body · application/json · required
PatchDestinationInputBody
  • accessKeystring
    Omit or leave empty to keep the stored key.
  • bucketstring
  • compatModeboolean
  • endpointstring
  • localDirstring
  • namestring
  • pathStyleboolean
  • prefixstring
  • regionstring
  • secretKeystring
    Omit or leave empty to keep the stored key.
Response 200 · OK · application/json
DestinationView
  • accessKeySetbooleanrequired
  • bucketstring
  • compatModebooleanrequired
  • createdAtstring (date-time)required
  • endpointstring
  • idstringrequired
  • inUseBySchedulesinteger (int64)required
  • kindenum: s3 | localrequired
  • lastTestAtstring (date-time)
  • lastTestMessagestring
  • lastTestOkboolean
  • localDirstring
  • namestringrequired
  • offSitebooleanrequired
    False for local directories: a backup on the database's own host does not survive the loss of that host.
  • pathStylebooleanrequired
  • prefixstring
  • regionstring
  • secretKeySetbooleanrequired
  • storedBackupsinteger (int64)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

DELETE/backup-destinations/{destinationId}

Delete a backup destination

409 destination_in_use while a schedule or a stored backup uses it.

ParameterInTypeDescription
destinationIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflictdestination_in_use
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/backup-destinations/{destinationId}/test

Test a backup destination

The agent on the chosen server writes, reads back and deletes a probe object. Waits up to 25 seconds; if the agent has not answered by then the response carries no test result yet (poll the destination).

ParameterInTypeDescription
destinationIdrequiredpathstring
Request body · application/json · required
TestDestinationInputBody
  • serverIdstringrequired
    The server whose agent performs the test (it is the one that talks to the destination).
Response 200 · OK · application/json
DestinationView
  • accessKeySetbooleanrequired
  • bucketstring
  • compatModebooleanrequired
  • createdAtstring (date-time)required
  • endpointstring
  • idstringrequired
  • inUseBySchedulesinteger (int64)required
  • kindenum: s3 | localrequired
  • lastTestAtstring (date-time)
  • lastTestMessagestring
  • lastTestOkboolean
  • localDirstring
  • namestringrequired
  • offSitebooleanrequired
    False for local directories: a backup on the database's own host does not survive the loss of that host.
  • pathStylebooleanrequired
  • prefixstring
  • regionstring
  • secretKeySetbooleanrequired
  • storedBackupsinteger (int64)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

GET/backup-restores/{restoreId}

Get a restore

ParameterInTypeDescription
restoreIdrequiredpathstring
Response 200 · OK · application/json
RestoreView
  • actorstring
  • backupIdstringrequired
  • createdAtstring (date-time)required
  • errorstring
  • finishedAtstring (date-time)
  • idstringrequired
  • modeenum: new | in_placerequired
  • preBackupIdstring
  • sourceServiceIdstringrequired
  • statusenum: provisioning | pre_backup | restoring | succeeded | failedrequired
  • targetServiceIdstring
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

PATCH/backup-schedules/{scheduleId}

Update a backup schedule

ParameterInTypeDescription
scheduleIdrequiredpathstring
Request body · application/json · required
PatchScheduleInputBody
  • cronstring
  • destinationIdstring
  • enabledboolean
  • retentionCountinteger (int64)
  • retentionDaysinteger (int64)
  • timezonestring
Response 200 · OK · application/json
ScheduleView
  • createdAtstring (date-time)required
  • cronstringrequired
  • destinationIdstringrequired
  • destinationNamestring
  • enabledbooleanrequired
  • idstringrequired
  • lastRunAtstring (date-time)
  • nextRunAtstring (date-time)
  • retentionCountinteger (int64)required
  • retentionDaysinteger (int64)required
  • serviceIdstringrequired
  • timezonestringrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

DELETE/backup-schedules/{scheduleId}

Delete a backup schedule

ParameterInTypeDescription
scheduleIdrequiredpathstring
Response 204 · No Content

No body.

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

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

GET/backups/{backupId}

Get a backup

ParameterInTypeDescription
backupIdrequiredpathstring
Response 200 · OK · application/json
BackupView
  • actorstring
  • createdAtstring (date-time)required
  • databasestring
  • destinationIdstringrequired
  • destinationKindstring
  • destinationNamestring
  • enginestringrequired
  • engineVersionstring
  • errorstring
  • finishedAtstring (date-time)
  • formatstring
  • idstringrequired
  • lockedbooleanrequired
  • objectDeletedbooleanrequired
    True once retention or a user removed the stored object; the row stays as history.
  • objectKeystring
  • restorablebooleanrequired
  • scheduleIdstring
  • serverIdstring
  • serviceIdstringrequired
  • sha256string
  • sizeBytesinteger (int64)required
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | skipped | expiredrequired
  • triggerenum: manual | schedule | pre_restorerequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

DELETE/backups/{backupId}

Delete a backup

Deletes the stored object through the agent. 409 when the backup is locked or its server is offline.

ParameterInTypeDescription
backupIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

PUT/backups/{backupId}/lock

Lock or unlock a backup

Locked backups are never removed by retention or deleted.

ParameterInTypeDescription
backupIdrequiredpathstring
Request body · application/json · required
LockInputBody
  • lockedbooleanrequired
Response 200 · OK · application/json
BackupView
  • actorstring
  • createdAtstring (date-time)required
  • databasestring
  • destinationIdstringrequired
  • destinationKindstring
  • destinationNamestring
  • enginestringrequired
  • engineVersionstring
  • errorstring
  • finishedAtstring (date-time)
  • formatstring
  • idstringrequired
  • lockedbooleanrequired
  • objectDeletedbooleanrequired
    True once retention or a user removed the stored object; the row stays as history.
  • objectKeystring
  • restorablebooleanrequired
  • scheduleIdstring
  • serverIdstring
  • serviceIdstringrequired
  • sha256string
  • sizeBytesinteger (int64)required
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | skipped | expiredrequired
  • triggerenum: manual | schedule | pre_restorerequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/backups/{backupId}/restore

Restore a backup

mode new (default) creates a sibling database, deploys it empty and restores into it; the original is untouched. mode in_place first takes a safety backup, then overwrites the database; it needs confirmSlug. Poll the restore.

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
RestoreInputBody
  • confirmSlugstring
    In-place restores: the database's slug.
  • modeenum: new | in_place
    new: restore into a new sibling database (default, the original is untouched). in_place: overwrite this database after a safety backup.
  • namestring
    Name of the new database (mode new).
  • serverIdstring
    Server for the new database (mode new). A backup stored in a local directory can only be restored on its own server.
Response 202 · Accepted · application/json
RestoreView
  • actorstring
  • backupIdstringrequired
  • createdAtstring (date-time)required
  • errorstring
  • finishedAtstring (date-time)
  • idstringrequired
  • modeenum: new | in_placerequired
  • preBackupIdstring
  • sourceServiceIdstringrequired
  • statusenum: provisioning | pre_backup | restoring | succeeded | failedrequired
  • targetServiceIdstring
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

GET/dump-restores/{restoreId}

Get a restore from a dump file

ParameterInTypeDescription
restoreIdrequiredpathstring
Response 200 · OK · application/json
DumpRestoreView
  • actorstring
  • bytesReceivedinteger (int64)required
    Bytes the agent has accepted so far.
  • createdAtstring (date-time)required
  • errorstring
  • fileNamestring
  • finishedAtstring (date-time)
  • formatstring
    Detected from the file's first bytes: pg_custom, pg_tar, sql or mongo_archive.
  • gzipboolean
  • idstringrequired
  • logstring
    Progress of the restore (the newest 64 KiB), one line per entry. Omitted from lists.
  • maxUploadBytesinteger (int64)required
    The largest file the control plane accepts.
  • modeenum: new | in_placerequired
  • preBackupIdstring
  • sha256string
    Checksum of the uploaded bytes, known once the upload completed.
  • sizeBytesinteger (int64)required
    Bytes announced by the upload.
  • sourceServiceIdstringrequired
  • startedAtstring (date-time)
  • statusenum: provisioning | pre_backup | awaiting_upload | uploading | restoring | succeeded | failedrequired
  • targetServiceIdstring
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/dump-restores/{restoreId}/cancel

Cancel a restore that has not received its file

Only while the restore is provisioning, taking its safety backup or awaiting its file. The new database it created stays; delete it like any service.

ParameterInTypeDescription
restoreIdrequiredpathstring
Response 200 · OK · application/json
DumpRestoreView
  • actorstring
  • bytesReceivedinteger (int64)required
    Bytes the agent has accepted so far.
  • createdAtstring (date-time)required
  • errorstring
  • fileNamestring
  • finishedAtstring (date-time)
  • formatstring
    Detected from the file's first bytes: pg_custom, pg_tar, sql or mongo_archive.
  • gzipboolean
  • idstringrequired
  • logstring
    Progress of the restore (the newest 64 KiB), one line per entry. Omitted from lists.
  • maxUploadBytesinteger (int64)required
    The largest file the control plane accepts.
  • modeenum: new | in_placerequired
  • preBackupIdstring
  • sha256string
    Checksum of the uploaded bytes, known once the upload completed.
  • sizeBytesinteger (int64)required
    Bytes announced by the upload.
  • sourceServiceIdstringrequired
  • startedAtstring (date-time)
  • statusenum: provisioning | pre_backup | awaiting_upload | uploading | restoring | succeeded | failedrequired
  • targetServiceIdstring
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

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

GET/services/{serviceId}/backup-restores

List restores of a database

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
RestoreListOutputBody
  • RestoreView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

GET/services/{serviceId}/backup-schedules

List a database's backup schedules

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
ScheduleListOutputBody
  • ScheduleView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

POST/services/{serviceId}/backup-schedules

Schedule recurring backups

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
CreateScheduleInputBody
  • cronstringrequired
    5-field cron expression or @hourly/@daily/@weekly/@monthly/@yearly. At most one run every 5 minutes.
  • destinationIdstringrequired
  • enabledboolean
  • retentionCountinteger (int64)
    Keep the newest N successful backups (default 7, 0 = no limit).
  • retentionDaysinteger (int64)
    Delete backups older than N days (0 = no limit).
  • timezonestring
    IANA zone, default UTC.
Response 201 · Created · application/json
ScheduleView
  • createdAtstring (date-time)required
  • cronstringrequired
  • destinationIdstringrequired
  • destinationNamestring
  • enabledbooleanrequired
  • idstringrequired
  • lastRunAtstring (date-time)
  • nextRunAtstring (date-time)
  • retentionCountinteger (int64)required
  • retentionDaysinteger (int64)required
  • serviceIdstringrequired
  • timezonestringrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

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

GET/services/{serviceId}/backups

List a database's backups

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

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

POST/services/{serviceId}/backups

Back up a database now

Returns 202 with a queued backup; poll it or listen for backup.updated events. 409 server_offline / database_not_running when it can not start.

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
CreateBackupInputBody
  • destinationIdstringrequired
Response 202 · Accepted · application/json
BackupView
  • actorstring
  • createdAtstring (date-time)required
  • databasestring
  • destinationIdstringrequired
  • destinationKindstring
  • destinationNamestring
  • enginestringrequired
  • engineVersionstring
  • errorstring
  • finishedAtstring (date-time)
  • formatstring
  • idstringrequired
  • lockedbooleanrequired
  • objectDeletedbooleanrequired
    True once retention or a user removed the stored object; the row stays as history.
  • objectKeystring
  • restorablebooleanrequired
  • scheduleIdstring
  • serverIdstring
  • serviceIdstringrequired
  • sha256string
  • sizeBytesinteger (int64)required
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | skipped | expiredrequired
  • triggerenum: manual | schedule | pre_restorerequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 409Conflictserver_offline
  • 422Unprocessable Entity
  • 500Internal Server Error

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

GET/services/{serviceId}/dump-restores

List restores from a dump file of a database

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
DumpRestoreListOutputBody
  • DumpRestoreView[] | 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}/dump-restores

Restore a database from a dump file

Prepares a restore of a managed database from a file you upload: a pg_dump file (custom -Fc, tar -Ft or plain SQL, optionally gzipped), a mysqldump/mariadb-dump SQL file (optionally gzipped) or a mongodump --archive file. mode new (default) creates a sibling database and deploys it empty; mode in_place first takes a safety backup (needs confirmSlug) and then replaces this database's data. Poll the restore until its status is awaiting_upload, then send the file: PUT /api/v1/dump-restores/{restoreId}/upload with the file as the raw request body (Content-Type: application/octet-stream, Content-Length required, optional ?fileName=). It answers 202 once the agent has the whole file (status restoring); poll GET /dump-restores/{restoreId} for succeeded or failed. The control plane stores nothing: the bytes stream through it to the agent. The format is detected from the file's first bytes (422 unsupported_dump_format when it does not fit the engine); 413 file_too_large above the limit (maxUploadBytes, default 5 GiB).

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
CreateDumpRestoreInputBody
  • confirmSlugstring
    In-place restores: the database's slug.
  • destinationIdstring
    In-place restores: the backup destination of the safety backup; default the destination of the database's backup schedule.
  • fileNamestring
    The name of the file about to be uploaded (shown in the history).
  • modeenum: new | in_place
    new: restore into a new sibling database (default, the original is untouched). in_place: replace this database's data after a safety backup.
  • namestring
    Name of the new database (mode new).
  • serverIdstring
    Server for the new database (mode new); default the source's server.
  • sizeBytesinteger (int64)
    The size of the file about to be uploaded. A file above the limit is refused before anything is created.
Response 202 · Accepted · application/json
DumpRestoreView
  • actorstring
  • bytesReceivedinteger (int64)required
    Bytes the agent has accepted so far.
  • createdAtstring (date-time)required
  • errorstring
  • fileNamestring
  • finishedAtstring (date-time)
  • formatstring
    Detected from the file's first bytes: pg_custom, pg_tar, sql or mongo_archive.
  • gzipboolean
  • idstringrequired
  • logstring
    Progress of the restore (the newest 64 KiB), one line per entry. Omitted from lists.
  • maxUploadBytesinteger (int64)required
    The largest file the control plane accepts.
  • modeenum: new | in_placerequired
  • preBackupIdstring
  • sha256string
    Checksum of the uploaded bytes, known once the upload completed.
  • sizeBytesinteger (int64)required
    Bytes announced by the upload.
  • sourceServiceIdstringrequired
  • startedAtstring (date-time)
  • statusenum: provisioning | pre_backup | awaiting_upload | uploading | restoring | succeeded | failedrequired
  • targetServiceIdstring
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 413Request Entity Too Largefile_too_large
  • 422Unprocessable Entityunsupported_dump_format
  • 500Internal Server Error

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