# apply_dns_records

Source: https://modulify.ai/docs/api/bought-domains/apply-dns-records

Saves a set of DNS records to a domain the workspace bought in one call, replacing the records the set asks to replace.

- Title: Save a set of DNS records to a bought domain
- Scope: `domains:write`
- Access: Destructive
- Endpoint: `POST /v1/apply_dns_records`

The records the set replaces are deleted, then the new ones are added. The set follows the rules of `preview_dns_records`, so call that with the same records first: a record is only ever added unless it was sent with `replace` set to `true`, records Modulify manages are never replaced, and an NS record replaces nothing and is never replaced. It takes every record type `create_dns_record` takes.

Nothing changes unless the whole set can be saved, so one blocked record refuses the call, with that record's reason when the set holds one record and `Some of these records cannot be added, so none of them can be!` otherwise. Every record it would delete has to be named in `replaceRecordIds`, by the `Id` the preview lists under `Replaces`. The call is refused with `This request deletes records that were not confirmed. Preview it again and confirm them!` when it would delete a record that is not named, which happens when the domain changed after the preview. Sites, email or services that rely on a deleted record can stop working, so the tool tells the client to confirm with you first.

The answer carries `Added` and `Removed`, the records it added and deleted, and `Kept`, how many already existed. When every record was already there, it answers `Every record was already in place.` and changes nothing. If saving fails part way, Modulify puts back what it changed, and the refusal ends with `No record was changed!` or, when it could not, with `Only some of the records were saved, so check the DNS records of this domain!`

The new records usually reach every DNS server within a few minutes. It needs the **Manage domains** permission, and the domain must be `active` or `expiring`. A call counts as one change. The workspace can make 30 domain changes a minute, shared with the **Domains** page and covering DNS records, nameservers, the registrant, the transfer lock, auto-renew and transfer codes, and a refusal says how long to wait. See [Add records with a link](https://modulify.ai/docs/publish/add-records-with-a-link).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/apply_dns_records`, sending the inputs below as a JSON object. The token needs the `domains:write` scope.

> **Warning**
>
> This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it.

```bash
curl -X POST https://api.modulify.ai/v1/apply_dns_records \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID","domainId":"DOMAIN_ID","records":[{}]}'
```

Over MCP, the same method is the [apply_dns_records tool](https://modulify.ai/docs/mcp/bought-domains/apply-dns-records).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string | Yes | The workspace that owns the domain. |
| `domainId` | string | Yes | The `_id` of the bought domain, from `list_bought_domains`. |
| `records` | array of objects | Yes | The records, up to 20 in one call. Each takes `type` (`A`, `AAAA`, `ANAME`, `CNAME`, `MX`, `NS`, `SRV` or `TXT`), `host` and `value`, which are required, and `priority`, `weight`, `port`, `ttl` and `replace`. The fields mean what they mean on `create_dns_record`, and `replace` is `true` to let the record take the place of the records it clashes with. |
| `replaceRecordIds` | array of integers | No | The `Id` of every record this call may delete, copied from `Replaces` in the answer of `preview_dns_records`. Leave it out when the set replaces nothing. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.