The Herald

What it is

The Herald is where you keep hostname records. Apps look them up with GET /dns-query (JSON). Zipper does not listen on UDP/TCP 53, does not publish nameservers, and does not sign DNSSEC.

Cloudflare analogue: Cloudflare DNS-over-HTTPS JSON (not authoritative :53). SLA 99.9% · p99 12ms. Admins publish records. Viewers may read.

• ▸GET /dns-query
• ▸JSON answers
• ▸Add records with the API
• ▸Not port 53

How it works

Each zone stores Herald records. Zipper answers DNS-JSON at GET /dns-query?name=&type= with Content-Type application/dns-json: Status, TC, RD, RA, AD, CD, Question, Answer.

Proxied A records flatten to 191.215.40.237 so visitors land on Zipper. Unproxied records return the stored address. CNAME is chased inside the zone.

Zipper does not listen on UDP/TCP 53, does not speak RFC 8484 wire format, does not recurse the public internet, and does not sign DNSSEC.

To put a hostname on Zipper without DNS-JSON, point A/AAAA at tinyzipper.com or use /gate/{hostname}/.

Use cases

Concrete ways teams use this service on day one.

Set it up in the dashboard

Dashboard → Services → The Herald. Publish records. Query GET /dns-query?name=www.example.com&type=A.

API

Control-plane: POST /api/v1/herald/records · GET /dns-query?name=&type= (application/dns-json). Send Authorization: Bearer tz_live_YOUR_TOKEN.

Creates count against the plan quota. A 402 plan_limit means you are at the cap — upgrade or delete an unused resource.

curl -sS -X POST https://tinyzipper.com/api/v1/herald/records \
  -H "Authorization: Bearer tz_live_YOUR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","name":"@","content":"191.215.40.237","ttl":300,"proxied":true}'

curl -sS "https://tinyzipper.com/dns-query?name=www.example.com&type=A" -H "Accept: application/dns-json"

const res = await fetch("https://tinyzipper.com/api/v1/herald/records", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ZIPPER_TOKEN}`,
    "Content-Type": "application/json"
  }
});
const json = await res.json();
if (!res.ok) throw new Error(json.error ?? res.statusText);
console.log(json);

Tips

MX and CAA are usually DNS-only. Do not proxy mail.

• ▸DNS-JSON
• ▸Global Server

Runbook

Publish records for GET /dns-query. Zipper does not listen on port 53.