Add a DNS record to a bought domain
create_dns_record
Adds one DNS record to a domain the workspace bought.
host is the name relative to the domain: @ for the domain itself, www for www.<domain>, and a full name such as www.<domain> is saved as www. Each part between dots takes letters, numbers, hyphens and underscores, and a * as the first part makes a wildcard, which NS and SRV records cannot use.
value depends on the type: an IPv4 address for A, an IPv6 address for AAAA, the text for TXT, up to 2,048 characters on one line, with surrounding double quotes dropped and several quoted parts joined into one, and a full hostname for ANAME, CNAME, MX, NS and SRV, never an IP address. MX and SRV records also take priority, and SRV records take weight and port, with a host that starts with the service and the protocol, such as _sip._tcp, and the target hostname as value. ttl is in seconds, from 300 to 604800.
These are refused:
- A CNAME record on
@. Use an ANAME record there. - An ANAME record on any other name. Use a CNAME record there.
- A CNAME record that points at its own name.
- A CNAME record next to any other record at its name, and any record at a name that holds a CNAME record.
- An ANAME record next to an A, AAAA or other ANAME record at its name.
- An NS record on
@. The domain's own nameservers change withset_domain_nameservers. - A record that already exists with the same name, type and value, and for MX and SRV the same priority.
- A new record once the domain holds 100 records.
A record is also refused at a name where it would clash with one Modulify manages for a site or an email domain of the workspace: anything at a name with a managed CNAME record, a CNAME record at a name with any managed record, an A, AAAA, ANAME or CNAME record where a site's address records are managed, and an MX record where an email domain receives mail. The refusal names the site or email domain that holds them, see Locked records.
The answer is the saved record, which usually reaches every DNS server within a few minutes. It needs the Manage domains permission, and the domain must be active or expiring. 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 a record.
Request
Call it with a POST to https://api.modulify.ai/v1/create_dns_record, sending the inputs below as a JSON object. The token needs the domains:write scope.
It makes changes, so send an Idempotency-Key header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.
curl -X POST https://api.modulify.ai/v1/create_dns_record \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"workspaceId":"WORKSPACE_ID","domainId":"DOMAIN_ID","type":"TYPE","host":"HOST","value":"VALUE"}'Over MCP, the same method is the create_dns_record tool.
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. |
type |
string | Yes | The record type: A, AAAA, ANAME, CNAME, MX, NS, SRV or TXT. |
host |
string | Yes | The name relative to the domain, @ for the domain itself or a part such as www. Up to 253 characters. |
value |
string | Yes | What the record answers: an address, a hostname or the text, depending on the type. For SRV, the target hostname. Up to 4,096 characters as sent. |
priority |
integer | No | Required for MX and SRV, ignored for other types. From 0 to 65535, lower is tried first. |
weight |
integer | No | Required for SRV, ignored for other types. From 0 to 65535. |
port |
integer | No | Required for SRV, ignored for other types. From 1 to 65535. |
ttl |
integer | No | Seconds DNS servers keep the record, from 300 to 604800. Defaults to 300. |
Response
Every call answers with the JSON envelope 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 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 explains every status code a call can answer with.