#goy-spa{display:none!important} PRIVEX We run on it. Private servers, lax abuse policy. 5% off your first bill, code goymail Save 5%

GoyDNS

GoyDNS

JSON API

Scripts talk to /api/v1 with a Bearer key. The dashboard uses cookies. MCP is a different protocol at /mcp.

Mint a key <MCP>

REST /api/v1

Base /api/v1 same path on onion / I2P

Auth gdk_ Bearer, shown once

Caps 5 / 25 / 100 Starter / Pro / Business

Quick start

Mint a key in Settings. Prefix gdk_. The login token is a different secret. Same URLs on onion and I2P. POST bodies are JSON; GET is query-string only.

List domains

shell

curl -sS -H "Authorization: Bearer gdk_…" https://goydns.com/api/v1/zones

Read one domain

shell

curl -sS -H "Authorization: Bearer gdk_…" https://goydns.com/api/v1/zones/example.com

Add a record

shell

curl -sS -H "Authorization: Bearer gdk_…" -H 'Content-Type: application/json' \
  -d "{\"owner\":\"www\",\"type\":\"A\",\"ttl\":\"3600\",\"data\":\"203.0.113.10\"}" \
  https://goydns.com/api/v1/zones/example.com/records

Preview an import

shell

curl -sS -H "Authorization: Bearer gdk_…" -H 'Content-Type: application/json' \
  -d "{\"text\":\"www 3600 A 203.0.113.10\\n@ 3600 MX 10 mail.example.com\",\"preview\":true}" \
  https://goydns.com/api/v1/zones/example.com/import

Export BIND

shell

curl -sS -H "Authorization: Bearer gdk_…" -o example.com.zone "https://goydns.com/api/v1/zones/example.com/export?format=bind"

Auth

gdk_

Bearer: Authorization: Bearer gdk_…. No CSRF. Scripts and MCP.
Cookie: dashboard session. Mutations need X-CSRF-Token (or a form csrf field).

headers

Authorization: Bearer gdk_…
Content-Type: application/json
X-CSRF-Token: …

Each key has a domain scope (one hosted name, or every domain on the account) and a role (read or write). Empty scope and empty role in storage mean all domains and write, so older keys keep working.

read may GET domains, records, export, DS, recheck nameservers, and import with preview: true. write may also change records, replace, unset, batch, TTL, header listing, and import commit.

Keys cannot mint or list other keys, cannot change TOTP, and cannot add or delete domains. Those stay on the logged-in dashboard. A one-domain key that hits another name gets the same 404 as a name the account does not own.

Records

TTL 300-86400. Host @ is the domain apex. * as the leftmost label is a wildcard. No user NS, SOA, or DNSSEC records. A and AAAA must be public addresses. Loopback and documentation ranges are refused. BIND line grammar is on Syntax.

Type	data	Example
A	Public IPv4. Host @ is the apex, * is a wildcard.	203.0.113.10
AAAA	Public IPv6. Same host rules as A.	2001:db8::1
CNAME	Target hostname. Not at the apex.	target.example.net
ALIAS	Apex only. We publish the target's A and AAAA.	target.example.net
TXT	SPF, DKIM, verification. Long values split at 255 bytes.	v=spf1 mx -all
MX	Priority then hostname.	10 mail.example.com
SRV	Priority weight port hostname.	0 0 5060 sip.example.com
HTTPS	Priority target parameters. Target . means this host.	1 . alpn=h2,h3
SVCB	Same shape as HTTPS, for other services.	1 doh.example.net alpn=h2
TLSA	Usage selector matching-type hex. Host like _443._tcp.	3 1 1 <64 hex chars>
CAA	Flags tag value.	0 issue "letsencrypt.org"
NAPTR	Order preference flags service regexp replacement.	100 10 "S" "SIP+D2U" "" _sip._udp
SSHFP	Algorithm type fingerprint hex.	1 1 123456789abcdef0…

GET payloads include wire fields owner, ttl, type, data plus display fields host, host_fqdn, summary, ttl_hint. Mutations still send wire fields. Caps: Starter 5 domains / 50 records / 1 key, Pro 25 / 500 / 5, Business 100 / 2000 / 20.

GET /zones/{zone}

{
  "rrs": [
    {
      "owner": "@",
      "ttl": 3600,
      "type": "A",
      "data": "203.0.113.10",
      "host": "@",
      "host_fqdn": "example.com",
      "summary": "203.0.113.10",
      "ttl_hint": "1h"
    }
  ],
  "ds": "example.com. IN CDS …",
  "ns": { "status": "pending", "names": [], "checked_at": "2026-09-12T00:00:00Z" },
  "ns_hostnames": { "ns1": "ns1.goydns.com", "ns2": "ns2.goydns.com" },
  "user_rrs": 1,
  "max_rrs": 500,
  "soa_serial": "2026091201",
  "listed": true
}

Endpoints

Paths below are under /api/v1. The path still says /zones; that is one hosted domain. Cookie-only routes are called out. Billing and donate stay on the dashboard; they are not for Bearer keys.

Method	Path	Body
GET	/zones	Array of { zone, created, ns, listed } (filtered when the key is scoped)
POST	/zones	{ "zone": "example.com" }. Cookie session only; Bearer 403
GET	/zones/{zone}	{ rrs, ds, ns, ns_hostnames, user_rrs, max_rrs, soa_serial, listed }
DELETE	/zones/{zone}	Cookie session only; Bearer 403
POST	/zones/{zone}/records	{ owner, type, ttl, data } (write)
POST	/zones/{zone}/replace	Old triple plus new fields (write)
POST	/zones/{zone}/unset	{ owner, type, data } or { items: [...] } (write)
POST	/zones/{zone}/batch	{ "text": "www 3600 A 203.0.113.10" } (write)
POST	/zones/{zone}/ttl	{ ttl, items } (write)
POST	/zones/{zone}/import	{ text, preview, replace }. read may preview
POST	/zones/{zone}/raw	{ text, preview }. replace all user records from BIND text. read may preview
GET	/zones/{zone}/export	?format=bind\|json\|csv. records=user omits SOA/NS
GET	/zones/{zone}/ds	{ cds }
POST	/zones/{zone}/ns	Recheck parent NS (rate-limited)
POST	/zones/{zone}/listed	{ listed } header marquee on/off (write). Missing unlisted in storage means on.

Add

JSON

{
  "owner": "www",
  "type": "A",
  "ttl": "3600",
  "data": "203.0.113.10"
}

Replace

JSON

{
  "old_owner": "www",
  "old_type": "A",
  "old_data": "203.0.113.10",
  "owner": "www",
  "type": "A",
  "ttl": "3600",
  "data": "203.0.113.20"
}

Unset

JSON

{
  "owner": "www",
  "type": "A",
  "data": "203.0.113.10"
}

Errors

Failures are JSON { "error": "…" }. Messages stay short. HTTP status matches the table; do not parse the string for branching beyond what you already know from the status.

HTTP	error	When
401	unauthorized	Missing or bad Bearer / session
402	payment required	Inactive account, mutating call
403	forbidden	Read key on a write, Bearer add/delete domain, CSRF, MCP while inactive
404	not found	Unknown domain, or a scoped key on another name
429	slow down	NS recheck and other rate limits

Import

POST /zones/{zone}/import accepts BIND, Cloudflare JSON, CSV, or one record per line. Max 256 KiB. preview: true parses and returns a skip-report with no write. Commit is all-or-nothing and refused if the importable set would exceed the plan record cap. replace: true clears existing user records first.

JSON

{
  "text": "www 3600 A 203.0.113.10\n@ 3600 MX 10 mail.example.com",
  "preview": true,
  "replace": false
}

GoyDNS