# Manage a Domain

> The domain operation on whisper.agents: the assess, submit, status and list actions, where the arguments sit in the call, and the errors each returns.

*Source: https://www.whisper.security/docs/control-plane/operations/domain*
*Published: 2026-09-19*
*Last updated: 2026-09-19*

---
`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.

| Argument | Contract |
|---|---|
| `op` | `assess`, `submit`, `status` or `list`. Omit it and the call runs `submit`, which writes. |
| `name` | The name to act on. `zone` is accepted for the same argument. Not needed for `list`. |

## Actions

| Action | Does |
|---|---|
| `assess` | Reports whether the name can be attached, before you change anything at the registrar. |
| `submit` | Records the intent and returns the delegation and signing records to publish. |
| `status` | Reports what the plane currently observes for the name, and what is still missing. |
| `list` | Returns 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](/docs/identity/own-domain) walks the registrar side and the check that closes it.

## Errors

| Code | Status | Meaning |
|---|---|---|
| `BAD_ARGS` | 400 | The 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_REGISTRABLE` | 400 | The name cannot be attached as given. |
| `FORBIDDEN_SCOPE` | 403 | The key does not carry `admin:dns`. |
| `DOMAIN_TAKEN`, `DOMAIN_OVERLAPS_ANOTHER_ACCOUNT` | 409 | The name, or a name above it, is held elsewhere. |
| `DOMAIN_IN_BAILIWICK` | 409 | The name sits inside a zone the plane already serves. |
| `DOMAIN_UNDER_HELD_APEX` | 409 | The apex above the name is on hold. |
| `DOMAIN_LIMIT`, `BYOD_CAPACITY` | `429` | The account cannot take another name right now. Ask Whisper. |