Get a cluster
Returns the cluster, terminating while Cluster API tears a deleted one down. Once it is gone, 404.
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:read
id*stringThe cluster id.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63Api-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 <= 500The cluster.
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 GET 'https://api.cloud.confidential.ai/v1/clusters/cl-0123456789abcdef' \ -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'{ "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": "running", "statusChangedAt": "2026-10-24T22:05:12Z", "conditions": [ { "type": "Available", "status": "True", "reason": "Available", "lastTransitionTime": "2026-10-24T22:05:12Z", "observedGeneration": 1 }, { "type": "ControlPlaneInitialized", "status": "True", "reason": "Initialized", "lastTransitionTime": "2026-10-24T22:02:40Z", "observedGeneration": 1 } ], "generation": 2, "observedGeneration": 2, "endpoint": { "hostname": "cl-0123456789abcdef.us-west-1.k8s.confidential.ai" }, "labels": { "team": "inference" }, "createdAt": "2026-10-24T22:00:00Z"}Create a cluster POST
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.
Change a cluster PATCH
Sets the cluster's desired state, as a JSON merge patch of the fields it names, and returns `202` with the cluster and its new `generation`. Raising `kubernetesVersion` upgrades the control plane and then each pool that does not defer. Sending what the cluster already has changes nothing and keeps its generation. A cluster that is `terminating` cannot change (`409 invalid_state`). A change that crosses another is made again on the cluster as the other left it.