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

# Projects

> The projects operations of the v1 API.

## List the projects of a cluster

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

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 projects. Body: [`V1Page_for_V1Project`](/api/reference/schemas#v1page_for_v1project).
- `400`: Invalid limit or cursor, or a malformed cluster id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's user cannot read this cluster.
- `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/projects' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Create a project in a cluster

`POST /v1/clusters/{cluster_id}/projects` (operation ID `create_project`)

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.
- `cluster_id` (path, required, `string`): The cluster UUID

**Request body**: [`V1CreateProject`](/api/reference/schemas#v1createproject) (required): A project to create.

**Responses**

- `201`: The created project. Body: [`V1Project`](/api/reference/schemas#v1project).
- `400`: Invalid or reserved name, invalid display name, or malformed JSON.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only, or its user is not a member of the cluster's environment.
- `404`: Cluster not found.
- `409`: The name is already taken in the cluster or its environment, or a request with the same Idempotency-Key is in progress.
- `422`: Missing or unknown body fields, 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).

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

## Get one project

`GET /v1/clusters/{cluster_id}/projects/{project_id}` (operation ID `get_project`)

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

**Parameters**

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

**Responses**

- `200`: The project. Body: [`V1Project`](/api/reference/schemas#v1project).
- `400`: Malformed cluster or project id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read this cluster.
- `404`: Project 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/projects/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Update a project's display name or isolation

`PATCH /v1/clusters/{cluster_id}/projects/{project_id}` (operation ID `update_project`)

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

**Parameters**

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

**Request body**: [`V1UpdateProject`](/api/reference/schemas#v1updateproject) (required): Changes to a project; at least one field. The name is fixed at creation; `isolated` switches the app network.

**Responses**

- `200`: The updated project. Body: [`V1Project`](/api/reference/schemas#v1project).
- `400`: Invalid display name, no fields, opening a hosted project, or malformed JSON.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only, its user is not a member of the project's environment, or the field is managed by IaC.
- `404`: Project not found.
- `422`: Unknown body fields (the name cannot change).
- `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 PATCH 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/projects/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"display_name":"example","isolated":false}'
```

## Delete a project

`DELETE /v1/clusters/{cluster_id}/projects/{project_id}` (operation ID `delete_project`)

A hard delete: the project cannot be recovered.

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

**Parameters**

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

**Responses**

- `204`: Project deleted.
- `400`: Malformed cluster or project id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only, or its user is not a member of the project's environment.
- `404`: Project 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 -X DELETE 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/projects/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Get a project's outbound mode and allowlist

`GET /v1/clusters/{cluster_id}/projects/{project_id}/egress` (operation ID `get_project_egress`)

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

**Parameters**

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

**Responses**

- `200`: The project's outbound settings. Body: [`ProjectEgressResponse`](/api/reference/schemas#projectegressresponse).
- `400`: Malformed cluster or project id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's user cannot read this project.
- `404`: Cluster or project 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/projects/00000000-0000-4000-8000-000000000002/egress' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Replace a project's outbound mode and allowlist

`PUT /v1/clusters/{cluster_id}/projects/{project_id}/egress` (operation ID `update_project_egress`)

Re-applies the network policies of the project's deployed apps. API keys need the write scope; no second-factor check applies to them.

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

**Parameters**

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

**Request body**: [`UpdateEgressRequest`](/api/reference/schemas#updateegressrequest) (required): The whole new setting of a scope.

**Responses**

- `200`: The project's outbound settings now. Body: [`ProjectEgressResponse`](/api/reference/schemas#projectegressresponse).
- `400`: Malformed ids or JSON.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only, or its user is not a member of the project's environment.
- `404`: Cluster or project not found.
- `409`: The project's egress is managed in git.
- `422`: Invalid settings; `details.errors` lists every problem.
- `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 PUT 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/projects/00000000-0000-4000-8000-000000000002/egress' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"example","rules":[]}'
```

## Get a project's quota limits and current usage

`GET /v1/clusters/{cluster_id}/projects/{project_id}/quotas` (operation ID `get_project_quotas`)

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

**Parameters**

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

**Responses**

- `200`: The limits and usage. Body: [`V1ProjectQuotas`](/api/reference/schemas#v1projectquotas).
- `400`: Malformed cluster or project id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's user cannot read this cluster.
- `404`: Cluster or project 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/projects/00000000-0000-4000-8000-000000000002/quotas' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```
