# Set DNS records of a name

> Set the records of one name and type in the DNS zone of a domain - replacing what is there.

- Effect: Write - Changes the account. Agents ask first.
- Idempotent: yes
- Stability: stable
- MCP tool: `manitu_domain_dns_zone_record_set` on https://mcp.manitu.de/mcp
- REST: `POST https://api.manitu.de/v1/domain/dns/zone/record/set`
- Needs: `service_domain`
- Counts against: [writes](/rate-limits/#limit-writes) (60 per hour per account)
- Page: /reference/domain/dns/zone/record/set/

## MCP tool

`manitu_domain_dns_zone_record_set`

**Changes the account. Agents say what will happen and wait for an explicit yes before calling it.**

### Description for the model

Sets the records of one name and type in the DNS zone of a domain at manitu - the values given replace all records of that name and type ("point home at 203.0.113.7", "the MX of the domain are ..."). host is relative to the domain ("@" the domain itself, "www", "*.dev"); a value as in a zone file, a TXT the text itself; a name in a value without a final dot is relative to the domain. The same call again changes nothing (changed false). To add one more value use [`manitu_domain_dns_zone_record_add`](/reference/domain/dns/zone/record/add.md), to remove [`manitu_domain_dns_zone_record_delete`](/reference/domain/dns/zone/record/delete.md); for many changes at once [`manitu_domain_dns_zone_set`](/reference/domain/dns/zone/set.md). Tell the user the name, type and values first and wait for an explicit yes - web site and e-mail of the domain depend on the zone. The NS records of the domain itself are manitu's (apex_ns_not_allowed); NS of a subdomain delegate it, never at a wildcard (wildcard_ns_not_allowed); a CNAME stands alone (cname_not_alone) and never at the domain itself (cname_at_apex). A value that cannot be right is refused with its reason (ipv4_address_invalid, target_hostname_invalid ...), a subdomain delegated to manitu's own name servers with ns_target_is_provider; hints come as warnings (record_duplicate, an address not of the account or not on the internet ...). Refused with a conflict when manitu does not hold the zone (zone_not_hosted_here), the domain is not active (zone_not_editable) or the zone changed since zone_revision (zone_changed). Every change counts the serial up and answers the new zone_revision - pass that one with the next change. A new serial after your own change is expected, not a change by someone else.

Reasons it may answer: resource_not_found, permission_missing, zone_not_hosted_here, zone_not_editable, zone_changed and 21 more. Warnings it may answer: invalid_record_kept, ipv4_address_not_global, ipv6_address_not_global, mx_missing, mx_target_without_address, record_duplicate and 3 more.

### Arguments

- `name` (string, required) - The domain name, with international characters or in ASCII. (minLength `1`; maxLength `253`; pattern `"^[^\\x00-,./:-@[-`{-\\x7F]+(?:\\.[^\\x00-,./:-@[-`{-\\x7F]+)+$"`)
- `host` (string, required) - The name of the record, relative to the domain: "@" for the domain itself, "www" for www.<domain>, "*.dev" for a wildcard - with international characters or in ASCII. (minLength `1`; maxLength `253`; pattern `"^[^\\x00-\\x1F\\x7F]*$"`)
- `type` (string, required) - The record type. (one of `"A"`, `"AAAA"`, `"CAA"`, `"CNAME"`, `"MX"`, `"NS"`, `"SRV"`, `"TXT"`)
- `zone_revision` (string) - Optional: zone_revision from [`manitu_domain_dns_zone_get`](/reference/domain/dns/zone/get.md) or from the answer to the last change - refused with zone_changed if the zone changed since. A new zone_revision after your own change is expected, not a change by someone else. (pattern `"^[0-9a-f]{64}$"`)
- `value_list` (array of string, required) - The values - all of them: what is not listed is removed. A CNAME has exactly one. (minItems `1`; maxItems `50`)
- `ttl` (integer) - How long resolvers may keep it, in seconds. Left out: the zone's default. (minimum `60`; maximum `604800`)
- `approval_token` (string, write-only) - The token of the way call_again from the approval_required answer of the same call - only after the user said yes to everything in its elements. Valid 15 minutes, once. (minLength `1`; maxLength `255`)

### Example

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "manitu_domain_dns_zone_record_set",
    "arguments": {
      "name": "example.com",
      "host": "string",
      "type": "A",
      "value_list": [
        "string"
      ]
    }
  }
}
```

## REST

`POST https://api.manitu.de/v1/domain/dns/zone/record/set`

**This request changes something.**

### Description

Sets the records of one name and type in the DNS zone of a domain at manitu: the values given replace all records of that name and type. host is relative to the domain ("@" the domain itself, "www", "*.dev"); a value is written as in a zone file, a TXT as the text itself, and a name in a value without a final dot is relative to the domain. The same call again changes nothing (changed false). One more value is [`POST /v1/domain/dns/zone/record/add`](/reference/domain/dns/zone/record/add.md), removing [`POST /v1/domain/dns/zone/record/delete`](/reference/domain/dns/zone/record/delete.md), many changes at once [`POST /v1/domain/dns/zone/set`](/reference/domain/dns/zone/set.md). The NS records of the domain itself are manitu's (apex_ns_not_allowed); NS of a subdomain delegate it, never at a wildcard (wildcard_ns_not_allowed); a CNAME stands alone (cname_not_alone), with one value only (cname_single_value), and never at the domain itself (cname_at_apex). A value that cannot be right is refused with its reason (ipv4_address_invalid, target_hostname_invalid ...), a subdomain delegated to manitu's own name servers with ns_target_is_provider; warnings point at likely mistakes (record_duplicate, an address not of the account or not on the internet ...). Refused with a conflict when manitu does not hold the zone (zone_not_hosted_here), the domain is not active (zone_not_editable) or the zone changed since zone_revision (zone_changed). Every change counts the serial up and answers the new zone_revision, the base of the next change. Made with a session of the customer panel, the call is carried out at once; otherwise the caller confirms it first: approval_required with the way call_again, then the same call again with its approval_token - unless the access is set to make such changes without asking. For a record of type MX, NS, SRV or CAA, at a wildcard, or at the host _acme-challenge, autodiscover or autoconfig (and below), it waits instead until a person signed in to the customer panel approves it (approval_required; its state: [`POST /v1/approval/get`](/reference/approval/get.md)).

### Authentication

One of `X-API-Key`, `Authorization: Bearer …` - never more than one in a request.

### Request body

JSON; unknown fields are refused.

- `name` (string, required) - The domain name, with international characters or in ASCII. (minLength `1`; maxLength `253`; pattern `"^[^\\x00-,./:-@[-`{-\\x7F]+(?:\\.[^\\x00-,./:-@[-`{-\\x7F]+)+$"`)
- `host` (string, required) - The name of the record, relative to the domain: "@" for the domain itself, "www" for www.<domain>, "*.dev" for a wildcard - with international characters or in ASCII. (minLength `1`; maxLength `253`; pattern `"^[^\\x00-\\x1F\\x7F]*$"`)
- `type` (string, required) - The record type. (one of `"A"`, `"AAAA"`, `"CAA"`, `"CNAME"`, `"MX"`, `"NS"`, `"SRV"`, `"TXT"`)
- `zone_revision` (string) - Optional: zone_revision from [`POST /v1/domain/dns/zone/get`](/reference/domain/dns/zone/get.md) or from the answer to the last change - refused with zone_changed if the zone changed since. (pattern `"^[0-9a-f]{64}$"`)
- `value_list` (array of string, required) - The values - all of them: what is not listed is removed. A CNAME has exactly one. (minItems `1`; maxItems `50`)
- `ttl` (integer) - How long resolvers may keep it, in seconds. Left out: the zone's default. (minimum `60`; maximum `604800`)
- `approval_token` (string, write-only) - The token of the way call_again from the approval_required answer of the same call - only after the user said yes to everything in its elements. Valid 15 minutes, once. (minLength `1`; maxLength `255`)

### Response

In `data`; the rest of the body as on every call.

- `name` (string, required) - The domain, with international characters. (maxLength `253`; pattern `"^[^\\x00-,./:-@[-`{-\\x7F]+(?:\\.[^\\x00-,./:-@[-`{-\\x7F]+)+$"`)
- `host` (string, required) - The name of the record, relative to the domain, in ASCII; "@" for the domain itself. (pattern `"^[^\\x00-\\x1F\\x7F]*$"`)
- `type` (string, required) - (one of `"A"`, `"AAAA"`, `"CAA"`, `"CNAME"`, `"MX"`, `"NS"`, `"SRV"`, `"TXT"`)
- `changed` (boolean, required) - false: it was so already - nothing was stored.
- `ttl` (integer | null, required) - The TTL of the records now, in seconds; null: the zone's default.
- `value_list` (array of string, required) - The values of this host and type now, as stored - empty when there are none left.
- `zone_revision` (string, required) - The revision of the zone now. (pattern `"^[^\\x00-\\x1F\\x7F]*$"`)

### Statuses

- `200` Success.
- `400` The input is wrong, or the request itself (INVALID_INPUT). Each entry names its field and its reason - correct the input and call again.
- `401` No credential was presented, or it was not recognised (UNAUTHENTICATED).
- `403` The credential is valid, but may not do this (PERMISSION_DENIED). The reason says why - another credential is the way, not a repeat.
- `404` What the call names does not exist, or not for this caller (NOT_FOUND). Look it up again - do not guess another.
- `409` Not possible in the current state (PRECONDITION_FAILED). The reason says what stands in the way; the same call may succeed once it has changed.
- `429` Too many calls. The Retry-After header says when to try again.
- `500` The server failed. Nothing about the request was wrong. Whether a change took effect is not known - check before trying it again.
- `503` The channel this operation forwards through is unavailable.

### Example

```sh
curl -X POST \
  'https://api.manitu.de/v1/domain/dns/zone/record/set' \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example.com","host":"string","type":"A","value_list":["string"]}'
```

## Example result

```json
{
  "name": "example.com",
  "host": "string",
  "type": "A",
  "changed": true,
  "ttl": 1,
  "value_list": [
    "string"
  ],
  "zone_revision": "string"
}
```

## Errors

Reasons it is known to fail with - any other may come too; act on the class.

- [`resource_not_found`](/errors/resource_not_found.md) (`NOT_FOUND`) - What the call names does not exist in the account, or not for this access.
- [`permission_missing`](/errors/permission_missing.md) (`PERMISSION_DENIED`) - This access lacks a permission the call needs; the main access of the account can grant it.
- [`zone_not_hosted_here`](/errors/zone_not_hosted_here.md) (`PRECONDITION_FAILED`) - The zone of the domain is not a primary zone held here - its name servers are elsewhere.
- [`zone_not_editable`](/errors/zone_not_editable.md) (`PRECONDITION_FAILED`) - The domain is not active, so its zone cannot be changed.
- [`zone_changed`](/errors/zone_changed.md) (`PRECONDITION_FAILED`) - The zone changed since it was read: read it again and apply the change again.
- [`zone_stored_not_readable`](/errors/zone_stored_not_readable.md) (`PRECONDITION_FAILED`) - The zone as stored cannot be read; the provider has to repair it.
- [`zone_not_loadable`](/errors/zone_not_loadable.md) (`INVALID_INPUT`) - The name server would not load the zone; the old zone stays.
- [`cname_not_alone`](/errors/cname_not_alone.md) (`INVALID_INPUT`) - A CNAME stands alone at its name - no other record beside it.
- [`wildcard_ns_not_allowed`](/errors/wildcard_ns_not_allowed.md) (`INVALID_INPUT`) - NS records delegate one name, never a wildcard.
- [`caa_invalid`](/errors/caa_invalid.md) (`INVALID_INPUT`) - A CAA record is not flags, a tag and a value.
- [`ipv4_address_invalid`](/errors/ipv4_address_invalid.md) (`INVALID_INPUT`) - An A record holds no IPv4 address.
- [`ipv6_address_invalid`](/errors/ipv6_address_invalid.md) (`INVALID_INPUT`) - An AAAA record holds no IPv6 address.
- [`port_out_of_range`](/errors/port_out_of_range.md) (`INVALID_INPUT`) - A port is outside 0 to 65535.
- [`priority_out_of_range`](/errors/priority_out_of_range.md) (`INVALID_INPUT`) - A priority is outside 0 to 65535.
- [`svcb_params_invalid`](/errors/svcb_params_invalid.md) (`INVALID_INPUT`) - The parameters of an HTTPS or SVCB record are not valid.
- [`target_hostname_invalid`](/errors/target_hostname_invalid.md) (`INVALID_INPUT`) - A target is no host name - no URL, no port, no path.
- [`tlsa_invalid`](/errors/tlsa_invalid.md) (`INVALID_INPUT`) - A TLSA record is not usage, selector, matching type and a digest of the right length.
- [`type_unknown`](/errors/type_unknown.md) (`INVALID_INPUT`) - A record type no zone can hold.
- [`value_invalid`](/errors/value_invalid.md) (`INVALID_INPUT`) - The value is not one of the type.
- [`weight_out_of_range`](/errors/weight_out_of_range.md) (`INVALID_INPUT`) - A weight is outside 0 to 65535.
- [`ns_target_is_provider`](/errors/ns_target_is_provider.md) (`INVALID_INPUT`) - A subdomain delegated to manitu's own name servers, which hold the zone already.
- [`apex_ns_not_allowed`](/errors/apex_ns_not_allowed.md) (`INVALID_INPUT`) - The NS records of the domain itself are the provider's - neither added nor removed.
- [`cname_at_apex`](/errors/cname_at_apex.md) (`INVALID_INPUT`) - A CNAME cannot stand at the domain itself, beside its SOA and NS.
- [`host_invalid`](/errors/host_invalid.md) (`INVALID_INPUT`) - The host is no DNS name.
- [`name_needs_final_dot`](/errors/name_needs_final_dot.md) (`INVALID_INPUT`) - A name written with the domain at its end needs a final dot - or none of the domain.
- [`cname_single_value`](/errors/cname_single_value.md) (`INVALID_INPUT`) - A CNAME has one value.

## Warnings

They never block the call.

- [`invalid_record_kept`](/errors/invalid_record_kept.md) - A record is not valid (code), but stored so already - kept, not refused. Tell the user; it should be repaired or removed.
- [`ipv4_address_not_global`](/errors/ipv4_address_not_global.md) - An IPv4 address that is not reachable on the internet (private, loopback ...).
- [`ipv6_address_not_global`](/errors/ipv6_address_not_global.md) - An IPv6 address that is not reachable on the internet (link-local, unique local ...).
- [`mx_missing`](/errors/mx_missing.md) - No MX record - no mail for the domain is taken.
- [`mx_target_without_address`](/errors/mx_target_without_address.md) - An MX target within the zone has no A, AAAA or CNAME record.
- [`record_duplicate`](/errors/record_duplicate.md) - A record is there twice.
- [`ipv4_address_not_in_account`](/errors/ipv4_address_not_in_account.md) - An IPv4 address that is not one of the account's.
- [`ipv6_address_not_in_account`](/errors/ipv6_address_not_in_account.md) - An IPv6 address that is not one of the account's.
- [`mx_target_is_mail_client_host`](/errors/mx_target_is_mail_client_host.md) - An MX record names the host for mail programs, which takes no mail from other servers - suggested_target does.
