The dns.lgbt API

With the API, programs can manage the records and DNSSEC of your domains: get certificates from Let’s Encrypt with DNS challenges, keep a record pointed at a changing IP address, or keep your zone in a repository. Domains themselves are added and deleted in the web app only.

Getting started

1. Open your account and create a token under “API tokens”. Copy it right away: we only store a fingerprint of it, so we can’t show it again.
2. Send it with every request, in the Authorization header. Every address starts with https://dns.lgbt/api/v1.

curl https://dns.lgbt/api/v1/me -H "Authorization: Bearer dnslgbt_pat_…"

Bodies are JSON (Content-Type: application/json), and so are the answers. Changes go live on every nameserver within seconds once the domain is delegated to dns.lgbt: the domain’s publishPending says whether some are still waiting, and its serial grows with every published version.

The API is for people who agreed to our terms of service: until you have agreed to them once in the app, the API answers terms_not_accepted.

Tokens and what they allow

A token belongs to your account and acts for you. Give each program its own token with only what it needs, so you can delete it on its own if it leaks. You can have up to 20.

• Domains: a token can be limited to some of your domains. The others answer not_found, as if they didn’t exist. Without a limit it works for every domain, including the ones you add later.
• Records: a token can be limited to records by name and type, with up to 20 rules. A name ending in .* also covers every name that starts with it: _acme-challenge.* covers _acme-challenge and _acme-challenge.www. Such a token only sees those records, can’t change others, and can’t import zone files.
• Expiry: tokens last 30, 90, 180 or 365 days (90 unless you choose). We let you know when a token is created and 7 days before it expires, and delete it 30 days after.

Records

A record looks like this:

{
  "id": "cmvk…",
  "name": "@",
  "type": "MX",
  "ttl": 3600,
  "data": { "priority": 10, "exchange": "mail.example.com" },
  "value": "10 mail.example.com",
  "etag": "\"mvkmdoup\"",
  "createdAt": "2026-10-23T06:59:36.337Z",
  "updatedAt": "2026-10-23T06:59:36.337Z"
}

• name is relative to the domain: @ for the domain itself, www, _dmarc, or a wildcard like *.dev.
• data holds the fields of the record’s type (see below). Host names may end with a dot or not; we store them without.
• ttl is 1 to 86,400 seconds, 3600 if you leave it out.
• The same rules apply as in the web app: a CNAME stands alone at its name, a DS record needs NS records at its name, no record is there twice, and a domain has at most 1,000 records (unless your account has other limits, see your account page), at most 100 per name and type. The SOA, the domain’s own NS records and DNSSEC records are managed by dns.lgbt.
• A and AAAA records carry proxied: whether their name is served through dns.lgbt’s proxies, with them as the origins. Proxying is switched in the web app; changing the address of a proxied record through the API keeps the name proxied, but an address that can’t be an origin (private, loopback, …) is refused.
• Every record carries managedBy: the dns.lgbt feature that keeps it, or null. Today that is "wkd", the openpgpkey CNAME of a domain whose key directory (WKD) is on. Such a record can’t be changed or deleted (409 conflict) until WKD is switched off in the domain’s Settings, so leave it out when you sync a whole zone.

Changing records safely

• ETags: every record and record set has an ETag. Send it back as If-Match when you change or delete it, and the request fails with precondition_failed if someone changed it in the meantime, in the web app or with another token. If-None-Match: * on a record set only creates it if it doesn’t exist yet.
• Record sets: PUT …/rrsets/www/A makes the records with that name and type exactly the ones you send. Records that stay keep their id. This is the simplest way to set a value.
• Batches: POST …/records:batch makes up to 100 changes all or nothing. The rules are checked against the result, so a batch can, for example, delete an A record and create a CNAME at the same name.

IP sources (dynamic DNS)

An IP source is a named address that changes, for instance the public address of your home connection. Instead of a fixed ipAddress, an A or AAAA record can follow a source: give it data.ipSourceId. When the source’s address changes, every record that follows it changes with it, in every domain. A source is either IPv4 (for A records) or IPv6 (for AAAA records). While it has no address, its records are held back: they aren’t served, and the record answers heldBack: true. You can have up to 50 sources.

Create sources on the IP sources page or with POST /ip-sources (scope ip_sources:write). On the page, “Generate key” gives a source a token of its own that can do nothing but read that source and set its address: give it to your router or a script, not a token of your whole account. Such a key can’t rename, create or delete sources (ip_source_key), and GET /ip-sources only shows it its own source. A token limited to some domains or records can’t have the IP source scopes at all, since a source’s records may be in every domain. On a record, giving data.ipSourceId clears ipAddress and the other way round.

#!/bin/sh
# Sets the IP source to this machine's public IPv4 address. KEY is the
# source's key from the IP sources page, ID its id (shown there, too).
IP=$(curl -sf https://api.ipify.org)
curl -sf -X PATCH "https://dns.lgbt/api/v1/ip-sources/$ID" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"address\":\"$IP\"}"

Sending the same address again is fine (routers do it every few minutes): it only updates lastSetAt. A source with records can’t be deleted (conflict); change or delete the records first. Records that follow a source can be at proxied names and onion services too: the proxies and onion nodes forward to the source’s current address, and while a name has no origin with an address, it isn’t in effect.

Limits

Answers carry RateLimit-Policy and RateLimit headers with what is left (r) and when the window moves on (t, seconds). Past the limit, you get rate_limited with a Retry-After header. Many changes to one domain in a row are published in bursts of a few, then at most every 10 seconds.

Errors

Errors are problem details (application/problem+json) with a stable code to switch on and a detail to show to people. field names the input it is about, and in a batch index names the change.

{
  "type": "https://dns.lgbt/docs/api#errors-conflict",
  "title": "Conflicts with the zone",
  "status": 409,
  "detail": "www already has other records, so it can’t have a CNAME record",
  "code": "conflict",
  "index": 1
}

Endpoints

Record types and their fields

The keys of data for each type. Numbers may also be sent as strings.

Examples

Certificates from Let’s Encrypt with Certbot

The easiest way is certbot’s dns-rfc2136 plugin with the key from your account page, see Certificates with Certbot. With the API instead, create a token with records:read and records:write, limited to _acme-challenge.* and TXT (the token form fills this in for you), and save these two hooks:

#!/bin/sh
# certbot --manual-auth-hook: adds the challenge as a TXT record.
# ZONE is your domain at dns.lgbt, TOKEN a token with records:write.
set -e
NAME="_acme-challenge"
[ "$CERTBOT_DOMAIN" != "$ZONE" ] && NAME="_acme-challenge.${CERTBOT_DOMAIN%.$ZONE}"
curl -sf -X POST "https://dns.lgbt/api/v1/domains/$ZONE/records" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"name\":\"$NAME\",\"type\":\"TXT\",\"ttl\":60,\"data\":{\"text\":\"$CERTBOT_VALIDATION\"}}"
sleep 30

#!/bin/sh
# certbot --manual-cleanup-hook: deletes the challenge again (needs jq).
set -e
NAME="_acme-challenge"
[ "$CERTBOT_DOMAIN" != "$ZONE" ] && NAME="_acme-challenge.${CERTBOT_DOMAIN%.$ZONE}"
for ID in $(curl -sf "https://dns.lgbt/api/v1/domains/$ZONE/records?name=$NAME&type=TXT" \
    -H "Authorization: Bearer $TOKEN" |
    jq -r --arg v "$CERTBOT_VALIDATION" '.records[] | select(.data.text == $v) | .id'); do
  curl -sf -X DELETE "https://dns.lgbt/api/v1/domains/$ZONE/records/$ID" \
    -H "Authorization: Bearer $TOKEN"
done

ZONE=example.com TOKEN=dnslgbt_pat_… certbot certonly --manual \
  --preferred-challenges dns -d example.com -d '*.example.com' \
  --manual-auth-hook ./auth.sh --manual-cleanup-hook ./cleanup.sh

Dynamic DNS

The easiest way is an IP source that your records follow (see above). To set one record directly instead, with a token limited to home and A, run this every few minutes:

#!/bin/sh
# Points home.example.com at this machine's public IPv4 address.
IP=$(curl -sf https://api.ipify.org)
curl -sf -X PUT "https://dns.lgbt/api/v1/domains/example.com/rrsets/home/A" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"ttl\":300,\"records\":[{\"data\":{\"ipAddress\":\"$IP\"}}]}"

Export and import

curl https://dns.lgbt/api/v1/domains/example.com/zone -H "Authorization: Bearer $TOKEN" > example.com.zone

POST …/zone:import with {"zone": "…", "dryRun": true} shows what an import would add without changing anything.

Over Tor

The API is also at our onion service, at http://lgbtdns5pwlmd3owons7dkabgrge7onmisghx42rjoddinndseks6tid.onion/api/v1, with the same tokens, endpoints and limits. Send the requests through a Tor client, e.g. the one of the tor package, which listens on port 9050:

ONION=http://lgbtdns5pwlmd3owons7dkabgrge7onmisghx42rjoddinndseks6tid.onion
curl --socks5-hostname 127.0.0.1:9050 $ONION/api/v1/me \
  -H "Authorization: Bearer dnslgbt_pat_…"
# or
torsocks curl $ONION/api/v1/me -H "Authorization: Bearer dnslgbt_pat_…"

--socks5-hostname lets Tor look up the address; plain --socks5 fails for onion addresses. The address is http on purpose: Tor encrypts the connection all the way to us, and the address itself proves you reached dns.lgbt.

How to check the address, sign up and use the app over Tor: dns.lgbt over Tor.