at.happyproto.server.setPrimaryDomain

Make a domain the primary of one of the caller's instances: a verified custom domain that is serving, or the platform subdomain. The instance restarts onto it. Customers only.

Repository @happyproto.at did:plc:mo7vq4jbioxwafy5zkcc3eux namespace authority

Details · procedure

Kind	procedure
Authority	server.happyproto.at
Indexed	12d ago · 2026-10-29

Compare Edit in builder → Fork →

Procedure

procedure · POST

Input

application/json

hostname

requiredstring

The verified custom domain, or the instance's own <slug>.hpy.at.

idempotencyKey

requiredstring

A UUID the client generates once per intended change and resends on every retry of it, so a retry gets the original reply instead of acting twice.

instanceId

requiredstring

The instance's UUID.

Output

application/json

jobId

string

The background job following the switch, when there was one. Absent when the hostname was already the requested primary. Poll it with at.happyproto.server.getJob.

Errors

AuthRequired

This endpoint requires an authenticated caller.

Forbidden

The caller is not a HappyProto customer, or the provisioner refused them.

InvalidRequest

instanceId or idempotencyKey is not a UUID, or hostname is missing or too long.

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

The hostname is not a valid public hostname: no scheme, port, path, wildcard or IP address.

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

The hostname is not a verified domain of this instance: still pending, lapsed, or about to lapse.

CertificateNotReady

The domain's certificate isn't issued yet, or the instance is stopped, so the domain isn't serving over HTTPS.

VersionTooOld

The instance runs a HappyView too old to switch its primary domain safely. Update the instance first.

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.

Similar lexicons

semantic match

Lexicons whose schemas describe something close to this one. Check them before publishing a new one that overlaps.

at.happyproto.server.removeDomain
procedure

Remove a custom domain from one of the caller's instances. HappyProto stops serving it. Customers only.
at.happyproto.server.addDomain
procedure

Add a custom domain to one of the caller's instances. It starts pending, with the DNS records to publish. Customers only.
at.happyproto.server.listDomains
query

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

Check a custom domain's DNS records now, rather than at the next scheduled check. Customers only.
at.happyproto.server.updateInstance
procedure

Move one of the caller's instances to another plan or HappyView release, and start a job that follows the change. Customers only.