# KarlDNS

> KarlDNS provides anonymous dynamic DNS hostnames for routers and other clients,
> with IPv4 (A) and IPv6 (AAAA) updates through an HTTP API and a private web dashboard.

The public service base URL is `https://karldns.de`. Hostnames are generated under
`karldns.de`; clients cannot choose a custom hostname.
Use HTTPS for this public service. No account login or API key is needed to create
a hostname. Returned private URLs are bearer credentials: save them securely and
never publish them, put them in shared logs, or substitute them into documentation.
Examples below use placeholders, never working credentials.

Create and activate a hostname:

1. Send `POST https://karldns.de/api/v1/hostnames` with no request body. HTTP 201 JSON
   includes `hostname`, `status` (initially `pending`), `dashboard_url`,
   `registration_url`, and `update_url`. Save all three private URLs first.
2. Call the returned `registration_url` using GET or POST, supplying the public
   address as `myip` (IPv4) and/or `myipv6` (IPv6). HTTP 200 `good registered`
   means activation succeeded. For FRITZ!Box, let the router perform registration
   using `?myip=<ipaddr>` so the router supplies its own WAN address.
3. After activation, configure the client with the returned `update_url`.
   FRITZ!Box uses `?myip=<ipaddr>` and optionally `&myipv6=<ip6addr>`.
   Do not send those router placeholders literally from a general HTTP client.

Router requests use `GET` or `POST /api/v1/router/register/{dashboard_secret}`
and `GET` or `POST /api/v1/router/update/{update_slug}`. They accept query
parameters `myip`/`ipaddr` for IPv4 and `myipv6`/`ip6addr` for IPv6. POST also
accepts JSON or URL-encoded bodies with string values. Prefer explicit public
addresses; otherwise source-address detection is used. Never use a health probe
to call these routes: even GET requests can change DNS.

Updates return plain text: `good <address>` means changed, `nochg <address>`
means already current. Invalid IPs return HTTP 400 `badip ...`; DNS-provider
failures return HTTP 500 `911 ...`. Unknown, disabled, or unregistered update
credentials return HTTP 404. Check HTTP status as well as the response body;
back off on HTTP 429 or transient server failures instead of retrying rapidly.

Read status with `GET /api/v1/hostnames/{dashboard_secret}`, using the last
path segment of `dashboard_url`. Optional `history_limit` is 0 through 100
(default 10). The response is JSON and includes lifecycle state and DNS addresses.
Rotate an active hostname's update credential with
`POST /api/v1/hostnames/{dashboard_secret}/rotate-update-url`; save and configure
the returned replacement `update_url` immediately because the old one stops working.
`DELETE /api/v1/hostnames/{dashboard_secret}` removes the hostname and its DNS
records and returns HTTP 204. Delete only when the owner requests it.

On the website, GET `/` displays the homepage; submitting its form creates a
hostname and redirects to the private dashboard. Keep that dashboard URL: it is
the management credential. Dashboard passwords protect only the web dashboard,
not API access using the dashboard secret. Use the API for automation instead of
scraping private pages. Unregistered hostnames are cleaned up automatically.
GET `/healthz` is a read-only health check returning HTTP 200 `ok`.

## API and Website

- [OpenAPI schema](https://karldns.de/openapi.json): Machine-readable request and response definitions.
- [API guide](https://karldns.de/docs): Human-readable API examples and router setup guidance.
- [Homepage](https://karldns.de/): Create a hostname through the browser form.
- [Health](https://karldns.de/healthz): Read-only service availability probe.

## Optional

- [Privacy](https://karldns.de/privacy): Data handling information.
- [Project README](https://raw.githubusercontent.com/StasonJatham/karldns.de/main/README.md): Self-hosting and clients.