Create a cluster
Creates a managed Kubernetes cluster, and the node pools the request
lists, and returns it provisioning. Requires Idempotency-Key.
Managed Kubernetes is enabled per org: without it, the call returns
403 feature_not_enabled.
The control plane runs in our management cluster, as API server pods
whose state is the cluster's own etcd, and is reached at
endpoint.hostname on 443. Nodes are instances that join it. Every
pool in the request is checked before the create is accepted, so a
bad pool refuses the whole create. Wait on observedGeneration and
the conditions, as on any Kubernetes object.
AuthorizationBearer <cc_...>An API key of your org, sent as Authorization: Bearer cc_.... Keys
start with cc_ and are otherwise opaque. Treat a key as a password:
anyone holding it can act with its scopes until it expires or is
revoked. Each operation's security requirement lists the scopes it
needs; an empty list means any valid key. The MCP server at /mcp
accepts agent keys and no other kind.
Scope: clusters:write
Idempotency-Key*stringA unique key for this intent, such as a UUID. Reuse it for every
retry of the same request. A missing key returns
400 idempotency_key_required. See Idempotency above.
^[!-~]+$1 <= length <= 255Api-Version*stringThe API version the request is written against. This document
describes 2026-10-15. A missing header returns
400 api_version_required, and a version the API does not serve
returns 400 unsupported_api_version.
X-Correlation-ID?stringAn id of your own for this request, or for a group of requests, to
find them in our logs and yours. Logged with the request and returned
unchanged in X-Correlation-ID. The request id itself is always the
API's own, in X-Request-ID.
^[A-Za-z0-9._:-]+$1 <= length <= 128Org-Context?stringAdmin keys only: the id of the org to act in. Required with an admin
key, together with Access-Reason; with any other credential it
returns 400 invalid_request. Every request that carries it is
recorded in that org's operator-access log.
^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$5 <= length <= 63Access-Reason?stringAdmin keys only: why the operator is acting in the org, such as a
support ticket. Required with Org-Context. Recorded, verbatim, in
the org's operator-access log.
^[^\x00-\x1F\x7F]+$10 <= length <= 500application/json- body
A managed Kubernetes cluster, and the pools to create with it. Each
field maps to one field of an upstream object: Cluster API's
Cluster and Kamaji's KamajiControlPlane for the cluster, and a
MachineDeployment for each pool.
name*ClusterNameSpecA name unique among the clusters of the project, a deleted one's
included until it is gone: a lowercase DNS label of at most 40
characters that does not begin with cl-, so that no name looks
like a cluster id. It names the cluster's objects in management.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 40project?ProjectNameThe project to create the cluster in. default without it.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63location?LocationIdThe cluster's location and its pools' default, from
GET /v1/locations. Without it, the default location of tee;
without either, 400 invalid_request.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63tee?TeeThe TEE of every node. Without it, the TEE whose default location location is.
kubernetesVersion*KubernetesVersionA supported Kubernetes version, v and its major, minor and patch numbers.
^v[0-9]+\.[0-9]+\.[0-9]+$length <= 32controlPlane?The cluster's API servers, which run as pods in our management cluster, not as instances.
auditLogs?booleanShip the API server's audit log to you, as component audit of
the cluster's logs. Set only at create; a PATCH that changes it
is 400 invalid_request with the violation not_allowed.
falsepaused?booleanStop Cluster API from changing the cluster, as spec.paused
does: machines being created finish, and nothing new starts.
falsenodePools?array<>Pools to create with the cluster, as POST /v1/clusters/{id}/node-pools takes them. Optional; pools can be added later.
items <= 16[]labels?Up to 64 labels, as in Kubernetes. A key is an optional prefix and
/, then a name of up to 63 letters, digits, -, _ and .,
starting and ending with a letter or digit. The prefix is a DNS
subdomain of at most 253 characters, and prefixes in the domains
confidential.ai, kubernetes.io and k8s.io are reserved for the
platform. A value is empty or follows the same rule as the name.
Labels are not secret: never put a secret in one.
properties <= 64Accepted, with the cluster's new generation. Management converges
on it from here; observedGeneration reaches it once it has. A
replay returns the cluster's current state.
application/json- response
A managed Kubernetes cluster. It never holds a credential.
id*ClusterIdcl- and 16 lowercase hex digits, a DNS label that names the cluster in management.
^cl-[0-9a-f]{16}$name*stringlength <= 63project*ProjectNameA project name. default is the only project in this version.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63location*LocationIdA location id from GET /v1/locations, such as us-west-1.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63tee*TeeThe trusted execution environment. Open set; accept values not listed.
kubernetesVersion*KubernetesVersionThe version the cluster asks for. The control plane reports the one it runs in the conditions.
^v[0-9]+\.[0-9]+\.[0-9]+$length <= 32c8sRelease*C8sReleaseThe c8s release the cluster runs, until an upgrade to another is done.
^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9]+-g[0-9a-f]{7,40})?$length <= 63upgrade?The cluster's upgrade, absent when it has none. kubernetesVersion
stays what the cluster runs until the upgrade is done.
controlPlane*auditLogs*booleanpaused*booleanstatus*ClusterStatusOpen set; accept values not listed. provisioning until the control
plane first becomes available; running; updating while Cluster
API rolls out or scales; unknown while Cluster API cannot reach the
cluster's API server (RemoteConnectionProbe is False) or cannot
tell whether it is available (Available is Unknown): its
workloads probably still run; terminating after a delete, until
Cluster API has torn it down. A cluster that answers but is not
available stays running, with Available False and its reason.
statusChangedAt*stringWhen status last changed.
date-timeconditions*array<>The Cluster's conditions. A new cluster has none.
generation*integerThe Cluster's metadata.generation, which every accepted change to the cluster or its pools raises.
1 <= valueobservedGeneration*integerThe last generation Cluster API has reconciled, which its topology has rendered. 0 until it has reconciled the first.
0 <= valueendpoint*Where the cluster's API server is reached. Workers join and kubelets connect at the same hostname.
labels*Labels. May include keys with a reserved prefix, such as cloud.confidential.ai/, which the platform sets.
createdAt*stringWhen the create was accepted.
date-timecurl -X POST 'https://api.cloud.confidential.ai/v1/clusters' \ -H 'Idempotency-Key: 0b9d6c1e-5f8a-4c2e-9a51-2f7e0c3d4b18' \ -H 'Api-Version: 2026-10-15' \ -H 'X-Correlation-ID: rollout-2026-10-22' \ -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed' \ -H 'Content-Type: application/json' \ -d '{ "name": "inference", "location": "us-west-1", "tee": "tdx", "kubernetesVersion": "v1.36.4", "controlPlane": { "replicas": 3 }, "auditLogs": true, "nodePools": [ { "name": "web", "size": "c1.4x", "replicas": 2 }, { "name": "gpu", "size": "g1-b300.2x", "autoscaling": { "min": 0, "max": 2 }, "reservation": "r-5mf2k9x3qp" } ], "labels": { "team": "inference" }}'{ "id": "cl-0123456789abcdef", "name": "inference", "project": "default", "location": "us-west-1", "tee": "tdx", "kubernetesVersion": "v1.36.4", "c8sRelease": "v0.99.35-4-ga8ecf448d", "controlPlane": { "replicas": 3, "size": "small" }, "auditLogs": true, "paused": false, "status": "provisioning", "statusChangedAt": "2026-10-24T22:00:00Z", "conditions": [], "generation": 1, "observedGeneration": 0, "endpoint": { "hostname": "cl-0123456789abcdef.us-west-1.k8s.confidential.ai" }, "labels": { "team": "inference" }, "createdAt": "2026-10-24T22:00:00Z"}List clusters GET
Lists the org's clusters, newest first, as management holds them. A deleted cluster is listed `terminating` until Cluster API has torn it down, and not at all after. An org without managed Kubernetes has none.
Get a cluster GET
Returns the cluster, `terminating` while Cluster API tears a deleted one down. Once it is gone, `404`.