A batch applies creates, updates and deletes of one zone's records as one change: one version, one diff, one rollback. Either every operation is applied or none is. Use it to migrate a zone, to replace a set of records (for example the mail records of a new provider) or for any change that would leave the zone inconsistent halfway.
The dashboard uses batches too: bulk delete and bulk proxy switch in DNS › Records, imports, and the email wizard.
Request
POST /v1/orgs/{org}/zones/{zone}/records/batch, with the tech role or higher.
{
"delete": ["0b9c6c2e-1f7a-4a39-9d1e-2b8f3c5d7e01"],
"update": [
{"id": "5a1e2f3b-6c7d-4e8f-9a0b-1c2d3e4f5a6b", "content": "203.0.113.20"}
],
"create": [
{"type": "MX", "name": "@", "content": "mx1.example.net", "priority": 10},
{"type": "MX", "name": "@", "content": "mx2.example.net", "priority": 20},
{"type": "TXT", "name": "@", "content": "v=spf1 include:_spf.example.net -all"}
]
}| Field | Content |
|---|---|
create | Records with the same fields as a single create: type, name, content, ttl, priority, proxied, comment, tags |
update | id of the record plus only the fields that change ("priority": null clears it) |
delete | Ids of the records to delete |
Rules:
- 1 to 500 operations in total. More:
422 invalidwith “at most 500 operations per batch”. - Each record can be updated or deleted only once in the same batch.
- Operations run as deletes, then updates, then creates. Each record is validated as it is written, and the coexistence rules are checked on the final state of every name the batch touches. So one batch can, for example, replace an
Arecord with aCNAMEat the same name. - As with a single update, switching the proxy of one
A,AAAAorCNAMErecord switches the other records at that name that the batch does not change. - An error names the failing operation in its
field, for examplecreate[2].content.
Simulate and apply
# Simulate: validates everything and returns the diff, applying nothing
curl -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/records/batch?dry_run=1" \
-H "Authorization: Bearer $OPENWAF_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Change-Reason: Move mail to the new provider" \
--data @batch.json
# Apply against the version you simulated
curl -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/records/batch" \
-H "Authorization: Bearer $OPENWAF_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Change-Reason: Move mail to the new provider" \
-H 'If-Match: "41"' \
--data @batch.jsonBoth answer 200 with from_version, to_version, diff, warnings and records, the zone's records after the change. If the zone changed since the version in If-Match, the batch is refused with 412 version_conflict.
Ask your assistant for the change; it calls apply_records_batch with zone, create, update and delete. The first call (confirm: false) only simulates and returns the diff and current_version; after you approve, the same call with confirm: true and expected_version applies it. The tool is marked destructive when it deletes records.
Select records in DNS › Records and use Delete, Proxy on or Proxy off; the dialog lists every record the change touches and applies it as one version.
Undo a batch
A batch is one version, so reverting to the version before it undoes all its operations at once. See Zone versions.