---
title: "Restart the cluster's Keycloak instances"
method: POST
path: "/clusters/{cluster_id}/restart-instances"
tags: ["Cluster Operations"]
---

# Restart the cluster's Keycloak instances

`POST /clusters/{cluster_id}/restart-instances`

## Request

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

Rolls the cluster's Keycloak instances, for example so theme content replaced under an exact theme name
(see `PUT /theme-settings`) starts rendering. Applies immediately unless the workspace's disruptive changes
are latched to the maintenance window, in which case the response reports `deferred: true` and, when known,
`next_window`.

Returns `409 Conflict` when the cluster is not in the `available` status, with a `code` field identifying
why: `cluster_busy` (a restart or other update is already in progress), `cluster_not_available` (the cluster
is failed, deleting, stopped, provisioning, degraded, or under maintenance), or `env_var_limit` (no
environment variable slot left to fall back to on an older operator).

Required scope: `clusters:write`

## Path parameters

- `cluster_id` string, uuid, required

## Headers

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

## Response `202`

The request has been accepted for processing, but processing has not yet completed.

- ClusterRestartOutcome: Outcome of a requested Keycloak instance restart.
  - `deferred` boolean, required: True when the restart is deferred to the cluster's maintenance window instead of applying immediately.
  - `next_window` string, date-time: When the deferred restart's maintenance window next opens. Absent when `deferred` is false, or when the next window could not be resolved.
  - `impact` string, required: Customer-facing description of how disruptive the restart is for this cluster's size.

## Other responses

- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `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)