Update a cluster

PATCH

/clusters/{cluster_id}

const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {
  method: 'PATCH',
  headers: {
    'API-Version': '2026-06-01.beta',
    'API-Key': '<API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"size":"medium"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "size": "medium" }'

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

Authorizations

ApiKeyAuth

Parameters

Path Parameters

cluster_id

required

string format: uuid

Header Parameters

API-Version

required

string

Allowed values: 2026-06-01.beta

Request Body^required

application/json

Partial update request. At least one field must be provided. location and type cannot be changed after creation.

object

name

string

>= 1 characters <= 63 characters /^[a-zA-Z][a-zA-Z0-9 _-]*$/

size

string

Allowed values: small medium large

version

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

string

>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/

Example

26.5.5

management_mode

Change the management mode of the cluster.

string

Allowed values: full

features

Replace the full set of enabled feature flags.

Array<string>

features_disabled

Replace the full set of disabled feature flags.

Array<string>

http_relative_path

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

string

sso_enabled

Whether to enable or disable SSO integration.

boolean

auto_upgrade_enabled

Enable or disable automatic patch upgrades.

boolean

Example

{
  "size": "medium"
}

Responses

200

The request has succeeded.

application/json

A Keycloak cluster managed by Skycloak.

object

required

Unique cluster identifier.

string format: uuid

name

required

Human-readable cluster name.

string

>= 1 characters <= 63 characters /^[a-zA-Z][a-zA-Z0-9 _-]*$/

type

required

string

Allowed values: keycloak tidecloak

size

required

string

Allowed values: small medium large

version

required

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

string

>= 1 characters <= 20 characters /^[0-9]+\.[0-9]+(\.[0-9]+)?$/

location

required

Region where the cluster is hosted.

string

Allowed values: us us-west ca au eu

status

required

string

Allowed values: provisioning available updating degraded maintenance stopped failed deleting

management_mode

required

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

string

Allowed values: full

url

required

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

string format: uri

sso_enabled

required

Whether admin console SSO integration is enabled for this cluster.

boolean

auto_upgrade_enabled

Whether automatic patch upgrades are enabled for this cluster.

boolean

http_relative_path

required

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

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

features

required

Keycloak feature flags explicitly enabled on this cluster.

Array<string>

features_disabled

required

Keycloak feature flags explicitly disabled on this cluster.

Array<string>

Example

{
  "type": "keycloak",
  "size": "small",
  "version": "26.5.5",
  "location": "us",
  "status": "provisioning",
  "management_mode": "full",
  "http_relative_path": ""
}

400

The server could not understand the request due to invalid syntax.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

401

Access is unauthorized.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

404

The server cannot find the requested resource.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

409

The request conflicts with the current state of the server.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

422

Client error

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

errors

required

Array<object>

>= 1 items

object

field

required

string

detail

required

string

code

string

value

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"
    }
  ]
}

429

Client error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Headers

Retry-After

integer

RateLimit-Limit

integer

RateLimit-Remaining

integer

RateLimit-Reset

integer

X-RateLimit-Limit-Second

integer

X-RateLimit-Remaining-Second

integer

X-RateLimit-Limit-Minute

integer

X-RateLimit-Remaining-Minute

integer

X-RateLimit-Limit-Hour

integer

X-RateLimit-Remaining-Hour

integer

X-RateLimit-Limit-Day

integer

X-RateLimit-Remaining-Day

integer

500

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

501

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Update a cluster

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Example

Example

Responses

200

Example

400

Example generated

401

Example generated

404

Example generated

409

Example generated

422

Example generated

429

Example generated

Headers

500

Example generated

501

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated