Change DNS records in several zones
POST /api/v2/domains/bulk/dns
Add, update or delete DNS records in several DNS zones with one call. Pick the change with action. add and update take the records in records. delete takes deleteType and the filter field that goes with it.
update looks in each zone for a record of the same type whose stored name equals name. Zones store full names such as _dmarc.example.se. A short name such as _dmarc or @ finds nothing. The record is then added next to the old one. To replace an A or AAAA record on many domains, add the new record and delete the old one with deleteType by_value.
Name the zones by domain name in domainNames, for example example.se. Every domain must be in your account and have its DNS zone with Hostup. Otherwise the whole batch is rejected. A key that is limited to some DNS zones or records is rejected for changes outside those limits.
Before the job is queued, the current records of each zone are saved as a snapshot (GET /api/v2/domains/{id}/dns/snapshots). The call returns 202 with a job. Follow it at operation.pollUrl (Jobs). The job ends completed even when some zones fail. Each zone’s outcome is in the job’s result.results[]: success, the counts and, for add and update, each record with its error. With update, a record that could not be written can still show success: true. Check the zone afterwards with GET /api/v2/dns-zones/{id}/records. A delete that matches nothing counts as failed.
Authentication: An API key with the scope write:dns. About keys and scopes
Request
Body
actionstringrequiredadd creates the records. update changes a record of the same type whose stored full name equals name and adds the record when none matches. A short name such as www or @ never matches. delete removes the records that match deleteType. One of add, update, delete.domainNamesarray of stringrequiredexample.se. Not domain IDs.recordsarray of objectaction is add or update. Record types in capitals, such as TXT. MX and SRV records need priority.typestringrequiredTXT records whose value starts with v=spf1. One of A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA.namestring@ or an empty string, for the zone root. Use a label such as www or _dmarc, not the full name www.example.com. Responses return full names. For an NS record, send only the subdomain label: in the zone example.com, name: "shop" delegates shop.example.com. That does not change the nameservers of example.com itself. Change domain nameservers does that.valuestringrequiredttlintegerpriorityintegerweightintegerportintegerdeleteTypestringaction is delete. all deletes every record in each zone, the SOA record and the NS records at the domain itself included. by_type deletes records of recordType. by_name deletes records named recordName. by_value deletes records whose value is recordValue. One of all, by_type, by_name, by_value.recordTypestringTXT. Required when deleteType is by_type.recordNamestring_dmarc.example.se. A short name such as _dmarc matches nothing. A full name matches in one zone only. @ is the domain itself and works in every zone. Required when deleteType is by_name. With by_type it limits the delete to this name.recordValuestringdeleteType is by_value.Example
curl -X POST "https://cloud.hostup.se/api/v2/domains/bulk/dns" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "add", "domainNames": [ "example.se", "example.nu" ], "records": [ { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none", "ttl": 3600 } ] }'curl -X POST "https://cloud.hostup.se/api/v2/domains/bulk/dns" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "add", "domainNames": [ "example.se", "example.nu" ], "records": [ { "type": "ALIAS", "name": "@", "value": "target.example.com", "ttl": 3600 } ] }'curl -X POST "https://cloud.hostup.se/api/v2/domains/bulk/dns" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "delete", "domainNames": [ "example.se", "example.nu" ], "deleteType": "by_type", "recordType": "TXT" }'Responses
202 Job queued. Follow it at operation.pollUrl.
{ "operation": { "status": "pending", "jobId": "dbj_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": "/api/jobs/dbj_01hxa3b4c5d6e7f8g9h0j1k2m3" }, "action": "add", "domainsQueued": 2}Response fields
operationobjectstatusstring202 Accepted response only has pending, queued or in_progress. completed and failed appear when you poll pollUrl. They also appear in a 200 OK response when the action finished during the request. One of pending, queued, in_progress, completed, failed.jobIdstringpollUrlstring or nullnull when status is already completed or failed.actionstringadd, update, delete.domainsQueuedinteger or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_request. Nothing is queued. With a pointer in errors[]: an unknown action or deleteType, a field the action does not take, an empty domainNames or records, or a delete without its filter field. Without a pointer and with the detail The bulk DNS operation request is invalid.: a record did not pass the checks, recordType is not a record type in capitals, or a domain has no DNS zone at Hostup. The response does not say which. Check that ttl is 60 to 86400 and that MX and SRV records have priority. Check that each domain is in GET /api/v2/dns-zones. |
| 401 | Unauthorized. Authentication is required. |
| 403 | forbidden. Nothing is queued. The key lacks write:dns: requiredScopes names it. A name in domainNames is not in the account: errors[] points at each one, for example /domainNames/1. Access denied. without a list has two causes. A domain has only its DNS zone at Hostup and is not a domain in the account. Or the change is outside the DNS zones and records the key may change. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |