# Clusters

> Source: https://developers.cloud66.com/v3/endpoints/clusters/

## Get Cluster

URL: https://developers.cloud66.com/v3/endpoints/clusters/#show
Endpoint: GET /clusters/:id
OAuth scope: public

Returns comprehensive details about the specified Kubernetes cluster.

Includes all associated metadata, node information, and related resources based on user permissions. Optionally includes cluster logs when requested.

**Related models:** Cluster, Node

<ResponseCodes 
  codes={[200, 401, 403, 404]}
  overrides={{
    200: "Success - Returns cluster details",
    403: "Forbidden - OAuth token lacks required `public` scope",
    404: "Not Found - Cluster not found"
  }}
/>

### Parameters

- `id` (string, optional) — Cluster UID
- `show_log` (string, optional) — Whether to show log in the response

### Response

```json
{
  "response": {
    "id": 123,
    "uid": "5999b763474b0eafa5fafb64bff0ba80",
    "name": "Production Cluster",
    "environment": "production",
    "cloud": "AWS",
    "region": "us-east-1",
    "status": 1,
    "health": 3,
    "kubernetes_version": "1.28.2",
    "node_count": 5,
    "nodes": [
      {
        "name": "node-1",
        "status": "Ready",
        "instance_type": "m5.large",
        "capacity": {
          "cpu": "2",
          "memory": "8Gi",
          "pods": "29"
        }
      }
    ],
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-01-15T11:00:00Z",
    "created_at_iso": "2023-01-15T10:30:00Z",
    "updated_at_iso": "2023-01-15T11:00:00Z"
  }
}
```

---

## List Clusters

URL: https://developers.cloud66.com/v3/endpoints/clusters/#list
Endpoint: GET /clusters
OAuth scope: public

Retrieves a paginated list of all Kubernetes clusters the user can access.

Returns a paginated collection of cluster resources that the authenticated user has access to. Clusters represent managed Kubernetes environments for container orchestration.

**Related models:** Cluster, Pagination

<ResponseCodes 
  codes={[200, 401, 403]}
  overrides={{
    200: "Success - Returns paginated list of clusters",
    403: "Forbidden - OAuth token lacks required `public` scope"
  }}
/>

### Parameters

- `page` (string, optional) — Page number for pagination (defaults to 1, minimum 1)

### Response

```json
{
  "response": [
    {
      "id": 123,
      "uid": "5999b763474b0eafa5fafb64bff0ba80",
      "name": "Production Cluster",
      "environment": "production",
      "cloud": "AWS",
      "status": 1,
      "health": 3,
      "kubernetes_version": "1.28.2",
      "node_count": 5,
      "created_at": "2023-01-15T10:30:00Z",
      "updated_at": "2023-01-15T11:00:00Z",
      "created_at_iso": "2023-01-15T10:30:00Z",
      "updated_at_iso": "2023-01-15T11:00:00Z"
    },
    {
      "id": 124,
      "uid": "6000c874585c1fbfb6gbc75cgg1cb91",
      "name": "Staging Cluster",
      "environment": "staging", 
      "cloud": "DigitalOcean",
      "status": 1,
      "health": 3,
      "kubernetes_version": "1.28.1",
      "node_count": 3,
      "created_at": "2023-01-10T14:20:00Z",
      "updated_at": "2023-01-10T15:00:00Z",
      "created_at_iso": "2023-01-10T14:20:00Z",
      "updated_at_iso": "2023-01-10T15:00:00Z"
    }
  ],
  "count": 2,
  "pagination": {
    "previous": null,
    "next": null,
    "current": 1,
    "per_page": 100,
    "count": 2,
    "pages": 1
  }
}
```

---

## Create Cluster

URL: https://developers.cloud66.com/v3/endpoints/clusters/#create
Endpoint: POST /clusters
OAuth scope: redeploy

Creates a new Kubernetes cluster with the provided parameters.

<Callout type="info" title="Not Yet Implemented">
This endpoint is not yet implemented and will return a "Not implemented yet" error. Cluster creation functionality is planned for future releases.
</Callout>

**Related models:** Cluster

<ResponseCodes 
  codes={[501, 401, 403]}
  overrides={{
    501: "Not Implemented - Cluster creation not yet available",
    403: "Forbidden - OAuth token lacks required `redeploy` scope"
  }}
/>

### Response

```json
{
  "response": {
    "message": "Not implemented yet",
    "status": "not_implemented"
  }
}
```

---

## Reboot Cluster Servers

URL: https://developers.cloud66.com/v3/endpoints/clusters/#reboot-servers
Endpoint: POST /clusters/:id/reboot_servers
OAuth scope: admin

Executes reboot operations on servers within the specified Kubernetes cluster.

This operation is performed asynchronously and returns an async action object to track progress. Requires admin permissions on the cluster resource.

**Related models:** Cluster, AsyncAction, Server

The async action can be monitored using the [Get Stack Action](/v3/endpoints/stacks/action-get) endpoint to track the reboot progress.

<ResponseCodes 
  codes={[200, 401, 403, 404]}
  overrides={{
    200: "Success - Returns async action to track server reboot",
    403: "Forbidden - OAuth token lacks required `admin` scope or insufficient permissions",
    404: "Not Found - Cluster not found"
  }}
/>

### Parameters

- `id` (string, optional) — Cluster UID
- `strategy` (string, optional) — Reboot strategy (optional)
- `group` (string, optional) — Server group to reboot (optional)

### Response

```json
{
  "response": {
    "id": 789,
    "status": "queued",
    "action_type": "stack_reboot",
    "resource_type": "stack",
    "resource_id": 123,
    "started_via": "api",
    "started_at": null,
    "finished_at": null,
    "finished_success": null,
    "finished_message": null,
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-01-15T10:30:00Z"
  }
}
```