The short answer: the API reads and changes the DNS zone of the active domains in your account that have DNS switched on (you switch it on in Meu MozOut). With dns:read you read; with dns:write you add, change and delete records. Before every change a zone backup is kept, and the last 20 per domain are stored.
The operations
| Operation |
What it does |
| GET /v1/domains/{domain}/dns |
Lists the records. Those with read_only set to true, such as the root NS, cannot be changed here. |
| POST /v1/domains/{domain}/dns |
Adds a record: name, type, value and, optionally, ttl and priority. |
| POST /v1/domains/{domain}/dns/validate |
Checks a record without saving it. dns:read is enough. |
| PUT /v1/domains/{domain}/dns/{record_id} |
Changes a record. |
| DELETE /v1/domains/{domain}/dns/{record_id} |
Deletes a record. |
| GET /v1/domains/{domain}/dns/backups |
Lists the zone backups. |
| POST /v1/domains/{domain}/dns/backups/{id}/restore |
Restores a backup. |
| POST /v1/domains/{domain}/dns/reset |
Empties the zone of your records. Needs the domain name in confirm. |
The accepted types are A, AAAA, CNAME, MX, TXT, NS, SRV and CAA. Nameservers are changed in the domains part: see domains through the API.
Example: a TXT verification record
| 1 |
Check it first with POST /v1/domains/{domain}/dns/validate, using the same body you will save.
|
|
| 2 |
Save it with POST /v1/domains/{domain}/dns. Use @ as the name for the domain itself.
|
|
| 3 |
Read the answer: it shows what ended up in the zone, which is what counts.
|
|
curl https://api.mozout.co.mz/v1/domains/asuaempresa.co.mz/dns -X POST \
-H "Authorization: Bearer $RLX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "@", "type": "TXT", "value": "verification=abc123", "ttl": 14400}'
|
Quotes in a TXT: quotes around the whole value are removed; quotes or backslashes in the middle of the text answer 422, because the DNS server would store a different value. And a CNAME cannot share its name with other records: that answers 409 with cname_conflict.
|
A record's id changes
A record's id changes when its name, type, value or priority changes; changing only the ttl keeps the same id. Always use the id from the latest list, or the next change answers 404. An AAAA address comes back in its short form.
The domain of the account e-mail
If the e-mail you sign in with, or that of one of your users, is on this domain (or a subdomain of it), the API refuses, with 409 account_email_domain and in Sandbox too, anything that decides where the mail goes: the MX records for that name; the A, AAAA, CNAME and NS records of the name the MX points to (or, without MX, of the name itself); resetting the zone and restoring a backup that touches these records. Make those changes in Meu MozOut. All other records can still be changed through the API.
Backups and limits
| What |
How it works |
| Zone backups |
One before every change; the last 20 per domain are kept. |
| Incomplete restore |
If complete comes back false, a record in the backup could not be put back exactly as it was: check the list. |
| Changes |
20 per minute, per account, on top of the general limit. |
| Zone reads |
30 per minute, per account. The list may come from a copy up to 60 seconds old, which does not count towards that limit. |
|
What you change through the API shows at once; what you change in Meu MozOut can take up to 60 seconds to show in the API. Before a big change, list the backups: if something goes wrong, restoring is a single request.
|
|
Want to automate the DNS of your domains? See the API page and test with a Sandbox key, which simulates the changes.
See the API page
|
Português
English
