Create a cluster

POST

/clusters

const url = 'http://localhost:8000/clusters';
const options = {
  method: 'POST',
  headers: {
    'API-Version': '2026-06-01.beta',
    'API-Key': '<API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"my-cluster","size":"small","version":"26.5.5","location":"us"}'
};

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

curl --request POST \
  --url http://localhost:8000/clusters \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "my-cluster", "size": "small", "version": "26.5.5", "location": "us" }'

Required scope: clusters:write

Authorizations

ApiKeyAuth

Parameters

Header Parameters

API-Version

required

string

Allowed values: 2026-06-01.beta

Request Body^required

application/json

Request body for creating a new cluster. Admin console SSO integration is enabled by default.

object

name

required

string

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

type

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]+)?$/

Example

26.5.5

location

required

Region where the cluster is hosted.

string

Allowed values: us us-west ca au eu

management_mode

Management mode for the cluster. Defaults to full.

string

Allowed values: full

features

Keycloak feature flags to enable on the cluster at creation time.

Array<string>

features_disabled

Keycloak feature flags to disable on the cluster at creation time.

Array<string>

http_relative_path

HTTP path prefix to serve Keycloak from (e.g. /auth). Defaults to /.

string

auto_upgrade_enabled

Enable automatic patch upgrades. Requires a maintenance window; one is provisioned if not supplied.

boolean

maintenance_window

Set the cluster’s maintenance window at creation. A region default is provisioned if omitted.

object

enabled

required

Whether the window is active.

boolean

days_of_week

required

Days of week the window applies to (0 = Sunday … 6 = Saturday).

Array<integer>

start_local

required

Local start time, HH:MM.

string

end_local

required

Local end time, HH:MM.

string

timezone

required

IANA timezone, e.g. Europe/Berlin.

string

Example

{
  "name": "my-cluster",
  "size": "small",
  "version": "26.5.5",
  "location": "us"
}

Responses

201

The request has succeeded and a new resource has been created as a result.

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

402

Client error

application/problem+json

Returned when a workspace plan quota would be exceeded. required_plan indicates the minimum plan needed to complete the request.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

current_plan

required

string

required_plan

required

string

code

Machine-readable identifier of the quota that was hit, so a client can tell quotas apart without parsing detail. Known values include cluster_limit (the workspace’s total cluster allowance), cluster_size_quota (the allowance for the requested cluster size) and cluster_size (the requested size is not offered on the plan at all). New values may be added.

string

current_usage

How many of the resource the workspace currently has.

integer

current_limit

Maximum allowed by the current plan. 0 means the plan does not include the resource at all.

integer

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "current_plan": "example",
  "required_plan": "example",
  "code": "example",
  "current_usage": 1,
  "current_limit": 1
}

403

Access is forbidden.

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

Create a cluster

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Example

Responses

201

Example

400

Example generated

401

Example generated

402

Example generated

403

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