Skip to content
dns-gate

API by example

The gate's own API lives under /api/v1. It is the same whatever the DNS provider of a zone, and it is what the web UI, the MCP server and the dnsgate Terraform provider use. These pages show each task in several languages; pick yours once, the choice follows you from page to page.

Task Page
Get a token, use an API key, exchange a CI token Authenticate
List zones, read, create, update and delete record sets, plan and apply Zones and records
Adopt existing records, move records to another team Adopt and transfer
Redirect a host to a URL URL forwards
See whether a change is visible on the DNS Propagation check
Search the audit journal Audit journal

Every example runs as is against the Quickstart gate. For your own gate, change the address and how the token is obtained.

Setup used on every page

GATE=http://127.0.0.1:8080
TOKEN=$(curl -fsS "http://127.0.0.1:8090/mint?sub=alice")
auth=(-H "Authorization: Bearer $TOKEN")

Bash or zsh, curl and jq.

$Gate = "http://127.0.0.1:8080"
$Token = Invoke-RestMethod "http://127.0.0.1:8090/mint?sub=alice"
$H = @{ Authorization = "Bearer $Token" }

PowerShell 7 (-ResponseHeadersVariable is used to read ETag).

import requests

GATE = "http://127.0.0.1:8080"
token = requests.get("http://127.0.0.1:8090/mint", params={"sub": "alice"}).text
s = requests.Session()
s.headers["Authorization"] = f"Bearer {token}"

Python 3 with requests.

const GATE = "http://127.0.0.1:8080";
const token = await (await fetch("http://127.0.0.1:8090/mint?sub=alice")).text();
const auth = { Authorization: `Bearer ${token}` };
const json = { ...auth, "Content-Type": "application/json" };

Node.js 18 or later, in an ES module (.mjs) for top-level await.

terraform {
  required_providers {
    dnsgate = { source = "KamorionLabs/dnsgate", version = "~> 0.3" }
  }
}

provider "dnsgate" {
  endpoint = "http://127.0.0.1:8080"
  auth {
    token_command = ["curl", "-fsS", "http://127.0.0.1:8090/mint?sub=alice"]
  }
}

See Terraform for the authentication methods of a real pipeline.

claude mcp add --transport http dns-gate-local http://127.0.0.1:8080/mcp \
  --header "Authorization: Bearer $(curl -fsS 'http://127.0.0.1:8090/mint?sub=alice')"

Claude calls the gate's tools; the examples show what to ask and the tool it uses. See MCP and Claude.

Conventions

  • Hosts are relative to the zone, @ is the apex. Names inside values without a trailing dot are absolute (web.example.net is web.example.net.).
  • Errors are JSON with a stable reason for programs: {"reason": "not_owner", "message": "www CNAME is owned by team api"}. The list is in the API guide.
  • GET /.well-known/dns-gate (no authentication) tells the gate version and its features.

The reference

The API reference documents every operation and schema of the OpenAPI document (api/dns-gate.openapi.yaml), with generated code samples (curl, Python, Node.js, PowerShell, Go).

Try it from the reference

The reference can send requests: choose Your gate (or Quickstart gate) under Server and paste a token under Authentication. The token stays in the browser tab unless you tick Remember tokens in this browser.

Cross-origin requests

The requests go from your browser, on kamorionlabs.github.io, to your gate. The gate does not send CORS headers, so browsers block those calls today: copy the generated sample to a terminal instead.