---
title: "Update a cluster"
method: PATCH
path: "/clusters/{cluster_id}"
tags: ["Clusters"]
---

# Update a cluster

`PATCH /clusters/{cluster_id}`

## Request

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

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`

## Path parameters

- `cluster_id` string, uuid, required

## Headers

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

## Request body

- UpdateClusterRequest: Partial update request. At least one field must be provided. `location` and `type` cannot be changed after creation.
  - `name` string
  - `size` 'small' | 'medium' | 'large'
  - `version` string: 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.
  - `features` string[]: Replace the full set of enabled feature flags.
  - `features_disabled` string[]: Replace the full set of disabled feature flags.
  - `http_relative_path` string: Change the HTTP path prefix. Set to `/` to revert to the root path.
  - `sso_enabled` boolean: Whether to enable or disable SSO integration.
  - `auto_upgrade_enabled` boolean: Enable or disable automatic patch upgrades.

## Response `200`

The request has succeeded.

- Cluster: A Keycloak cluster managed by Skycloak.
  - `id` string, uuid, required
  - `name` string, required
  - `type` 'keycloak' | 'tidecloak', required
  - `size` 'small' | 'medium' | 'large', required
  - `version` string, 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.
  - `url` string, uri, required: Keycloak instance URL. Only non-empty once the cluster reaches `available` status.
  - `sso_enabled` boolean, required: Whether admin console SSO integration is enabled for this cluster.
  - `auto_upgrade_enabled` boolean: Whether automatic patch upgrades are enabled for this cluster.
  - `http_relative_path` string, required: Path prefix Keycloak is served from (e.g. `/auth`). Empty string means `/`.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `features` string[], required: Keycloak feature flags explicitly enabled on this cluster.
  - `features_disabled` string[], required: Keycloak feature flags explicitly disabled on this cluster.

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)