> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CKS API Reference

> REST API reference for creating, listing, updating, and deleting CoreWeave CKS clusters

With an access token, you can interact with the CKS API using `curl` or any other HTTP client. The API allows you to create, list, update, and delete CKS clusters.

<Info>
  * The API server is `https://api.coreweave.com`.
  * Replace `{API_ACCESS_TOKEN}` in the examples below with your [CoreWeave API access token](/security/authn-authz/manage-api-access-tokens).
</Info>

## Reference table

| Endpoint                                                         | Method                                     | Description                             |
| ---------------------------------------------------------------- | ------------------------------------------ | --------------------------------------- |
| [`/v1beta1/cks/clusters`](#get-/v1beta1/cks/clusters)            | [GET](#get-/v1beta1/cks/clusters)          | List all clusters.                      |
| [`/v1beta1/cks/clusters`](#post-/v1beta1/cks/clusters)           | [POST](#post-/v1beta1/cks/clusters)        | Create a cluster.                       |
| [`/v1beta1/cks/clusters/{id}`](#get-/v1beta1/cks/clusters/id)    | [GET](#get-/v1beta1/cks/clusters/id)       | Get a cluster's information by ID.      |
| [`/v1beta1/cks/clusters/{id}`](#delete-/v1beta1/cks/clusters/id) | [DELETE](#delete-/v1beta1/cks/clusters/id) | Delete a cluster by ID.                 |
| [`/v1beta1/cks/clusters/{id}`](#patch-/v1beta1/cks/clusters/id)  | [PATCH](#patch-/v1beta1/cks/clusters/id)   | Update a cluster's configuration by ID. |

## Clusters

To list or create CKS clusters, use the `/v1beta1/cks/clusters` endpoint. The API supports the `GET` and `POST` methods.

### GET /v1beta1/cks/clusters

To list all CKS clusters, use the `GET` method with the `/v1beta1/cks/clusters` endpoint.

```bash title="Example request" theme={"system"}
curl -X GET https://api.coreweave.com/v1beta1/cks/clusters \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer {API_ACCESS_TOKEN}"
```

A successful response returns an array of CKS cluster objects. The fields returned are:

```json title="Response status code 200" theme={"system"}
{
  "items": [
    {
      "id": string,
      "name": string,
      "zone": string,
      "vpcId": string,
      "public": boolean,
      "version": string,
      "network": {
        "podCidrName": string,
        "serviceCidrName": string,
        "internalLbCidrNames": Array of strings
      },
      "oidc": {
        "issuerUrl": string,
        "clientId": string,
        "usernameClaim": string,
        "usernamePrefix": string,
        "groupsClaim": string,
        "groupsPrefix": string,
        "ca": string,
        "requiredClaim": string,
      "signingAlgorithms": Array of integers <enum> [ items <enum > ],
      },
      "authzWebhook": {
        "server": string,
        "ca": string
      },
      "authnWebhook": {
        "server": string,
        "ca": string
      },
      "auditPolicy": string,
      "status": integer <enum>,
      "apiServerEndpoint": string,
      "createdAt": string <date-time>,
      "updatedAt": string <date-time>
    }
  ]
}
```

### POST /v1beta1/cks/clusters

To create a CKS cluster, use the `POST` method with the `/v1beta1/cks/clusters` endpoint.

The cluster configuration must be supplied as a JSON object in the request body. The following fields are required in the request:

* `name`
* `zone`
* `vpcId`
* `public`
* `version`
* `network.podCidrName`
* `network.serviceCidrName`
* `network.internalLbCidrNames`
* `oidc.issuerUrl`
* `oidc.clientId`
* `authzWebhook.server`
* `authnWebhook.server`

<Note>
  - Create a VPC before creating a cluster, and supply the `vpcId` in the cluster configuration.
  - The cluster `id` should not be supplied in the request body; it is assigned and returned in the response.
</Note>

The supported fields and their data types are as follows.

```json title="data.json" theme={"system"}
    {
      "name": string,
      "zone": string,
      "vpcId": string,
      "public": boolean,
      "version": string,
      "network": {
        "podCidrName": string,
        "serviceCidrName": string,
        "internalLbCidrNames": Array of strings
      },
      "oidc": {
        "issuerUrl": string,
        "clientId": string,
        "usernameClaim": string,
        "usernamePrefix": string,
        "groupsClaim": string,
        "groupsPrefix": string,
        "ca": string,
        "requiredClaim": string,
      "signingAlgorithms": Array of integers <enum> [ items <enum > ],
      },
      "authzWebhook": {
        "server": string,
        "ca": string
      },
      "authnWebhook": {
        "server": string,
        "ca": string
      },
      "auditPolicy": string
    }
```

Submit the request, passing the JSON object in the body as `data.json`.

```bash title="Example request" theme={"system"}
curl -X POST https://api.coreweave.com/v1beta1/cks/clusters \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer {API_ACCESS_TOKEN}" \
       -d @data.json
```

A successful response returns a cluster object, with the newly-assigned `id`.

```json title="Response status code 200" theme={"system"}
{
  "cluster": {
    "id": string,
    "name": string,
    "zone": string,
    "vpcId": string,
    "public": boolean,
    "version": string,
    "network": {
      "podCidrName": string,
      "serviceCidrName": string,
      "internalLbCidrNames": Array of strings
    },
    "oidc": {
      "issuerUrl": string,
      "clientId": string,
      "usernameClaim": string,
      "usernamePrefix": string,
      "groupsClaim": string,
      "groupsPrefix": string,
      "ca": string,
      "requiredClaim": string,
      "signingAlgorithms": Array of integers <enum> [ items <enum > ],
    },
    "authzWebhook": {
      "server": string,
      "ca": string
    },
    "authnWebhook": {
      "server": string,
      "ca": string
    },
    "auditPolicy": string,
    "status": integer <enum>,
    "apiServerEndpoint": string,
    "createdAt": string <date-time>,
    "updatedAt": string <date-time>
  }
}
```

## Cluster by ID

To retrieve, update, or delete a CKS cluster by ID, use the `/v1beta1/cks/clusters/{id}` endpoint. The API supports the `GET`, `PATCH`, and `DELETE` methods.

### GET /v1beta1/cks/clusters/\{id}

To get information about a CKS cluster, use the `GET` method with the `/v1beta1/cks/clusters/{id}` endpoint. Substitute `{id}` with the cluster ID.

```bash title="Example request" theme={"system"}
curl -X GET https://api.coreweave.com/v1beta1/cks/clusters/{id} \
       -H "Content-Type: application/json" \
        -H "Authorization: Bearer {API_ACCESS_TOKEN}"
```

A successful response returns the cluster object.

```json title="Response status code 200" theme={"system"}
{
  "cluster": {
    "id": string,
    "name": string,
    "zone": string,
    "vpcId": string,
    "public": boolean,
    "version": string,
    "network": {
      "podCidrName": string,
      "serviceCidrName": string,
      "internalLbCidrNames": Array of strings
    },
    "oidc": {
      "issuerUrl": string,
      "clientId": string,
      "usernameClaim": string,
      "usernamePrefix": string,
      "groupsClaim": string,
      "groupsPrefix": string,
      "ca": string,
      "requiredClaim": string,
      "signingAlgorithms": Array of integers <enum> [ items <enum > ],
    },
    "authzWebhook": {
      "server": string,
      "ca": string
    },
    "authnWebhook": {
      "server": string,
      "ca": string
    },
    "auditPolicy": string,
    "status": integer <enum>,
    "apiServerEndpoint": string,
    "createdAt": string <date-time>,
    "updatedAt": string <date-time>
  }
}
```

### DELETE /v1beta1/cks/clusters/\{id}

To delete a CKS cluster, use the `DELETE` method with the `/v1beta1/cks/clusters/{id}` endpoint. Substitute `{id}` with the cluster ID.

```bash title="Example request" theme={"system"}
curl -X DELETE https://api.coreweave.com/v1beta1/cks/clusters/{id} \
       -H "Content-Type: application/json" \
        -H "Authorization: Bearer {API_ACCESS_TOKEN}"
```

A successful response returns the deleted cluster object.

```json title="Response status code 200" theme={"system"}
{
  "cluster": {
    "id": string,
    "name": string,
    "zone": string,
    "vpcId": string,
    "public": boolean,
    "version": string,
    "network": {
      "podCidrName": string,
      "serviceCidrName": string,
      "internalLbCidrNames": Array of strings
    },
    "oidc": {
      "issuerUrl": string,
      "clientId": string,
      "usernameClaim": string,
      "usernamePrefix": string,
      "groupsClaim": string,
      "groupsPrefix": string,
      "ca": string,
      "requiredClaim": string,
      "signingAlgorithms": Array of integers <enum> [ items <enum > ],
    },
    "authzWebhook": {
      "server": string,
      "ca": string
    },
    "authnWebhook": {
      "server": string,
      "ca": string
    },
    "auditPolicy": string,
    "status": integer <enum>,
    "apiServerEndpoint": string,
    "createdAt": string <date-time>,
    "updatedAt": string <date-time>
  }
}
```

### PATCH /v1beta1/cks/clusters/\{id}

To perform a partial update of a CKS cluster's configuration, use the `PATCH` method with the `/v1beta1/cks/clusters/{id}` endpoint. Substitute `{id}` with the cluster ID. This method uses a field mask, provided in the `updateMask` field, to specify which fields to modify. For more information on field masks, see the [Google AIP guidance](https://google.aip.dev/157).

The cluster configuration must be supplied as a JSON object in the request body. The following fields are required in the request:

* `id`
* `version`

Note: The following fields **are not** required when patching unless you're updating them specifically:

* `oidc.issuerUrl`
* `oidc.clientId`
* `authzWebhook.server`
* `authnWebhook.server`

<Info>
  **Example: Upgrading a cluster version**

  To upgrade a cluster, provide the new version number in the `version` field and specify `"version"` in the `updateMask`. See [Upgrade Kubernetes](/products/cks/clusters/upgrade-kubernetes) for more information.

  For example, to upgrade a cluster to version `1.32`, the request body would include:

  ```json theme={"system"}
  {
    "version": "1.32",
    "updateMask": "version"
  }
  ```

  Remember to include all other required fields in your request.
</Info>

The supported fields and their data types are as follows.

```json title="data.json" theme={"system"}
    {
      "id": string,
      "updateMask": string <field-mask>,
      "public": boolean,
      "version": string,
      "oidc": {
        "issuerUrl": string,
        "clientId": string,
        "usernameClaim": string,
        "usernamePrefix": string,
        "groupsClaim": string,
        "groupsPrefix": string,
        "ca": string,
        "requiredClaim": string,
        "signingAlgorithms": Array of integers <enum> [ items <enum > ],
      },
      "authzWebhook": {
        "server": string,
        "ca": string
      },
      "authnWebhook": {
        "server": string,
        "ca": string
      },
      "auditPolicy": string,
    }
```

Submit the request, passing the JSON object in the body as `data.json`.

```bash title="Example request" theme={"system"}
curl -X PATCH https://api.coreweave.com/v1beta1/cks/clusters/{id} \
       -H "Content-Type: application/json" \
        -H "Authorization: Bearer {API_ACCESS_TOKEN}" \
        -d @data.json
```

A successful response returns the updated cluster object.

```json title="Response status code 200" theme={"system"}
{
  "cluster": {
    "id": string,
    "name": string,
    "zone": string,
    "vpcId": string,
    "public": boolean,
    "version": string,
    "network": {
      "podCidrName": string,
      "serviceCidrName": string,
      "internalLbCidrNames": Array of strings
    },
    "oidc": {
      "issuerUrl": string,
      "clientId": string,
      "usernameClaim": string,
      "usernamePrefix": string,
      "groupsClaim": string,
      "groupsPrefix": string,
      "ca": string,
      "requiredClaim": string,
      "signingAlgorithms": Array of integers <enum> [ items <enum > ],
    },
    "authzWebhook": {
      "server": string,
      "ca": string
    },
    "authnWebhook": {
      "server": string,
      "ca": string
    },
    "auditPolicy": string,
    "status": integer <enum>,
    "apiServerEndpoint": string,
    "createdAt": string <date-time>,
    "updatedAt": string <date-time>
  }
}
```