Preview a cluster upgrade
const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/upgrade-preview?to=26.5.5';
const options = {
method: 'GET',
headers: {'API-Version': '2026-06-01.beta', 'API-Key': '<API-Key>'}
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}curl --request GET \
--url 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/upgrade-preview?to=26.5.5' \
--header 'API-Key: <API-Key>' \
--header 'API-Version: 2026-06-01.beta'Returns breaking changes and per-extension jar plans for upgrading this cluster to the requested target version.
Required scope: clusters:read
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”Cluster version in semver format. Check the documentation for the latest supported versions.
Example
26.5.5Header Parameters
Section titled “Header Parameters”Responses
Section titled “Responses”The request has succeeded.
Breaking changes and per-extension jar plans for upgrading a cluster to a target version.
object
Breaking changes between the cluster’s current version and the requested target.
A breaking change recorded for a version of a cluster type, taken from the product’s own migration guide.
object
Title of the change, as published in the migration guide.
Plain-language summary of what changes.
How disruptive the change is: breaking, config-change or deprecation.
Concrete steps to take before upgrading, or null when none are recorded.
Installed extensions and how their jars participate in the upgrade.
How one installed extension participates in a Keycloak upgrade to a target version.
object
Extension display name.
Planned action: will_update, unchanged, pinned, custom, no_compatible_build, or pinned_no_compatible_build.
Customer-facing detail for this row.
Primary JAR URL currently installed, when known.
Primary JAR URL that would be used on the target Keycloak version, when applicable.
Example generated
{
"breaking_changes": [
{
"title": "example",
"summary": "example",
"severity": "example",
"action_required": "example"
}
],
"extensions": [
{
"name": "example",
"action": "example",
"message": "example",
"current_jar_url": "example",
"target_jar_url": "example"
}
]
}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"
}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"
}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"
}