> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Clusters

> The clusters operations of the v1 API.

## List the clusters the key can open

`GET /v1/clusters` (operation ID `list_clusters`)

Organization owners and admins see every cluster of the organization, other members the clusters of their environments. Deleted clusters are left out. Ordered by creation time, oldest first. Cursor paginated.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cursor` (query, `string`): Opaque cursor from the previous page's `next_cursor`.
- `limit` (query, `integer`): Page size, 1 to 100 (default 25).

**Responses**

- `200`: A page of clusters. Body: [`V1Page_for_V1Cluster`](/api/reference/schemas#v1page_for_v1cluster).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/clusters' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Create a cluster

`POST /v1/clusters` (operation ID `create_cluster`)

The cluster starts in `provisioning`; its servers are ordered in the background. The balance must cover the first hours of the order. Send an `Idempotency-Key` to make a retry safe.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `Idempotency-Key` (header, `string`): Optional client-chosen key (1-255 visible ASCII characters). A retry with the same key and body within 24 hours replays the first response instead of creating again; the same key with a different body is a 422, and a retry while the first request still runs is a 409.

**Request body**: [`V1CreateCluster`](/api/reference/schemas#v1createcluster) (required): A cluster to create.

**Responses**

- `201`: The created cluster. Body: [`V1Cluster`](/api/reference/schemas#v1cluster).
- `400`: Invalid name, region, provider, environment, pool or system extension, or terms of service not accepted.
- `401`: Missing, invalid or revoked API key.
- `402`: The billing account is blocked (`billing_account_blocked`: negative balance, low balance, grace period or suspended), or the balance does not cover the order.
- `403`: The key is read-only.
- `409`: The name is taken, the quoted price or availability changed, or a request with the same Idempotency-Key is in progress.
- `422`: Missing or unknown body fields, invalid storage copies, or an Idempotency-Key reused with a different body.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).
- `503`: The extension catalog is unreachable.

```bash
curl -X POST 'https://api.a-line.cloud/v1/clusters' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"environment_id":"00000000-0000-4000-8000-000000000001","name":"example","pools":[],"provider":"example","region":"example"}'
```

## Get one cluster

`GET /v1/clusters/{cluster_id}` (operation ID `get_cluster`)

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID

**Responses**

- `200`: The cluster. Body: [`V1Cluster`](/api/reference/schemas#v1cluster).
- `400`: Malformed cluster id.
- `401`: Missing, invalid or revoked API key.
- `404`: Cluster not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Delete a cluster

`DELETE /v1/clusters/{cluster_id}` (operation ID `delete_cluster`)

The cluster moves to `deleting` and its servers are removed in the background; deleting a cluster already `deleting` answers the same. Deletes stay open on a blocked billing account.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `acknowledge_commitment` (query, `boolean`): Remove committed monthly machines although they stay billed to the end of their term.
- `acknowledge_iac` (query, `boolean`): Delete although a file of the infra link still defines the cluster (the link then proposes creating it again).
- `confirm` (query, `string`): The cluster's name, required when volumes go with it. Deleting volumes needs a signed-in user's step-up: an API key sending it gets 403 `step_up_unavailable`.
- `cluster_id` (path, required, `string`): The cluster UUID

**Responses**

- `202`: The cluster is being deleted. Body: [`V1DeletedCluster`](/api/reference/schemas#v1deletedcluster).
- `400`: Malformed cluster id or unknown query parameters.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only, its user is not an admin of the cluster's environment, or the request has `confirm` (`step_up_unavailable`: deleting volumes needs a signed-in user's step-up).
- `404`: Cluster not found.
- `409`: The cluster has volumes (delete them in the dashboard, which confirms with the cluster name), committed monthly machines (`?acknowledge_commitment=true`) or a file of the infra link defines it (`cluster_managed_in_git`; `?acknowledge_iac=true`).
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X DELETE 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## List a cluster's nodes

`GET /v1/clusters/{cluster_id}/nodes` (operation ID `list_cluster_nodes`)

The nodes that are not deleted, with their pool's name and addresses. Ordered by creation time, oldest first. Cursor paginated.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cursor` (query, `string`): Opaque cursor from the previous page's `next_cursor`.
- `limit` (query, `integer`): Page size, 1 to 100 (default 25).
- `cluster_id` (path, required, `string`): The cluster UUID

**Responses**

- `200`: A page of nodes. Body: [`V1Page_for_V1Node`](/api/reference/schemas#v1page_for_v1node).
- `400`: Malformed cluster id, invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `404`: Cluster not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/nodes' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```
