Start an on-demand backup
const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/backups';
const options = {
method: 'POST',
headers: {
'API-Version': '2026-06-01.beta',
'API-Key': '<API-Key>',
'Content-Type': 'application/json'
},
body: '{"retention_days":7}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}curl --request POST \
--url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/backups \
--header 'API-Key: <API-Key>' \
--header 'API-Version: 2026-06-01.beta' \
--header 'Content-Type: application/json' \
--data '{ "retention_days": 7 }'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
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
Days to keep this backup, from 1 to the plan maximum (Business 14, Enterprise 30).
Example
{
"retention_days": 7
}Responses
Section titled “Responses”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.
object
Backup identifier: auto-<yyyymmddhhmm> for an automatic backup, manual-<timestamp>-<suffix> for an on-demand one.
Days the backup is kept after it completes.
Size of the stored backup in bytes. Set once status is completed.
SHA-256 of the stored (encrypted) object, hex. Set once status is completed.
Keycloak version whose database was backed up.
Machine-readable failure cause when status is failed: JobFailed, JobLost, Missed, BackupsDisabled, InvalidReport, DatabaseNotReady or StorageNotConfigured.
When the backup is deleted from storage.
When the backup was deleted from storage, for status deleted.
Example
{
"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"
}Headers
Section titled “Headers”URL of the resource being created or modified. Poll this endpoint to track completion.
Access is unauthorized.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
Returned when a workspace plan quota would be exceeded. required_plan indicates the minimum plan needed to complete the request.
object
Machine-readable identifier of the quota that was hit, so a client can tell
quotas apart without parsing detail. Known values include cluster_limit
(the workspace’s total cluster allowance), cluster_size_quota (the
allowance for the requested cluster size) and cluster_size (the requested
size is not offered on the plan at all). New values may be added.
How many of the resource the workspace currently has.
Maximum allowed by the current plan. 0 means the plan does not include the resource at all.
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com",
"current_plan": "example",
"required_plan": "example",
"code": "example",
"current_usage": 1,
"current_limit": 1
}Access is forbidden.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The server cannot find the requested resource.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The request conflicts with the current state of the server.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
object
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com",
"errors": [
{
"field": "example",
"detail": "example",
"code": "example",
"value": "example"
}
]
}Client error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Headers
Section titled “Headers”Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}