Blog

The CloudFloorDNS API lets you manage DNS from code: create zones, change records, run secondary DNS, switch on DNSSEC, set up Netmon monitoring and failover, and handle domain registrations. It’s a plain JSON REST API with more than 100 endpoints, and you can call it from anything that speaks HTTP.

This guide takes you from nothing to useful automation: your first authenticated request, a small Python client, a drop-in Certbot hook for wildcard Let’s Encrypt certificates, and a nightly zone backup. The examples follow the published API reference, so you can copy them, swap in your own domain and API key, and run them.

Six things worth knowing before you write any code

The reference documents every endpoint. These are the details that tend to cost people an afternoon.

Your first API calls, step by step

The examples use curl and example.com. Replace it with a zone on your account.

export CFDNS_USER='your-panel-username'
# Prompts without echoing, so the key stays out of your shell history
printf 'API key: '; read -rs CFDNS_KEY; echo; export CFDNS_KEY
export API='https://apiv3.mtgsy.net/api/v1'
# Credentials for the Basic auth header: base64 of username:api_key
AUTH=$(printf '%s:%s' "$CFDNS_USER" "$CFDNS_KEY" | base64 | tr -d '\n')

curl -s -H "Authorization: Basic $AUTH" "$API/dns/zone2"

{
  "statusCode": 200,
  "data": [
    {
      "id": 10234,
      "domainname": "example.com",
      "primary": 1,
      "secondary": 0,
      "group_ids": []
    }
  ]
}

curl -s -H "Authorization: Basic $AUTH" \
  "$API/dns/zone2/example.com/record"

{
  "statusCode": 200,
  "data": {
    "id": 10234,
    "domainname": "example.com",
    "records": [
      { "name": "example.com", "type": "A",
        "content": "203.0.113.5", "ttl": 3600,
        "disabled": 0, "comment": "" },
      { "name": "www.example.com", "type": "CNAME",
        "content": "example.com.", "ttl": 3600,
        "disabled": 0, "comment": "" }
    ]
  }
}

curl -s -H "Authorization: Basic $AUTH" \
  "$API/dns/zone2/example.com/record" |
  jq -r '.data.records[] | [.name, .ttl, .type, .content] | @tsv'

curl -s -H "Authorization: Basic $AUTH" -X POST \
  -H 'Content-Type: application/json' \
  "$API/dns/zone2/example.com/record" \
  --data '{
    "records": [
      { "name": "app.example.com", "type": "A",
        "content": "203.0.113.10", "ttl": 3600 },
      { "name": "example.com", "type": "MX",
        "content": "10 mail.example.com.", "ttl": 3600 },
      { "name": "example.com", "type": "TXT",
        "content": "\"site-verification=4f9c2a7e\"", "ttl": 3600 }
    ]
  }'

curl -s -H "Authorization: Basic $AUTH" -X PATCH \
  -H 'Content-Type: application/json' \
  "$API/dns/zone2/example.com/record" \
  --data '{
    "search_type": "A",
    "search_name": "app.example.com",
    "search_content": "203.0.113.10",
    "content": "203.0.113.20",
    "ttl": 300
  }'

curl -s -H "Authorization: Basic $AUTH" -X PATCH \
  -H 'Content-Type: application/json' \
  "$API/dns/zone2/example.com/delete_record" \
  --data '{ "type": "A", "name": "app.example.com",
            "content": "203.0.113.20" }'

A small Python client

Past a one-off, it pays to wrap the calls. This client needs only requests (python3-requests from your distribution, or pip install requests in a virtualenv). It builds the Basic auth header, waits and retries on an HTTP 429 or a 503 on a read, and turns API errors into exceptions that carry the API’s own description.

"""Minimal client for the CloudFloorDNS API (Zone2 endpoints)."""
import base64
import time

import requests

API_BASE = "https://apiv3.mtgsy.net/api/v1"


class CloudFloorDNSError(Exception):
    pass


class CloudFloorDNS:
    def __init__(self, username, api_key, base_url=API_BASE, timeout=30):
        self.base_url = base_url.rstrip("/")
        self.timeout = timeout
        creds = base64.b64encode(f"{username}:{api_key}".encode()).decode()
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Basic {creds}",  # base64(username:api_key)
            "Accept": "application/json",
        })

    def _request(self, method, path, **kwargs):
        kwargs.setdefault("timeout", self.timeout)
        url = self.base_url + path
        for attempt in range(5):
            resp = self.session.request(method, url, **kwargs)
            # Rate limited, or a read hit a temporary 503: wait and retry
            retry = resp.status_code == 429 or (
                resp.status_code == 503 and method == "GET")
            if not retry:
                break
            wait = resp.headers.get("Retry-After", "")
            time.sleep(int(wait) if wait.isdigit() else 2 ** attempt)
        try:
            body = resp.json()
        except ValueError:
            body = {}
        if not resp.ok:
            err = body.get("error") or {}
            detail = err.get("description") or resp.text[:200]
            raise CloudFloorDNSError(
                f"{method} {path} -> {resp.status_code}: {detail}")
        return body.get("data")

    # Zones
    def zones(self):
        """Your zones on the Zone2 platform."""
        return self._request("GET", "/dns/zone2")

    def export(self, domain):
        """The whole zone as BIND zone-file text."""
        data = self._request("GET", f"/dns/zone2/{domain}/export")
        return data["zone_content"]

    # Records
    def records(self, domain, rtype=None, name=None):
        data = self._request("GET", f"/dns/zone2/{domain}/record")
        recs = data["records"]
        if rtype:
            recs = [r for r in recs if r["type"] == rtype.upper()]
        if name:
            recs = [r for r in recs if r["name"].lower() == name.lower()]
        return recs

    def add(self, domain, *records):
        """Create records: dicts with name, type, content and ttl."""
        path = f"/dns/zone2/{domain}/record"
        return self._request("POST", path, json={"records": list(records)})

    def update(self, domain, rtype, name, current_content, **changes):
        """Change content, ttl, disabled or comment on an exact match."""
        body = {"search_type": rtype, "search_name": name,
                "search_content": current_content, **changes}
        path = f"/dns/zone2/{domain}/record"
        return self._request("PATCH", path, json=body)

    def delete(self, domain, rtype, name, content):
        """Delete the record with exactly this type, name and content."""
        body = {"type": rtype, "name": name, "content": content}
        path = f"/dns/zone2/{domain}/delete_record"
        return self._request("PATCH", path, json=body)

Using it:

import os

from cfdns import CloudFloorDNS

cf = CloudFloorDNS(os.environ["CFDNS_USER"], os.environ["CFDNS_KEY"])

# Print every record in the zone
for r in cf.records("example.com"):
    print(f'{r["name"]:<32} {r["ttl"]:>6}  {r["type"]:<6} {r["content"]}')

# Add a host, repoint it with a short TTL, then remove it
cf.add("example.com", {"name": "app.example.com", "type": "A",
                       "content": "203.0.113.10", "ttl": 3600})
cf.update("example.com", "A", "app.example.com", "203.0.113.10",
          content="203.0.113.20", ttl=300)
cf.delete("example.com", "A", "app.example.com", content="203.0.113.20")

Recipe: wildcard Let’s Encrypt certificates with DNS-01

Let’s Encrypt issues wildcard certificates only through the DNS-01 challenge: you prove control of a domain by publishing a TXT record at _acme-challenge.<domain>. Certbot can run one script to publish that record and another to remove it. These three small files make issuance and renewal automatic for your primary zones on Zone2.

1. Shared settings

Your credentials plus two helpers. cfdns calls the API with the Basic auth header and prints the API’s error message if a call fails. find_zone works out which of your zones a name belongs to, so the TXT record for a certificate on api.example.com goes into the example.com zone.

# Shared by both certbot hooks. It holds your API key, so: chmod 600
CFDNS_USER="your-panel-username"
CFDNS_KEY="your-api-key"
API="https://apiv3.mtgsy.net/api/v1"
AUTH=$(printf '%s:%s' "$CFDNS_USER" "$CFDNS_KEY" | base64 | tr -d '\n')

cfdns() {  # usage: cfdns METHOD PATH [JSON-BODY]
  local args=(-sS -w '\n%{http_code}' -H "Authorization: Basic ${AUTH}"
              -X "$1" "${API}$2")
  if [[ $# -ge 3 ]]; then
    args+=(-H "Content-Type: application/json" --data "$3")
  fi
  local out
  out=$(curl "${args[@]}") || { CFDNS_STATUS=000; return 1; }
  CFDNS_STATUS=${out##*$'\n'}
  if [[ "$CFDNS_STATUS" != 2* ]]; then
    echo "CloudFloorDNS API: HTTP ${CFDNS_STATUS} ${out%$'\n'*}" >&2
    return 1
  fi
}

find_zone() {  # walk up from the certificate name to the zone hosted with us
  local zone="$1"
  while [[ "$zone" == *.* ]]; do
    if cfdns GET "/dns/zone2/${zone}/record" 2> /dev/null; then
      echo "$zone"
      return 0
    elif [[ "$CFDNS_STATUS" != 404 ]]; then
      echo "CloudFloorDNS API: HTTP ${CFDNS_STATUS} looking up ${zone}" >&2
      return 1
    fi
    zone="${zone#*.}"
  done
  echo "No CloudFloorDNS Zone2 zone found for $1" >&2
  return 1
}

2. The auth hook

Publishes the token, then waits until each of the zone’s nameservers returns it (as seen from this server), so Let’s Encrypt is less likely to check too early. If a nameserver still hasn’t got it after about two minutes, the hook prints a warning and carries on.

#!/usr/bin/env bash
# certbot --manual-auth-hook: publish the DNS-01 token as a TXT record
set -euo pipefail
source /etc/letsencrypt/cfdns.sh
command -v dig > /dev/null || { echo "dig is required" >&2; exit 1; }

ZONE=$(find_zone "$CERTBOT_DOMAIN")
NAME="_acme-challenge.${CERTBOT_DOMAIN}"
BODY=$(printf '{"records": [{"name": "%s", "type": "TXT", "ttl": 60,
                "content": "\\"%s\\""}]}' "$NAME" "$CERTBOT_VALIDATION")

cfdns POST "/dns/zone2/${ZONE}/record" "$BODY"

# Wait (up to ~2 minutes per nameserver) until each one returns the token
for ns in $(dig +short NS "$ZONE"); do
  for _ in $(seq 24); do
    answer=$(dig +short +time=2 +tries=1 TXT "$NAME" @"$ns" || true)
    [[ "$answer" == *"$CERTBOT_VALIDATION"* ]] && continue 2
    sleep 5
  done
  echo "Warning: $ns is not serving the token yet; continuing" >&2
done

3. The cleanup hook

Removes only the value it created. That matters when one certificate covers example.com and *.example.com, because both challenges use the same _acme-challenge name with different values.

#!/usr/bin/env bash
# certbot --manual-cleanup-hook: remove the TXT record the auth hook created
set -euo pipefail
source /etc/letsencrypt/cfdns.sh

ZONE=$(find_zone "$CERTBOT_DOMAIN")
NAME="_acme-challenge.${CERTBOT_DOMAIN}"
BODY=$(printf '{"type": "TXT", "name": "%s", "content": "\\"%s\\""}' \
         "$NAME" "$CERTBOT_VALIDATION")

cfdns PATCH "/dns/zone2/${ZONE}/delete_record" "$BODY"

4. Issue the certificate

sudo chmod 600 /etc/letsencrypt/cfdns.sh
sudo chmod 700 /etc/letsencrypt/cfdns-auth.sh \
               /etc/letsencrypt/cfdns-cleanup.sh

sudo certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook /etc/letsencrypt/cfdns-auth.sh \
  --manual-cleanup-hook /etc/letsencrypt/cfdns-cleanup.sh \
  -d example.com -d '*.example.com'

Certbot saves the hook paths in the certificate’s renewal settings, so certbot renew, and the renewal timer most packages install, keep working without you.

Recipe: nightly zone file backups

GET /dns/zone2/{domain}/export returns a whole zone as zone-file text. Loop over your Zone2 zones and you have an offline copy you can diff, archive, or load into another DNS server in an emergency. The script paces itself to stay under the GET limit, and if one export fails it carries on with the rest and exits non-zero so cron can tell you.

#!/usr/bin/env python3
"""Export every Zone2 zone to a dated folder of BIND zone files."""
import datetime
import os
import pathlib
import sys
import time

from cfdns import CloudFloorDNS, CloudFloorDNSError

cf = CloudFloorDNS(os.environ["CFDNS_USER"], os.environ["CFDNS_KEY"])
outdir = pathlib.Path("zone-backups", datetime.date.today().isoformat())
outdir.mkdir(parents=True, exist_ok=True)

failed = []
for zone in cf.zones():
    name = zone["domainname"]
    try:
        (outdir / f"{name}.zone").write_text(cf.export(name))
        print(f"saved {name}")
    except CloudFloorDNSError as err:
        failed.append(name)
        print(f"FAILED {name}: {err}", file=sys.stderr)
    time.sleep(0.5)  # stay under 120 GET requests a minute

sys.exit(1 if failed else 0)

Make it executable (chmod +x backup_zones.py) and run it nightly from cron, with your credentials in a root-only environment file next to the script:

# /etc/cron.d/dns-backup  (cfdns.env exports CFDNS_USER and CFDNS_KEY)
15 3 * * *  root  cd /opt/dns-backup && . ./cfdns.env && ./backup_zones.py

Prefer a change history? Write to a fixed folder instead of a dated one and commit it to git each night. git log -p then shows exactly what changed in your DNS, and when.

Still on Zone1?

Zone1 has its own record endpoints and identifies each record by a numeric id. A record carries id, name, type, data, aux, ttl and active (Y or N), and you change or delete it by id. Deletes use the DELETE method:

# Zone1 records include an id...
curl -s -H "Authorization: Basic $AUTH" \
  "$API/dns/zone/example.com/record"

# ...which you use to change or remove a record
curl -s -H "Authorization: Basic $AUTH" -X PATCH \
  -H 'Content-Type: application/json' \
  "$API/dns/zone/example.com/record/123456" \
  --data '{ "data": "203.0.113.20", "ttl": 300 }'

curl -s -H "Authorization: Basic $AUTH" -X DELETE \
  "$API/dns/zone/example.com/record/123456"

Moving a zone to Zone2 takes three calls: request the migration, approve it, then check its status. If you’d like a second pair of eyes before moving a busy zone, email support@cloudfloordns.com.

Z="$API/dns/zone/example.com"
curl -s -H "Authorization: Basic $AUTH" -X PATCH "$Z/migrate_to_zone2"
curl -s -H "Authorization: Basic $AUTH" -X PATCH \
  "$Z/approve_migration_to_zone2"
curl -s -H "Authorization: Basic $AUTH" "$Z/migration_status"

What else the API covers

Records are only part of it. Here’s the rest by area; each endpoint in the reference includes a curl example.

Rate limits and errors

Because the limits are per method, the bulk endpoints are worth knowing: one PATCH to bulk_update_records can replace many single updates.

Errors come back with the HTTP status plus a JSON body containing statusCode and an error object with type and description fields. The description is written for humans, so log it.

Frequently asked questions

Related guides

• Secondary DNS with Cloudflare as your primary
• Secondary DNS overview and pricing
• Moving from DNS Made Easy to CloudFloorDNS