Docs
Clusters

Upload the launch file and pin of a cluster's CDS

PUT
/v1/clusters/{id}/cds/launch

Takes the two files c8s cds config new wrote for the cluster, the launch file every CDS replica boots and the pin that binds it to the release's CDS image, and starts the replicas from them. The bytes are stored as they are: clients pin the launch file and every worker document carries the pin, so nothing is rendered or substituted here.

Each file is checked against what this cluster's CDS must be, and a file that fails returns 400 invalid_request naming the field: the cluster's id, its replica names, its router's DNS name, its location's guest subnet, a voter seat for each API server replica, the c8s release's allowlist seed, and, for the pin, the measurements of that release's CDS image bound to this launch file. A launch file that names nodes, a Pod image policy or a KMS is refused. GET /v1/clusters/{id}/cds serves every input the command takes.

The two files are taken once: a second upload is 409 invalid_state, and a terminating cluster the same. Returns 202 with the cluster; GET /v1/clusters/{id}/cds then shows the replicas starting.

Authorization

headerAuthorizationBearer <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

Path Parameters

id*string

The cluster id.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63

Header Parameters

Api-Version*string

The 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?string

An 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.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin 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.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin 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.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Request Body

application/json
  1. body

The two files c8s cds config new wrote for the cluster, each the exact bytes that are measured, in base64.

launchFile*string

cds-config.yaml, the c8s-cds/v1 launch file every replica boots, at most 64 KiB before encoding.

Formatbyte
pin*string

cds-pin.json, the measurements document binding the release's CDS image to the launch file, which every worker document carries.

Formatbyte

Response Body

The launch file and the pin are stored as uploaded. The cluster's CDS replicas launch from them, and every worker document carries the pin.

application/json
  1. response

A managed Kubernetes cluster. It never holds a credential.

id*ClusterId

cl- and 16 lowercase hex digits, a DNS label that names the cluster in management.

Match^cl-[0-9a-f]{16}$
name*string
Lengthlength <= 63
project*ProjectName

A project name. default is the only project in this version.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
location*LocationId

A location id from GET /v1/locations, such as us-west-1.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
tee*Tee

The trusted execution environment. Open set; accept values not listed.

kubernetesVersion*KubernetesVersion

The version the cluster asks for. The control plane reports the one it runs in the conditions.

Match^v[0-9]+\.[0-9]+\.[0-9]+$
Lengthlength <= 32
c8sRelease*C8sRelease

The c8s release the cluster runs, until an upgrade to another is done.

Match^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9]+-g[0-9a-f]{7,40})?$
Lengthlength <= 63
upgrade?

The cluster's upgrade, absent when it has none. kubernetesVersion stays what the cluster runs until the upgrade is done.

controlPlane*
auditLogs*boolean
paused*boolean
status*ClusterStatus

Open 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*string

When status last changed.

Formatdate-time
conditions*array<>

The Cluster's conditions. A new cluster has none.

generation*integer

The Cluster's metadata.generation, which every accepted change to the cluster or its pools raises.

Range1 <= value
observedGeneration*integer

The last generation Cluster API has reconciled, which its topology has rendered. 0 until it has reconciled the first.

Range0 <= value
endpoint*

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*string

When the create was accepted.

Formatdate-time
Example Request
curl -X PUT 'https://api.cloud.confidential.ai/v1/clusters/cl-0123456789abcdef/cds/launch' \  -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 '{  "launchFile": "c2NoZW1hVmVyc2lvbjogYzhzLWNkcy92MQo=",  "pin": "eyJzY2hlbWFfdmVyc2lvbiI6IjIifQo="}'
Example Response
{  "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"}