Cluster Backups

Start an on-demand backup

Starts a backup now, kept for retention_days (1 to the plan maximum). It is listed with type manual.

Returns 409 while another backup of the cluster is queued or running, or while the cluster is still provisioning, and 402 on plans without managed backups.

Required scope: clusters:backups:write

post/clusters/{cluster_id}/backups

Request

  • Base URL: http://localhost:8000
  • URL: http://localhost:8000/clusters/{cluster_id}/backups
  • Auth: API key in header API-Key

Path parameters

cluster_idstring uuid required

Headers

API-Version'2026-06-01.beta' required

Request body

retention_daysinteger required

Days to keep this backup, from 1 to the plan maximum (Business 14, Enterprise 30).

Example request

{
  "retention_days": 7
}

Response

The backup was queued. Poll GET /clusters/{cluster_id}/backups/{backup_id} until status is completed or failed, or subscribe to the backup.completed and backup.failed webhooks.

idstring required

Backup identifier: auto-<yyyymmddhhmm> for an automatic backup, manual-<timestamp>-<suffix> for an on-demand one.

cluster_idstring uuid required
type'automatic' | 'manual' required
status'pending' | 'running' | 'completed' | 'failed' | 'deleted' required
retention_daysinteger required

Days the backup is kept after it completes.

size_bytesinteger required

Size of the stored backup in bytes. Set once status is completed.

sha256string

SHA-256 of the stored (encrypted) object, hex. Set once status is completed.

keycloak_versionstring

Keycloak version whose database was backed up.

failure_reasonstring

Machine-readable failure cause when status is failed: JobFailed, JobLost, Missed, BackupsDisabled, InvalidReport, DatabaseNotReady or StorageNotConfigured.

requested_atstring date-time
started_atstring date-time
completed_atstring date-time
expires_atstring date-time

When the backup is deleted from storage.

deleted_atstring date-time

When the backup was deleted from storage, for status deleted.

created_atstring date-time required

Example response

{
  "id": "auto-202609230300",
  "cluster_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "automatic",
  "status": "completed",
  "retention_days": 14,
  "size_bytes": 52428800,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "keycloak_version": "26.3.0",
  "requested_at": "2026-09-23T03:00:00Z",
  "started_at": "2026-09-23T03:00:04Z",
  "completed_at": "2026-09-23T03:04:12Z",
  "expires_at": "2026-10-07T03:04:12Z",
  "created_at": "2026-09-23T03:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.