Cluster Versions and Upgrades

Three endpoints answer the questions that come up before an upgrade: which versions exist, which ones your cluster has to pass through, and what actually changes on the way.

List the versions of a cluster type

curl "https://api.skycloak.io/cluster-types/keycloak/versions" \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta"

[
  {
    "version": "26.2.4",
    "active": true,
    "is_major_change": false,
    "breaking_change_count": 0
  },
  {
    "version": "27.0.0",
    "active": true,
    "is_major_change": true,
    "breaking_change_count": 3
  }
]

Versions are ordered oldest first. Each entry carries:

• version: the version number.
• active: whether the version is currently offered for new clusters and upgrades.
• is_major_change: whether moving onto this version from the previous supported version crosses a major boundary.
• breaking_change_count: how many breaking changes are recorded for the version.

The list includes versions that are no longer offered (active: false), because a cluster of yours may still be running one.

The last two matter for automatic upgrades: a cluster with auto-upgrade enabled is moved one clean step at a time during its maintenance window, and a version that is a major change or carries a breaking change is never applied automatically. It waits for you.

Get the upgrade path for a cluster

curl "https://api.skycloak.io/clusters/$CLUSTER_ID/upgrade-path" \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta"

[
  { "version": "26.2.4", "required": false, "is_major_change": false, "breaking_change_count": 0 },
  { "version": "26.4.0", "required": true, "is_major_change": false, "breaking_change_count": 0 },
  { "version": "27.0.0", "required": true, "is_major_change": true, "breaking_change_count": 3 }
]

The first entry is the cluster’s current version (required is false); every later entry is a step you have to pass through, oldest first. is_major_change and breaking_change_count tell you which of those steps needs a human. This endpoint requires the clusters:read scope.

Preview the breaking changes between two versions

curl "https://api.skycloak.io/cluster-types/keycloak/upgrade-preview?from=26.2.4&to=27.0.0" \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta"

[
  {
    "title": "Admin API endpoint moved",
    "summary": "The endpoint that listed client scopes moved under a new path.",
    "severity": "breaking",
    "action_required": "Update automation that calls the old path before upgrading."
  }
]

from is exclusive and to is inclusive, so the example returns everything recorded for the versions after 26.2.4 up to and including 27.0.0, oldest version first. Both parameters are required and must be version numbers such as 26.4.0; a missing or malformed one returns 400.

severity is breaking, config-change or deprecation. action_required is null when no concrete step is recorded. The content comes from the product’s own migration guides, so it is a summary of what upstream published, not a guarantee that your configuration is affected.

This endpoint describes a cluster type rather than any cluster of yours, so it needs an API key but no extra scope, like the versions list.