Create or update a cluster (declarative PUT)

PUT

/api/v1/teams/{team_slug}/clusters/{name}/

const url = 'https://example.com/api/v1/teams/example/clusters/example/';
const options = {
  method: 'PUT',
  headers: {cookie: 'sessionid=<sessionid>', 'Content-Type': 'application/json'},
  body: '{"spec":{"connectionRef":"example","region":"example","kubernetesVersion":"example","hibernated":false,"controlPlaneHA":false,"plan":"monthly","network":{"nodeCIDR":"10.250.0.0/16","podCIDR":"example","serviceCIDR":"example","existingNetwork":"example"},"nodePools":[{"name":"example","source":"managed","machineType":"example","image":{"additionalProperty":"example"},"minimum":0,"maximum":3,"publicIP":true}]}}'
};

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

curl --request PUT \
  --url https://example.com/api/v1/teams/example/clusters/example/ \
  --header 'Content-Type: application/json' \
  --cookie sessionid=<sessionid> \
  --data '{ "spec": { "connectionRef": "example", "region": "example", "kubernetesVersion": "example", "hibernated": false, "controlPlaneHA": false, "plan": "monthly", "network": { "nodeCIDR": "10.250.0.0/16", "podCIDR": "example", "serviceCIDR": "example", "existingNetwork": "example" }, "nodePools": [ { "name": "example", "source": "managed", "machineType": "example", "image": { "additionalProperty": "example" }, "minimum": 0, "maximum": 3, "publicIP": true } ] } }'

Writes desired intent. A changed spec returns 202 + an Operation to poll; an unchanged spec is a 200 no-op (docs/58 §5.5).

Authorizations

cookieAuth
ApiKeyAuth

Parameters

Path Parameters

name

required

string

team_slug

required

string

Request Body^required

Request body for PUT …/clusters/{name} — the spec is nested under spec (docs/58 §5).

object

spec

required

Validates a Cluster spec on PUT (docs/58 §3.4). Names/region/connection immutability and pooled-pool invariants are enforced in the viewset against the existing row.

object

connectionRef

required

string

region

required

string

kubernetesVersion

required

string

<= 20 characters

hibernated

boolean

controlPlaneHA

boolean

plan

string

Allowed values: payg monthly annual

network

object

nodeCIDR

10.250.0.0/16 - 10.250.0.0/16
172.18.0.0/16 - 172.18.0.0/16
192.168.128.0/17 - 192.168.128.0/17

string

Allowed values: 10.250.0.0/16 172.18.0.0/16 192.168.128.0/17

podCIDR

string

serviceCIDR

string

existingNetwork

string

nodePools

Array<object>

object

name

required

string

<= 50 characters /^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$/

source

string

Allowed values: managed pooled dedicated onprem

machineType

required

string

<= 20 characters

image

object

key

additional properties

minimum

integer

maximum

integer

default: 3

publicIP

boolean

default: true

Request body for PUT …/clusters/{name} — the spec is nested under spec (docs/58 §5).

object

spec

required

Validates a Cluster spec on PUT (docs/58 §3.4). Names/region/connection immutability and pooled-pool invariants are enforced in the viewset against the existing row.

object

connectionRef

required

string

region

required

string

kubernetesVersion

required

string

<= 20 characters

hibernated

boolean

controlPlaneHA

boolean

plan

string

Allowed values: payg monthly annual

network

object

nodeCIDR

10.250.0.0/16 - 10.250.0.0/16
172.18.0.0/16 - 172.18.0.0/16
192.168.128.0/17 - 192.168.128.0/17

string

Allowed values: 10.250.0.0/16 172.18.0.0/16 192.168.128.0/17

podCIDR

string

serviceCIDR

string

existingNetwork

string

nodePools

Array<object>

object

name

required

string

<= 50 characters /^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$/

source

string

Allowed values: managed pooled dedicated onprem

machineType

required

string

<= 20 characters

image

object

key

additional properties

minimum

integer

maximum

integer

default: 3

publicIP

boolean

default: true

Request body for PUT …/clusters/{name} — the spec is nested under spec (docs/58 §5).

object

spec

required

Validates a Cluster spec on PUT (docs/58 §3.4). Names/region/connection immutability and pooled-pool invariants are enforced in the viewset against the existing row.

object

connectionRef

required

string

region

required

string

kubernetesVersion

required

string

<= 20 characters

hibernated

boolean

controlPlaneHA

boolean

plan

string

Allowed values: payg monthly annual

network

object

nodeCIDR

10.250.0.0/16 - 10.250.0.0/16
172.18.0.0/16 - 172.18.0.0/16
192.168.128.0/17 - 192.168.128.0/17

string

Allowed values: 10.250.0.0/16 172.18.0.0/16 192.168.128.0/17

podCIDR

string

serviceCIDR

string

existingNetwork

string

nodePools

Array<object>

object

name

required

string

<= 50 characters /^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$/

source

string

Allowed values: managed pooled dedicated onprem

machineType

required

string

<= 20 characters

image

object

key

additional properties

minimum

integer

maximum

integer

default: 3

publicIP

boolean

default: true

Responses

200

application/json

A Cluster resource (docs/58 §3.2): {apiVersion, kind, metadata, spec, status}.

object

apiVersion

required

string

kind

required

string

metadata

required

object

name

required

string

required

string

team

required

string

generation

required

integer

observedGeneration

required

integer

etag

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

spec

required

object

key

additional properties

status

required

object

phase

required

string

seedName

required

string

nullable

conditions

required

Array<object>

object

key

additional properties

migrationPhase

required

string

nullable

cost

required

object

key

additional properties

Example ^generated

{
  "apiVersion": "example",
  "kind": "example",
  "metadata": {
    "name": "example",
    "id": "example",
    "team": "example",
    "generation": 1,
    "observedGeneration": 1,
    "etag": "example",
    "createdAt": "2026-04-15T12:00:00Z",
    "updatedAt": "2026-04-15T12:00:00Z"
  },
  "spec": {
    "additionalProperty": "example"
  },
  "status": {
    "phase": "example",
    "seedName": "example",
    "conditions": [
      {
        "additionalProperty": "example"
      }
    ],
    "migrationPhase": "example",
    "cost": {
      "additionalProperty": "example"
    }
  }
}

202

application/json

202 Accepted body for a mutating call (docs/58 §5.3): the queued Operation + the resource as last observed.

object

operation

required

An async Operation resource (docs/58 §3.11, §5.3) — poll to convergence.

object

required

string

kind

required

string

target

required

object

key

additional properties

state

required

string

progress

required

integer

error

required

object

key

additional properties

desiredHash

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

self

required

string

nullable

resource

required

A Cluster resource (docs/58 §3.2): {apiVersion, kind, metadata, spec, status}.

object

apiVersion

required

string

kind

required

string

metadata

required

object

name

required

string

required

string

team

required

string

generation

required

integer

observedGeneration

required

integer

etag

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

spec

required

object

key

additional properties

status

required

object

phase

required

string

seedName

required

string

nullable

conditions

required

Array<object>

object

key

additional properties

migrationPhase

required

string

nullable

cost

required

object

key

additional properties

Example ^generated

{
  "operation": {
    "id": "example",
    "kind": "example",
    "target": {
      "additionalProperty": "example"
    },
    "state": "example",
    "progress": 1,
    "error": {
      "additionalProperty": "example"
    },
    "desiredHash": "example",
    "createdAt": "2026-04-15T12:00:00Z",
    "updatedAt": "2026-04-15T12:00:00Z",
    "self": "example"
  },
  "resource": {
    "apiVersion": "example",
    "kind": "example",
    "metadata": {
      "name": "example",
      "id": "example",
      "team": "example",
      "generation": 1,
      "observedGeneration": 1,
      "etag": "example",
      "createdAt": "2026-04-15T12:00:00Z",
      "updatedAt": "2026-04-15T12:00:00Z"
    },
    "spec": {
      "additionalProperty": "example"
    },
    "status": {
      "phase": "example",
      "seedName": "example",
      "conditions": [
        {
          "additionalProperty": "example"
        }
      ],
      "migrationPhase": "example",
      "cost": {
        "additionalProperty": "example"
      }
    }
  }
}

402

RFC 7807 problem document

application/json

RFC 7807 application/problem+json — every non-2xx response (docs/58 §5.10).

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

Stable machine code clients switch on

string

instance

required

string

nullable

operationId

required

string

nullable

Example ^generated

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

412

RFC 7807 problem document

application/json

RFC 7807 application/problem+json — every non-2xx response (docs/58 §5.10).

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

Stable machine code clients switch on

string

instance

required

string

nullable

operationId

required

string

nullable

Example ^generated

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

422

RFC 7807 problem document

application/json

RFC 7807 application/problem+json — every non-2xx response (docs/58 §5.10).

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

code

required

Stable machine code clients switch on

string

instance

required

string

nullable

operationId

required

string

nullable

Example ^generated

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

Create or update a cluster (declarative PUT)

Authorizations

Parameters

Path Parameters

Request Body required

Responses

200

Example generated

202

Example generated

402

Example generated

412

Example generated

422

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated