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

# Domains

> The domains operations of the v1 API.

## List an app's domains

`GET /v1/clusters/{cluster_id}/apps/{app_id}/domains` (operation ID `list_domains`)

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
- `app_id` (path, required, `string`): The app UUID

**Responses**

- `200`: A page of domains. Body: [`V1Page_for_V1AppDomain`](/api/reference/schemas#v1page_for_v1appdomain).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read this cluster.
- `404`: App 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/apps/00000000-0000-4000-8000-000000000002/domains' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Add a domain to an app

`POST /v1/clusters/{cluster_id}/apps/{app_id}/domains` (operation ID `add_domain`)

An organization domain must cover the host (or one being verified, with `pending_verification`).

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

**Parameters**

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

**Request body**: [`V1AddDomain`](/api/reference/schemas#v1adddomain) (required): A domain to add to an app.

**Responses**

- `201`: The domain was added. Body: [`V1AppDomain`](/api/reference/schemas#v1appdomain).
- `400`: Invalid input.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope.
- `404`: App not found.
- `409`: Another route in the cluster has the same host, port and path.
- `422`: Invalid host, ports, path or protocol or not covered by a verified domain (`details` names the field), malformed body or unknown field.
- `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/apps/00000000-0000-4000-8000-000000000002/domains' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example","port":1}'
```

## Get one app domain, with the DNS records it needs

`GET /v1/clusters/{cluster_id}/apps/{app_id}/domains/{domain_id}` (operation ID `get_domain`)

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

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The app UUID
- `domain_id` (path, required, `string`): The domain UUID

**Responses**

- `200`: The domain. Body: [`V1AppDomain`](/api/reference/schemas#v1appdomain).
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read this cluster.
- `404`: App or domain 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/apps/00000000-0000-4000-8000-000000000002/domains/00000000-0000-4000-8000-000000000003' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Change an app domain

`PATCH /v1/clusters/{cluster_id}/apps/{app_id}/domains/{domain_id}` (operation ID `update_domain`)

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

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The app UUID
- `domain_id` (path, required, `string`): The domain UUID

**Request body**: [`V1UpdateDomain`](/api/reference/schemas#v1updatedomain) (required): The fields to change; a field left out keeps its value.

**Responses**

- `200`: The changed domain. Body: [`V1AppDomain`](/api/reference/schemas#v1appdomain).
- `400`: Invalid input.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope.
- `404`: App or domain not found.
- `409`: The domain is a temporary URL, or the field is managed in git.
- `422`: Behind a proxy on a route that is not HTTP or HTTPS (`details` names the field), malformed body or unknown field.
- `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/apps/00000000-0000-4000-8000-000000000002/domains/00000000-0000-4000-8000-000000000003' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"behind_proxy":false}'
```

## Remove a domain from an app

`DELETE /v1/clusters/{cluster_id}/apps/{app_id}/domains/{domain_id}` (operation ID `remove_domain`)

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

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The app UUID
- `domain_id` (path, required, `string`): The domain UUID

**Responses**

- `204`: The domain was removed.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope, or the domain is a read-only platform host.
- `404`: App or domain 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/apps/00000000-0000-4000-8000-000000000002/domains/00000000-0000-4000-8000-000000000003' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Set the header a domain's proxy puts the client IP in

`PUT /v1/clusters/{cluster_id}/apps/{app_id}/domains/{domain_id}/client-ip-header` (operation ID `set_client_ip_header`)

Set the header a domain's proxy puts the client IP in; passed to the app only while the origin lock is on.

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

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The app UUID
- `domain_id` (path, required, `string`): The domain UUID

**Request body**: [`V1SetClientIpHeader`](/api/reference/schemas#v1setclientipheader) (required): The client-IP header of a domain behind a proxy.

**Responses**

- `200`: The domain with its client IP header. Body: [`V1AppDomain`](/api/reference/schemas#v1appdomain).
- `400`: An invalid header name, or a domain not behind a CDN or proxy.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope.
- `404`: App or domain 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 PUT 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/apps/00000000-0000-4000-8000-000000000002/domains/00000000-0000-4000-8000-000000000003/client-ip-header' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"header":"example"}'
```

## Turn on a domain's origin lock

`POST /v1/clusters/{cluster_id}/apps/{app_id}/domains/{domain_id}/origin-lock` (operation ID `enable_origin_lock`)

Requests without the key in `X-Aline-Origin-Key` are refused with 403, and the proxy's client-IP header reaches the app only while locked. The key is answered this once.

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

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The app UUID
- `domain_id` (path, required, `string`): The domain UUID

**Responses**

- `200`: The new key, shown once, and the domain. Body: [`V1OriginKey`](/api/reference/schemas#v1originkey).
- `400`: The domain is not behind a CDN or proxy.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope.
- `404`: App or domain not found.
- `409`: The lock is on already.
- `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/apps/00000000-0000-4000-8000-000000000002/domains/00000000-0000-4000-8000-000000000003/origin-lock' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Turn off a domain's origin lock

`DELETE /v1/clusters/{cluster_id}/apps/{app_id}/domains/{domain_id}/origin-lock` (operation ID `disable_origin_lock`)

Turn off a domain's origin lock; every key stops working.

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

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The app UUID
- `domain_id` (path, required, `string`): The domain UUID

**Responses**

- `200`: The domain, unlocked. Body: [`V1AppDomain`](/api/reference/schemas#v1appdomain).
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope.
- `404`: App or domain 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/apps/00000000-0000-4000-8000-000000000002/domains/00000000-0000-4000-8000-000000000003/origin-lock' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Rotate a domain's origin key

`POST /v1/clusters/{cluster_id}/apps/{app_id}/domains/{domain_id}/origin-lock/rotate` (operation ID `rotate_origin_lock`)

The new key is answered this once; the previous one keeps working for 24 hours.

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

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `app_id` (path, required, `string`): The app UUID
- `domain_id` (path, required, `string`): The domain UUID

**Responses**

- `200`: The new key, shown once, and the domain. Body: [`V1OriginKey`](/api/reference/schemas#v1originkey).
- `400`: The lock is off, or the domain is not behind a CDN or proxy.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope.
- `404`: App or domain 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 POST 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/apps/00000000-0000-4000-8000-000000000002/domains/00000000-0000-4000-8000-000000000003/origin-lock/rotate' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## List the organization's domains

`GET /v1/domains` (operation ID `list_org_domains`)

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 domains. Body: [`V1Page_for_V1OrgDomain`](/api/reference/schemas#v1page_for_v1orgdomain).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read the organization.
- `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/domains' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Get one organization domain and its verification state

`GET /v1/domains/{domain_id}` (operation ID `get_org_domain`)

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

**Parameters**

- `domain_id` (path, required, `string`): The domain UUID

**Responses**

- `200`: The domain. Body: [`V1OrgDomain`](/api/reference/schemas#v1orgdomain).
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read the organization.
- `404`: Domain 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/domains/00000000-0000-4000-8000-000000000001' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## List the organization's hosted zones

`GET /v1/hosted-zones` (operation ID `list_zones`)

Ordered by creation time, oldest first. Cursor paginated. Empty on an installation without hosted DNS.

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 zones. Body: [`V1Page_for_V1HostedZone`](/api/reference/schemas#v1page_for_v1hostedzone).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read the organization.
- `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).
- `502`: The DNS service failed.

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

## Get one hosted zone

`GET /v1/hosted-zones/{zone_id}` (operation ID `get_zone`)

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

**Parameters**

- `zone_id` (path, required, `string`): The zone UUID

**Responses**

- `200`: The zone. Body: [`V1HostedZone`](/api/reference/schemas#v1hostedzone).
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read the organization.
- `404`: Hosted zone 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).
- `502`: The DNS service failed.

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

## List the record sets of a verified hosted zone

`GET /v1/hosted-zones/{zone_id}/records` (operation ID `list_records`)

Ordered by name, then type. 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).
- `zone_id` (path, required, `string`): The zone UUID

**Responses**

- `200`: A page of record sets. Body: [`V1Page_for_V1RecordSet`](/api/reference/schemas#v1page_for_v1recordset).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `403`: The key cannot read the organization.
- `404`: Hosted zone not found.
- `409`: The zone is not verified yet.
- `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).
- `502`: The DNS service failed.

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

## Create or replace one record set of a verified hosted zone

`PUT /v1/hosted-zones/{zone_id}/records` (operation ID `put_record`)

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

**Parameters**

- `zone_id` (path, required, `string`): The zone UUID

**Request body**: [`V1RecordSet`](/api/reference/schemas#v1recordset) (required): A record set: every record of one name and type.

**Responses**

- `200`: The record set was written. Body: [`V1ZoneSerial`](/api/reference/schemas#v1zoneserial).
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope, or its owner is not an organization admin.
- `404`: Hosted zone not found.
- `409`: The zone is not verified yet, or the set conflicts with another (a CNAME beside other records).
- `422`: Invalid record set, malformed body or unknown field.
- `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).
- `502`: The DNS service failed.

```bash
curl -X PUT 'https://api.a-line.cloud/v1/hosted-zones/00000000-0000-4000-8000-000000000001/records' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"name":"example","records":[],"ttl":1,"type":"example"}'
```

## Delete one record set of a verified hosted zone

`DELETE /v1/hosted-zones/{zone_id}/records` (operation ID `delete_record`)

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

**Parameters**

- `name` (query, required, `string`): The owner name.
- `type` (query, required, `string`): The record type.
- `zone_id` (path, required, `string`): The zone UUID

**Responses**

- `204`: The record set was deleted.
- `400`: `name` or `type` missing.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks write scope, or its owner is not an organization admin.
- `404`: Hosted zone or record set not found.
- `409`: The zone is not verified yet.
- `422`: The record set cannot be deleted.
- `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).
- `502`: The DNS service failed.

```bash
curl -X DELETE 'https://api.a-line.cloud/v1/hosted-zones/00000000-0000-4000-8000-000000000001/records?name=example&type=example' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```
