Clusters

Update a cluster

Updates one or more fields on the cluster. All fields are optional — only the fields provided are changed.

Version upgrades

Set version to upgrade the cluster to a newer Keycloak version. Upgrades are sequential only — you must upgrade one version at a time. To determine the correct next version, use the GET /clusters/{cluster_id}/upgrade-path endpoint, which returns the ordered sequence of versions the cluster must pass through to reach the latest available version.

Attempting to skip a version returns 409 Conflict. Downgrading to a lower version is not supported.

Major version upgrades (e.g. 25.x → 26.x) include database schema migrations that cannot be easily reversed. Cancelling a major upgrade mid-flight via POST /clusters/{cluster_id}/upgrades/cancel is possible but risky if migrations have already been applied.

Required scope: clusters:write

patch/clusters/{cluster_id}

Request

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

Path parameters

cluster_idstring uuid required

Headers

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

Request body

namestring
size'small' | 'medium' | 'large'
versionstring

Cluster version in semver format. Check the documentation for the latest supported versions.

management_mode'full'

Skycloak manages the full lifecycle of the cluster. Every cluster is fully managed.

featuresstring[]

Replace the full set of enabled feature flags.

features_disabledstring[]

Replace the full set of disabled feature flags.

http_relative_pathstring

Change the HTTP path prefix. Set to / to revert to the root path.

sso_enabledboolean

Whether to enable or disable SSO integration.

auto_upgrade_enabledboolean

Enable or disable automatic patch upgrades.

Example request

{
  "size": "medium"
}

Response

The request has succeeded.

idstring uuid required
namestring required
type'keycloak' | 'tidecloak' required
size'small' | 'medium' | 'large' required
versionstring required

Cluster version in semver format. Check the documentation for the latest supported versions.

location'us' | 'us-west' | 'ca' | 'au' | 'eu' required

Region where the cluster is hosted.

status'provisioning' | 'available' | 'updating' | 'degraded' | 'maintenance' | 'stopped' | 'failed' | 'deleting' required
management_mode'full' required

Skycloak manages the full lifecycle of the cluster. Every cluster is fully managed.

urlstring uri required

Keycloak instance URL. Only non-empty once the cluster reaches available status.

sso_enabledboolean required

Whether admin console SSO integration is enabled for this cluster.

auto_upgrade_enabledboolean

Whether automatic patch upgrades are enabled for this cluster.

http_relative_pathstring required

Path prefix Keycloak is served from (e.g. /auth). Empty string means /.

created_atstring date-time required
updated_atstring date-time required
featuresstring[] required

Keycloak feature flags explicitly enabled on this cluster.

features_disabledstring[] required

Keycloak feature flags explicitly disabled on this cluster.

Example response

{
  "version": "26.5.5"
}

Changes

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