Skip to content
Control Plane API
Skip navigation

Manage a Domain

Attach a name you already own, read what the plane observes about it, and list the ones attached.

Published

On this page (4)

Manage a Domain Documentation

domain attaches a name you own to the account, so new addresses are minted under that name instead of the shared one. It needs admin:dns.

Where the arguments sit

domain carries a second operation of its own, and it goes inside args under the same key the envelope uses outside it.

whisper-call
CALL whisper.agents({op: 'domain', args: {op: 'status', name: 'example.com'}})

The nesting is required, not stylistic: one map cannot hold the key op twice, so a call that puts both at the top level loses the inner one.

ArgumentContract
opassess, submit, status or list. Omit it and the call runs submit, which writes.
nameThe name to act on. zone is accepted for the same argument. Not needed for list.

Actions

ActionDoes
assessReports whether the name can be attached, before you change anything at the registrar.
submitRecords the intent and returns the delegation and signing records to publish.
statusReports what the plane currently observes for the name, and what is still missing.
listReturns the names attached to the account.

Returns

Columns kind and value, one row per fact. Rows carry the state of the attachment, the name it applies to, each record to publish, the certificate-authority lines that go with it, and any note about what to do next.

Publishing those records at your registrar is the whole authorization: there is no token to paste and no file to host. Bring your own domain walks the registrar side and the check that closes it.

Errors

CodeStatusMeaning
BAD_ARGS400The inner op is not one of the four values, or name is missing where it is needed. The message names the argument it wanted.
DOMAIN_NOT_REGISTRABLE400The name cannot be attached as given.
FORBIDDEN_SCOPE403The key does not carry admin:dns.
DOMAIN_TAKEN, DOMAIN_OVERLAPS_ANOTHER_ACCOUNT409The name, or a name above it, is held elsewhere.
DOMAIN_IN_BAILIWICK409The name sits inside a zone the plane already serves.
DOMAIN_UNDER_HELD_APEX409The apex above the name is on hold.
DOMAIN_LIMIT, BYOD_CAPACITY429The account cannot take another name right now. Ask Whisper.