- Home
- API and docs
For developers and sysadmins
DNS you can review in a pull request
Every action in the panel has an API endpoint. Use scoped tokens in CI, keep zones in Terraform, and script the rest with the CLI.
# Add an A record to example.com
$ curl -X POST https://api.shieldns.com/v1/zones/example.com/records \
-H "Authorization: Bearer $SHIELDNS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"A","name":"www","content":"203.0.113.10","ttl":300}'
{
"id": "rec_8f2c41",
"type": "A",
"name": "www.example.com.",
"content": "203.0.113.10",
"ttl": 300,
"status": "live on 65 PoPs"
}# main.tf
terraform {
required_providers {
shieldns = { source = "shieldns/shieldns" }
}
}
resource "shieldns_zone" "main" {
name = "example.com"
dnssec = true
}
resource "shieldns_record" "www" {
zone = shieldns_zone.main.name
name = "www"
type = "CNAME"
content = "app.example.net."
ttl = 300
}# Point home.example.com at this machine's public IP
$ curl -fsS "https://ddns.shieldns.com/update?host=home.example.com&token=$DDNS_TOKEN"
good 198.51.100.24
# Run it every five minutes from cron
$ crontab -e
*/5 * * * * curl -fsS "https://ddns.shieldns.com/update?host=home.example.com&token=$DDNS_TOKEN"
# Routers: use the "Custom DynDNS" option with
# server ddns.shieldns.com and your host token
REST API
One API for zones, records and checks
JSON over HTTPS at api.shieldns.com/v1. Authenticate with a bearer token, scoped to the zones and actions it needs.
- Scoped tokens per zone, read-only or read-write, with expiry dates.
- Idempotent writes with an
Idempotency-Keyheader for safe retries. - Rate limits returned in headers on every response.
- Audit log entry for every change, with the token that made it.
| Method | Path | Action |
|---|---|---|
| GET | /v1/zones | List zones |
| POST | /v1/zones | Create a zone |
| GET | /v1/zones/{zone}/records | List records |
| POST | /v1/zones/{zone}/records | Add a record |
| PATCH | /v1/zones/{zone}/records/{id} | Change a record |
| DELETE | /v1/zones/{zone}/records/{id} | Delete a record |
| POST | /v1/zones/{zone}/import | Import a BIND file |
| POST | /v1/zones/{zone}/dnssec | Enable DNSSEC |
| GET | /v1/zones/{zone}/dnssec/ds | Get DS records |
| POST | /v1/checks | Create a health check |
Terraform
Infrastructure as code, DNS included
The ShieldNS provider manages zones, records, DNSSEC and health checks. Import existing zones into state and review every change as a plan before it goes live.
$ terraform import shieldns_zone.main example.com
shieldns_zone.main: Import prepared!
$ terraform plan
+ resource "shieldns_record" "www" {
+ name = "www"
+ type = "CNAME"
+ content = "app.example.net."
+ ttl = 300
}
Plan: 1 to add, 0 to change, 0 to destroy.# IPv4 and IPv6 in one request
$ curl -fsS "https://ddns.shieldns.com/update?host=home.example.com&myip=198.51.100.24,2001:db8::24&token=$DDNS_TOKEN"
good 198.51.100.24 2001:db8::24
# Same address again: nothing changes
$ curl -fsS "https://ddns.shieldns.com/update?host=home.example.com&token=$DDNS_TOKEN"
nochg 198.51.100.24Dynamic DNS
Keep a name on a moving address
Point a hostname at a home office, a lab or a site with a changing IP. Updates use a per-host token, so a leaked router password never exposes your account.
- Works with routers that support custom DynDNS URLs.
- IPv4 and IPv6 updated in the same request.
- Per-host tokens you can rotate without touching other hosts.
Zone import
Bring zones as they are
Upload a BIND zone file or pull the zone over AXFR from your current provider. We parse every record type and show you what will change before you commit.
$ curl -X POST https://api.shieldns.com/v1/zones/example.com/import \
-H "Authorization: Bearer $SHIELDNS_TOKEN" \
-H "Content-Type: text/dns" \
--data-binary @example.com.zone
{ "added": 42, "skipped": 0, "warnings": [] }
Support
Engineers answer your API questions
Support is staffed by the people who run the network. Send the request ID from any API response and we can see exactly what happened.
Move your DNS to an answer you can trust
Import a zone in minutes, check every answer before you switch, and only then change your name servers.