HF PanelDocsv1.0.0

API: DNS

List a hosting account's DNS zones and add, change and delete their records through the token API.

These endpoints work on the DNS zones of one hosting account, like the DNS zone editor in Control Panel. Every change goes through the zone editor itself: the same record checks, the zone is published at once and the change is written to the account's activity log.

bash
A=https://api.yourdomain.com:2087/v1
H="Authorization: Bearer hf_xxx"

Per-account endpoints

The path names the account: /v1/accounts/{username}/….

  • A customer's token works on its own account only. Any other username answers 404 "No such account."
  • An administrator's token works on any account; a reseller's token on their own customers' accounts. Staff work as Log in as does: the activity log says "(by )", and a reseller needs the Log in as privilege.
  • The account's plan applies: a switched-off feature answers 403 "This feature is not part of your hosting plan."
  • Changes need a Read & change token.

List the zones

GET /v1/accounts/{username}/dns: each main and parked domain, with how many records it has.

bash
curl -s -H "$H" $A/accounts/sarahbakes/dns
json
{
    "ok": true,
    "data": [
        {
            "domain": "example.com",
            "dnssec": false,
            "records": 9
        }
    ]
}

Read a zone

GET /v1/accounts/{username}/dns/{zone}: the zone with every record. An unknown zone answers 404 "No such DNS zone on this account."

json
{
    "ok": true,
    "data": {
        "domain": "example.com",
        "dnssec": false,
        "records": [
            {
                "id": 41,
                "name": "@",
                "type": "A",
                "value": "192.0.2.10",
                "ttl": 3600,
                "priority": 0
            },
            {
                "id": 44,
                "name": "@",
                "type": "MX",
                "value": "mail.example.com.",
                "ttl": 3600,
                "priority": 10
            }
        ]
    }
}
Field What it is
id the record's id, used to change or delete it
name @ for the zone itself, or the part before the zone (www, _dmarc)
type A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA or NS
value the record's value; host names end with a dot
ttl seconds
priority for MX and SRV; 0 otherwise

Add a record

POST /v1/accounts/{username}/dns/{zone}/records. 201 with the new record.

bash
curl -s -X POST -H "$H" -H "Content-Type: application/json" \
  -d '{"name":"shop","type":"CNAME","value":"shops.myshopify.com","ttl":600}' \
  $A/accounts/sarahbakes/dns/example.com/records
Field What it does
type required
value required
name default @
ttl default 3600
priority MX and SRV

The zone editor's rules apply and answer 422 with its message, for example: a CNAME must be the only record for its name, and a name gets its address from A/AAAA records or from one ALIAS, not both.

Change a record

PATCH /v1/accounts/{username}/dns/{zone}/records/{id} (or PUT). Send only what changes; the other fields keep their value. Answers with the record.

bash
curl -s -X PATCH -H "$H" -H "Content-Type: application/json" -d '{"ttl":300}' \
  $A/accounts/sarahbakes/dns/example.com/records/41

Delete a record

DELETE /v1/accounts/{username}/dns/{zone}/records/{id}. A record that is not in the zone answers 404 "No such record in this zone."

json
{
    "ok": true,
    "data": {
        "deleted": 41
    }
}

Note: changes reach the internet within minutes, up to the record's old TTL.