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

# IaC

> The IaC operations of the v1 API.

## List the organization's infra links, oldest first

`GET /v1/iac/infra-links` (operation ID `list_infra_links`)

List the organization's infra links, oldest first; with `path`, only the ones reading exactly that repository directory.

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).
- `path` (query, `string`): Only the links reading exactly this repository directory (one trailing slash ignored).

**Responses**

- `200`: The links. Body: [`V1Page_for_V1IacLink`](/api/reference/schemas#v1page_for_v1iaclink).
- `400`: Invalid path, limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `422`: Unknown query parameter.
- `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/iac/infra-links' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Plan an infra link's clusters/\*.yaml at a commit

`POST /v1/iac/infra-links/{link_id}/plan` (operation ID `plan_infra_link`)

Plan an infra link's `clusters/*.yaml` at a commit: the changes a sync of that commit would make, computed as the sync computes them, without applying or holding anything.

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

**Parameters**

- `link_id` (path, required, `string`): The infra link UUID

**Request body**: [`V1IacCommit`](/api/reference/schemas#v1iaccommit) (required): The commit a plan or sync is for.

**Responses**

- `200`: The plan. Body: [`V1IacPlan`](/api/reference/schemas#v1iacplan).
- `400`: Malformed id, JSON or commit id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only.
- `404`: Link not found.
- `422`: The commit cannot be applied (invalid files, or not descending from the applied commit).
- `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 repository or the planner is unavailable.
- `504`: Planning timed out.

```bash
curl -X POST 'https://api.a-line.cloud/v1/iac/infra-links/00000000-0000-4000-8000-000000000001/plan' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"sha":"example"}'
```

## Report an infra link's sync state at a commit

`GET /v1/iac/infra-links/{link_id}/status` (operation ID `infra_link_status`)

Report an infra link's sync state at a commit (default: the commit synced last), and every change still held for confirmation.

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

**Parameters**

- `sha` (query, `string`): The commit to report on. Default: the commit synced last.
- `link_id` (path, required, `string`): The infra link UUID

**Responses**

- `200`: The link's state. Body: [`V1IacStatus`](/api/reference/schemas#v1iacstatus).
- `400`: Malformed id or commit id.
- `401`: Missing, invalid or revoked API key.
- `404`: Link not found.
- `422`: Unknown query parameter.
- `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/iac/infra-links/00000000-0000-4000-8000-000000000001/status' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Sync an infra link to a commit

`POST /v1/iac/infra-links/{link_id}/sync` (operation ID `sync_infra_link`)

Sync an infra link to a commit: applies `clusters/*.yaml` exactly as of that commit (never the branch tip), holding changes that need confirmation. Poll `status_url` for the outcome.

The commit must be on the linked branch and descend from the commit the link applied last, or the sync fails.

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

**Parameters**

- `link_id` (path, required, `string`): The infra link UUID

**Request body**: [`V1IacCommit`](/api/reference/schemas#v1iaccommit) (required): The commit a plan or sync is for.

**Responses**

- `202`: The sync is queued. Body: [`V1IacSyncQueued`](/api/reference/schemas#v1iacsyncqueued).
- `400`: Malformed id, JSON or commit id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only, or its user is not a team admin.
- `404`: Link not found.
- `409`: The link is broken (its repository is gone or unreadable).
- `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/iac/infra-links/00000000-0000-4000-8000-000000000001/sync' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"sha":"example"}'
```

## List the organization's project links the key may read, oldest first

`GET /v1/iac/project-links` (operation ID `list_project_links`)

List the organization's project links the key may read, oldest first; with `path`, only the ones reading exactly that repository directory.

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).
- `path` (query, `string`): Only the links reading exactly this repository directory (one trailing slash ignored).

**Responses**

- `200`: The links. Body: [`V1Page_for_V1IacLink`](/api/reference/schemas#v1page_for_v1iaclink).
- `400`: Invalid path, limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `422`: Unknown query parameter.
- `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/iac/project-links' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Plan a project link's project.yaml and apps/ at a commit

`POST /v1/iac/project-links/{link_id}/plan` (operation ID `plan_project_link`)

Plan a project link's `project.yaml` and `apps/` at a commit: the changes a sync of that commit would make, computed as the sync computes them, without applying anything.

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

**Parameters**

- `link_id` (path, required, `string`): The project link UUID

**Request body**: [`V1IacCommit`](/api/reference/schemas#v1iaccommit) (required): The commit a plan or sync is for.

**Responses**

- `200`: The plan. Body: [`V1IacPlan`](/api/reference/schemas#v1iacplan).
- `400`: Malformed id, JSON or commit id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only.
- `404`: Link not found.
- `422`: The commit cannot be applied (invalid files, or not descending from the applied commit).
- `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 repository or the planner is unavailable.
- `504`: Planning timed out.

```bash
curl -X POST 'https://api.a-line.cloud/v1/iac/project-links/00000000-0000-4000-8000-000000000001/plan' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"sha":"example"}'
```

## Report a project link's sync state at a commit

`GET /v1/iac/project-links/{link_id}/status` (operation ID `project_link_status`)

Report a project link's sync state at a commit (default: the commit synced last), and every change still held for confirmation.

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

**Parameters**

- `sha` (query, `string`): The commit to report on. Default: the commit synced last.
- `link_id` (path, required, `string`): The project link UUID

**Responses**

- `200`: The link's state. Body: [`V1IacStatus`](/api/reference/schemas#v1iacstatus).
- `400`: Malformed id or commit id.
- `401`: Missing, invalid or revoked API key.
- `404`: Link not found.
- `422`: Unknown query parameter.
- `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/iac/project-links/00000000-0000-4000-8000-000000000001/status' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Sync a project link to a commit

`POST /v1/iac/project-links/{link_id}/sync` (operation ID `sync_project_link`)

Sync a project link to a commit: applies `project.yaml` and `apps/` exactly as of that commit (never the branch tip). Poll `status_url` for the outcome.

The commit must be on the linked branch and descend from the commit the link applied last, or the sync fails.

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

**Parameters**

- `link_id` (path, required, `string`): The project link UUID

**Request body**: [`V1IacCommit`](/api/reference/schemas#v1iaccommit) (required): The commit a plan or sync is for.

**Responses**

- `202`: The sync is queued. Body: [`V1IacSyncQueued`](/api/reference/schemas#v1iacsyncqueued).
- `400`: Malformed id, JSON or commit id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is read-only, or its user cannot deploy to the environment.
- `404`: Link not found.
- `409`: The link is broken (its repository is gone or unreadable).
- `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/iac/project-links/00000000-0000-4000-8000-000000000001/sync' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"sha":"example"}'
```
