# at.happyproto.server.listDomains

> Published by [happyproto.at](https://lexicon.garden/identity/did:plc:mo7vq4jbioxwafy5zkcc3eux)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:mo7vq4jbioxwafy5zkcc3eux/at.happyproto.server.listDomains)
- [Documentation](https://lexicon.garden/lexicon/did:plc:mo7vq4jbioxwafy5zkcc3eux/at.happyproto.server.listDomains/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:mo7vq4jbioxwafy5zkcc3eux/at.happyproto.server.listDomains/examples)

## Definitions

### `at.happyproto.server.listDomains#altRecord`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `string` | Yes | A. |
| `value` | `string` | Yes | The instance host's public IPv4. |

### `at.happyproto.server.listDomains#checks`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `checkedAt` | `string` | Yes | When the check ran. |
| `ownership` | `string` | Yes | Whether the TXT record carries this claim's token. |
| `pointing` | `string` | No | Whether the hostname resolves to the instance's host. Absent when the check didn't get that far, such as when the TXT record was missing. |

### `at.happyproto.server.listDomains#domain`

**Type**: `object`

A custom domain on one of the caller's instances.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `checks` | `ref` → `#checks` | No | The latest DNS check. Absent until the first check has run. |
| `createdAt` | `string` | Yes | When the domain was added. |
| `expiresAt` | `string` | No | When a pending claim expires if it is never verified. Absent once verified. |
| `hostname` | `string` | Yes | The hostname, lowercase, internationalized names in punycode. |
| `id` | `string` | Yes | The domain's UUID. |
| `lapsesAt` | `string` | No | When HappyProto stops serving the domain if its TXT record stays missing. Absent while the record is present. |
| `primary` | `boolean` | Yes | Whether this is the instance's primary domain, the one its PUBLIC_URL follows. |
| `records` | `array` | Yes | The DNS records the customer publishes: the TXT that proves ownership, then the CNAME that points the hostname at the instance. |
| `serving` | `string` | Yes | Whether the domain actually works: off until it is verified, issuing while its certificate is ordered, live once it serves over HTTPS. |
| `state` | `string` | Yes | pending: waiting for the DNS records. verified: proven and served. lapsed: the TXT record went missing, and HappyProto stopped serving it; it recovers if the record comes back before expiresAt. |
| `verifiedAt` | `string` | No | When the domain was first verified. |

### `at.happyproto.server.listDomains`

**Type**: `query`

The domains of one of the caller's instances: its platform subdomain and any custom domain. Customers only.

#### Parameters

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `instanceId` | `string` | Yes | The instance's UUID. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `domains` | `array` | Yes | The custom domains, at most one today. |
| `platform` | `ref` → `#platformDomain` | Yes |  |
| `requestedPrimary` | `string` | No | The hostname the primary is switching to, while a switch is in flight. Absent otherwise. The primary flags keep describing the live primary until the instance has restarted onto it. |

#### Errors

- **AuthRequired**: This endpoint requires an authenticated caller.
- **Forbidden**: The caller is not a HappyProto customer, or the provisioner refused them.
- **InvalidRequest**: instanceId is not a UUID.
- **NotFound**: No such instance or domain, or it is not the caller's. The cases are indistinguishable.
- **NotAvailable**: Custom domains are not switched on yet.
- **InvalidSlug**: Passed through from the provisioner.
- **SlugTaken**: Passed through from the provisioner.
- **NotEntitled**: Passed through from the provisioner.
- **InstanceLimit**: Passed through from the provisioner.
- **NoCapacity**: Passed through from the provisioner.
- **OperationInProgress**: Passed through from the provisioner: the instance is already changing, or a request with this idempotencyKey is still running.
- **InvalidHostname**: Passed through from the provisioner.
- **PlatformHostname**: Passed through from the provisioner.
- **DomainExists**: Passed through from the provisioner.
- **DomainLimit**: Passed through from the provisioner.
- **TooSoon**: Passed through from the provisioner.
- **DomainIsPrimary**: Passed through from the provisioner.
- **NotVerified**: Passed through from the provisioner.
- **CertificateNotReady**: Passed through from the provisioner.
- **VersionTooOld**: Passed through from the provisioner.
- **Upstream**: The provisioner is unreachable, not configured, or answered with an error it does not explain to callers, or the job could not be started.

### `at.happyproto.server.listDomains#platformDomain`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `hostname` | `string` | Yes | The instance's own <slug>.hpy.at hostname, which always serves it. |
| `primary` | `boolean` | Yes | Whether it is the instance's primary domain. |

### `at.happyproto.server.listDomains#record`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `alt` | `ref` → `#altRecord` | No | For an apex name, which cannot hold a CNAME: the A record to publish instead. Absent when the instance's host has no public IPv4. |
| `name` | `string` | Yes | The record's name. |
| `type` | `string` | Yes | TXT or CNAME. |
| `value` | `string` | Yes | The record's value. |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "altRecord": {
      "properties": {
        "type": {
          "description": "A.",
          "type": "string"
        },
        "value": {
          "description": "The instance host's public IPv4.",
          "type": "string"
        }
      },
      "required": [
        "type",
        "value"
      ],
      "type": "object"
    },
    "checks": {
      "properties": {
        "checkedAt": {
          "description": "When the check ran.",
          "type": "string"
        },
        "ownership": {
          "description": "Whether the TXT record carries this claim's token.",
          "knownValues": [
            "ok",
            "missing",
            "error"
          ],
          "type": "string"
        },
        "pointing": {
          "description": "Whether the hostname resolves to the instance's host. Absent when the check didn't get that far, such as when the TXT record was missing.",
          "knownValues": [
            "ok",
            "elsewhere",
            "error"
          ],
          "type": "string"
        }
      },
      "required": [
        "ownership",
        "checkedAt"
      ],
      "type": "object"
    },
    "domain": {
      "description": "A custom domain on one of the caller's instances.",
      "properties": {
        "checks": {
          "description": "The latest DNS check. Absent until the first check has run.",
          "ref": "#checks",
          "type": "ref"
        },
        "createdAt": {
          "description": "When the domain was added.",
          "type": "string"
        },
        "expiresAt": {
          "description": "When a pending claim expires if it is never verified. Absent once verified.",
          "type": "string"
        },
        "hostname": {
          "description": "The hostname, lowercase, internationalized names in punycode.",
          "type": "string"
        },
        "id": {
          "description": "The domain's UUID.",
          "type": "string"
        },
        "lapsesAt": {
          "description": "When HappyProto stops serving the domain if its TXT record stays missing. Absent while the record is present.",
          "type": "string"
        },
        "primary": {
          "description": "Whether this is the instance's primary domain, the one its PUBLIC_URL follows.",
          "type": "boolean"
        },
        "records": {
          "description": "The DNS records the customer publishes: the TXT that proves ownership, then the CNAME that points the hostname at the instance.",
          "items": {
            "ref": "#record",
            "type": "ref"
          },
          "type": "array"
        },
        "serving": {
          "description": "Whether the domain actually works: off until it is verified, issuing while its certificate is ordered, live once it serves over HTTPS.",
          "knownValues": [
            "routing",
            "issuing",
            "live",
            "failed",
            "off"
          ],
          "type": "string"
        },
        "state": {
          "description": "pending: waiting for the DNS records. verified: proven and served. lapsed: the TXT record went missing, and HappyProto stopped serving it; it recovers if the record comes back before expiresAt.",
          "knownValues": [
            "pending",
            "verified",
            "lapsed"
          ],
          "type": "string"
        },
        "verifiedAt": {
          "description": "When the domain was first verified.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "hostname",
        "state",
        "primary",
        "records",
        "serving",
        "createdAt"
      ],
      "type": "object"
    },
    "main": {
      "description": "The domains of one of the caller's instances: its platform subdomain and any custom domain. Customers only.",
      "errors": [
        {
          "description": "This endpoint requires an authenticated caller.",
          "name": "AuthRequired"
        },
        {
          "description": "The caller is not a HappyProto customer, or the provisioner refused them.",
          "name": "Forbidden"
        },
        {
          "description": "instanceId is not a UUID.",
          "name": "InvalidRequest"
        },
        {
          "description": "No such instance or domain, or it is not the caller's. The cases are indistinguishable.",
          "name": "NotFound"
        },
        {
          "description": "Custom domains are not switched on yet.",
          "name": "NotAvailable"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "InvalidSlug"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "SlugTaken"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "NotEntitled"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "InstanceLimit"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "NoCapacity"
        },
        {
          "description": "Passed through from the provisioner: the instance is already changing, or a request with this idempotencyKey is still running.",
          "name": "OperationInProgress"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "InvalidHostname"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "PlatformHostname"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "DomainExists"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "DomainLimit"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "TooSoon"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "DomainIsPrimary"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "NotVerified"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "CertificateNotReady"
        },
        {
          "description": "Passed through from the provisioner.",
          "name": "VersionTooOld"
        },
        {
          "description": "The provisioner is unreachable, not configured, or answered with an error it does not explain to callers, or the job could not be started.",
          "name": "Upstream"
        }
      ],
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "domains": {
              "description": "The custom domains, at most one today.",
              "items": {
                "ref": "#domain",
                "type": "ref"
              },
              "type": "array"
            },
            "platform": {
              "ref": "#platformDomain",
              "type": "ref"
            },
            "requestedPrimary": {
              "description": "The hostname the primary is switching to, while a switch is in flight. Absent otherwise. The primary flags keep describing the live primary until the instance has restarted onto it.",
              "type": "string"
            }
          },
          "required": [
            "platform",
            "domains"
          ],
          "type": "object"
        }
      },
      "parameters": {
        "properties": {
          "instanceId": {
            "description": "The instance's UUID.",
            "type": "string"
          }
        },
        "required": [
          "instanceId"
        ],
        "type": "params"
      },
      "type": "query"
    },
    "platformDomain": {
      "properties": {
        "hostname": {
          "description": "The instance's own <slug>.hpy.at hostname, which always serves it.",
          "type": "string"
        },
        "primary": {
          "description": "Whether it is the instance's primary domain.",
          "type": "boolean"
        }
      },
      "required": [
        "hostname",
        "primary"
      ],
      "type": "object"
    },
    "record": {
      "properties": {
        "alt": {
          "description": "For an apex name, which cannot hold a CNAME: the A record to publish instead. Absent when the instance's host has no public IPv4.",
          "ref": "#altRecord",
          "type": "ref"
        },
        "name": {
          "description": "The record's name.",
          "type": "string"
        },
        "type": {
          "description": "TXT or CNAME.",
          "type": "string"
        },
        "value": {
          "description": "The record's value.",
          "type": "string"
        }
      },
      "required": [
        "type",
        "name",
        "value"
      ],
      "type": "object"
    }
  },
  "id": "at.happyproto.server.listDomains",
  "lexicon": 1
}
```