at.happyproto.server.listDomains

happyproto.at

Documentation

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

main query

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

Parameters

instanceId string Required

The instance's UUID.

Output

Encodingapplication/json

domains array Required

The custom domains, at most one today.

platform ref#platformDomain Required

No description available.

requestedPrimary string Optional

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.

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://api.bsky.social)

Parameters

instanceId * The instance's UUID.

View raw schema

{
  "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"
}

altRecord object

No description available.

Properties

type string Required

value string Required

The instance host's public IPv4.

View raw schema

{
  "properties": {
    "type": {
      "description": "A.",
      "type": "string"
    },
    "value": {
      "description": "The instance host's public IPv4.",
      "type": "string"
    }
  },
  "required": [
    "type",
    "value"
  ],
  "type": "object"
}

checks object

No description available.

Properties

checkedAt string Required

When the check ran.

ownership string Required

Whether the TXT record carries this claim's token.

Known values: ok, missing, error

pointing string Optional

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.

Known values: ok, elsewhere, error

View raw schema

{
  "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 object

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

Properties

checks ref #checks Optional

The latest DNS check. Absent until the first check has run.

createdAt string Required

When the domain was added.

expiresAt string Optional

When a pending claim expires if it is never verified. Absent once verified.

hostname string Required

The hostname, lowercase, internationalized names in punycode.

id string Required

The domain's UUID.

lapsesAt string Optional

When HappyProto stops serving the domain if its TXT record stays missing. Absent while the record is present.

primary boolean Required

Whether this is the instance's primary domain, the one its PUBLIC_URL follows.

records array of ref#record Required

The DNS records the customer publishes: the TXT that proves ownership, then the CNAME that points the hostname at the instance.

serving string Required

Whether the domain actually works: off until it is verified, issuing while its certificate is ordered, live once it serves over HTTPS.

Known values: routing, issuing, live, failed, off

state string Required

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.

Known values: pending, verified, lapsed

verifiedAt string Optional

When the domain was first verified.

View raw schema

{
  "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"
}

platformDomain object

No description available.

Properties

hostname string Required

The instance's own <slug>.hpy.at hostname, which always serves it.

primary boolean Required

Whether it is the instance's primary domain.

View raw schema

{
  "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 object

No description available.

Properties

alt ref #altRecord Optional

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 Required

The record's name.

type string Required

TXT or CNAME.

value string Required

The record's value.

View raw schema

{
  "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"
}