Create cluster API Reference

POST

/tenants/{tenant}/clusters

curl --request POST \
  --url https://api.kupe.cloud/api/v1/tenants/acme/clusters \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "alerts": {}, "displayName": "Production Cluster", "highAvailability": true, "name": "production", "resources": { "cpu": "4", "memory": "16Gi", "storage": "100Gi" }, "version": "1.32" }'

Create a new managed Kubernetes cluster. The cluster is provisioned asynchronously: poll the GET endpoint and check status.phase until it reaches “Running”.

Authorizations

• BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

Request Body

Cluster configuration

Media type application/json

object

alerts

Alert configuration (free-form object)

object

displayName

Deprecated: accepted for backward compatibility and ignored (the cluster name is the identifier).

string

Example

Production Cluster

highAvailability

boolean

Example

true

name

Cluster name (DNS-safe) without “–”. At most 52 characters minus the length of the tenant name.

string

Example

production

resources

Resource allocations using Kubernetes quantity format

object

cpu

string

Example

4

memory

string

Example

16Gi

storage

string

Example

100Gi

version

Kubernetes version (optional; when omitted the platform default version is used)

string

Example

1.32

Responses

201

Cluster created

Media type application/json

object

alerts

object

key

additional properties

createdAt

string

displayName

Deprecated: always equal to name (the CRD has no display name; the cluster name is the identifier).

string

highAvailability

boolean

name

string

resourceVersion

string

resources

object

cpu

string

memory

string

storage

string

status

object

conditions

Array<object>

object

key

additional properties

endpoint

string

haConfigured

boolean

haPhase

HAPhase is the consumer-friendly HA rollup. One of pending, ha-healthy, ha-degraded, ha-unavailable. Empty for non-HA clusters.

string

kubernetesVersion

string

metrics

object

key

additional properties

phase

string

version

string

warnings

Warnings is an array of structured advisory messages. Always present (empty array when none). Populated today only by CREATE when a non-blocking advisory applies (e.g. HA_K8S_VERSION_RETIRING when HA is enabled on the oldest supported k8s minor). Each entry shares the same shape as a structured error envelope.

Array<object>

object

code

string

field

string

message

string

severity

string

Example

{
  "createdAt": "2026-02-01T14:00:00Z",
  "displayName": "production",
  "highAvailability": true,
  "name": "production",
  "resourceVersion": "294810",
  "resources": {
    "cpu": "4",
    "memory": "16Gi",
    "storage": "100Gi"
  },
  "status": {
    "endpoint": "https://production.acme.clusters.kupe.cloud",
    "haConfigured": true,
    "haPhase": "ha-healthy",
    "kubernetesVersion": "v1.32.3",
    "phase": "Running"
  },
  "version": "1.32",
  "warnings": [
    {
      "code": "HA_K8S_VERSION_RETIRING",
      "field": "spec.highAvailability",
      "message": "Cluster's Kubernetes version (1.33) is approaching end-of-life on this platform. Plan an upgrade before enabling high availability.",
      "severity": "warning"
    }
  ]
}

Headers

ETag

string

Resource version

400

Validation error, a name too long for the tenant (code CLUSTER_NAME_TOO_LONG), cluster creation is paused (code creation_paused), or the plan’s cluster limit is reached (code plan_limit_reached)

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

401

Missing or invalid authentication

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Admin access required

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

409

Cluster name already exists, or the tenant is being deleted (code tenant_terminating), suspended (code tenant_suspended) or awaiting a payment method (code payment_setup_required)

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Rate limit exceeded

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

503

The tenant’s limit is still being set up (a new tenant’s first seconds); retry in a few seconds

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}