---
title: "Replace theme content"
method: PUT
path: "/clusters/{cluster_id}/themes/{theme_id}/content"
tags: ["Themes"]
---

# Replace theme content

`PUT /clusters/{cluster_id}/themes/{theme_id}/content`

## Request

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

Replaces the theme's archive in place, keeping its identity and its realm and
application assignments. The new content is deployed immediately and every realm
and application using the theme is repointed at it, so the sign-in page is never
left unbranded the way delete-then-re-upload would.

The replacement archive must contain every theme type the theme currently provides
(`theme_types`); an archive that drops one is rejected with `400 Bad Request`.
Returns `409 Conflict` for themes created by a platform migration — their content
is pinned and cannot be replaced.

Maximum body size is 50 MB.

Required scope: `themes:write`

## Path parameters

- `cluster_id` string, uuid, required
- `theme_id` string, uuid, required

## Headers

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

## Response `200`

The request has succeeded.

- Theme: A custom Keycloak theme package deployed to a cluster.
  - `id` string, uuid, required
  - `cluster_id` string, uuid, required
  - `name` string, required
  - `description` string
  - `version` string
  - `theme_types` ThemeType[], required: Keycloak theme types detected in the uploaded ZIP package.
  - `status` 'deploying' | 'deployed' | 'undeploying' | 'failed', required
  - `file_size` integer, required: Size of the uploaded theme archive in bytes.
  - `deployed_at` string, date-time: Timestamp of the most recent successful deployment to Keycloak.
  - `error_message` string: Error detail from the last failed deployment.
  - `directory` string: Directory name Keycloak serves this theme from. Use this exact value when setting a realm or application theme outside Skycloak. Valid once `status` is `deployed`. It changes when the theme content is replaced: realm theme settings that name the previous directory are moved automatically, but application themes set outside Skycloak are not and must be updated after a replace.
  - `restart_required` boolean: True when the theme's content was replaced under its exact name and Keycloak has not restarted since, so the previous content may still be served. Only workspaces that keep exact theme names replace content in place; for every other theme this is false.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `402`: Client error
- `403`: Access is forbidden.
- `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)