If you only touch DNS a couple of times a year, Cloudflare's dashboard is usually enough. The API starts paying for itself when DNS changes are part of launches, migrations, white-label client work, or repeatable operational handovers. In those situations, the real gain is not raw speed. It is lower risk, clearer approvals, and a workflow another person can take over without guesswork.
As of June 9, 2026, Cloudflare's current documentation still supports a simple bash-first approach for DNS automation, including BIND zone imports. What no longer makes sense is building that around a broad Global API key. Cloudflare's current recommendation is to use scoped API tokens, and that is the right baseline for any serious team workflow.
When the Cloudflare API is worth using
- Bulk DNS changes during a migration, replatform, or launch.
- Repeatable setup work across multiple environments or client zones.
- Preflight checks in deployment pipelines for records that must exist before traffic moves.
- Agency or operations handovers where a readable script is safer than a memory of dashboard clicks.
If your use case is still occasional and one-off, keep it simple and use the dashboard. Automation becomes worth the effort when repeatability, review, and handover matter.
Start with the smallest safe token
Use a zone-scoped API token whenever possible. For inventory or verification, DNS Read is enough. For record changes or imports, use DNS Write. Cloudflare also supports Account API tokens for compatible endpoints, which is useful when you want a service token that is not tied to one employee login.
One practical detail matters for locked-down automation: looking up a zone ID through GET /zones requires Zone Zone Read. If you want the working token to stay limited to DNS permissions, fetch the zone ID once from the dashboard, store it securely, and reuse it in your script or CI secret store.
export CLOUDFLARE_API_TOKEN="..."
export ZONE_ID="..."
CF_API="https://api.cloudflare.com/client/v4"
curl --fail --silent --show-error "$CF_API/user/tokens/verify" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"If you do need to discover the zone through the API, keep that as a separate step so the extra permission is explicit:
curl --fail --silent --show-error "$CF_API/zones?name=example.com" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"A small bash workflow that teams can trust
The safest pattern is simple: verify access, read the current state, make one narrow change, and leave a note another human can understand later. Cloudflare supports record comments, and they are worth using. A ticket number, migration note, or owner label makes later audits and client handovers much easier. Comments are private metadata inside Cloudflare; they do not affect DNS resolution.
Before changing records, list what exists in the zone. That catches wrong-zone mistakes early and gives you something concrete to review in a change request or pull request.
curl --fail --silent --show-error "$CF_API/zones/$ZONE_ID/dns_records" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
curl --fail --silent --show-error "$CF_API/zones/$ZONE_ID/dns_records" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"type":"A","name":"app.example.com","content":"198.51.100.4","ttl":3600,"proxied":true,"comment":"App origin - ticket OPS-142"}'A few record-model rules are still the usual source of avoidable errors. A and AAAA records cannot share the same hostname with a CNAME. NS records cannot share a name with any other record type. For TTL values, the API treats 1 as automatic; otherwise the allowed range is generally 60 to 86400 seconds, with 30 seconds available on Enterprise zones. Those are small details, but they are exactly the kind of details that break rushed launch-night scripts.
Importing a BIND zone file without creating a mess
If your real job is a migration, the import and export endpoints are often more valuable than single-record calls. Export first. Review the source file. Then import into the target zone with the narrowest token that can do the job. That gives you a rollback reference and makes it easier to spot inherited problems before they become Cloudflare problems.
curl --fail --silent --show-error "$CF_API/zones/$ZONE_ID/dns_records/export" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--output zone-export.txt
curl --fail --silent --show-error "$CF_API/zones/$ZONE_ID/dns_records/import" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--form "file=@your_formatted_file.txt"Cloudflare's current DNS docs call out a few limits that matter in real migrations. Zone files are capped at 256 KiB, and the API limit is three import or export requests per minute per user. That is a good reason to review failures instead of hammering the endpoint with blind retries.
Formatting issues are where most imports go sideways. For CNAME, DNAME, MX, NS, PTR, and SRV records, the target should be a fully qualified domain name with a trailing period, such as example.com.. Cloudflare supports $ORIGIN, $TTL, and $GENERATE, but not $INCLUDE. If your current DNS setup relies on included files, flatten them before import. And if proxy status matters record by record, Cloudflare's cf-proxied:true and cf-proxied:false tags inside the zone file take precedence during import, which is useful when only some records should sit behind Cloudflare.
What a maintainable setup looks like
For a single site, a few curl commands may be enough. For a business with multiple environments, or an agency managing several client zones, the goal is not more automation for its own sake. The goal is boring automation: obvious inputs, narrow permissions, readable output, and a script someone else can run safely six months from now.
- Keep zone IDs and tokens out of the script body and in a proper secret store.
- Use separate read and write tokens if you want stricter approvals.
- Version the script, even if it is only a short bash file.
- Use comments so each record change has business context.
- Treat imports like migrations, not like clipboard operations.
If you only change one or two records a year, the dashboard is still probably cheaper. But if launches, migrations, or agency handovers keep touching DNS, a small Cloudflare API workflow quickly pays for itself in fewer mistakes and clearer ownership. If you want that set up cleanly without turning DNS into a bigger project than it needs to be, talk with Greg about a safer Cloudflare DNS workflow.
Need help with this kind of work?
Talk with Greg about a safer Cloudflare DNS workflow Get in touch with Greg.