API

The API lets scripts and other tools read and manage your watchlist without the web UI. This deployment is reachable at https://domainhawk.chaops.de (host domainhawk.chaops.de).

Tokens

Create a token under API tokens. Give it a name and a lifetime of 1, 7, 30, 90 or 365 days — or unlimited (never expires). You can create as many tokens as you need. The token is shown exactly once; store it somewhere safe, and deactivate it immediately if it is exposed. Changing your password or email address, or resetting your password, revokes every API token on the account.

Send the token as a bearer token. Session cookies are not accepted.

export DOMAINHAWK_TOKEN='dh_...'

Endpoints

All endpoints are scoped to the token owner. Requests to /api/v1 are rate limited per token (default 120 per minute, configurable with DH_API_RATE_LIMIT).

Endpoint	Purpose
GET /api/v1/me	Identity, watchlist limits and check interval.
GET /api/v1/watchlist	List the watchlist.
POST /api/v1/watchlist	Add {"domain":"example.com","notify":true}; runs a first check.
GET /api/v1/watchlist/{id}	Get one entry.
PATCH /api/v1/watchlist/{id}	Update notify and/or notifyExpiry.
DELETE /api/v1/watchlist/{id}	Remove an entry (204).
POST /api/v1/watchlist/{id}/check	Manual check, once per day per entry.

Examples

curl -H "Authorization: Bearer $DOMAINHAWK_TOKEN" \
  "https://domainhawk.chaops.de/api/v1/watchlist"

curl -X POST -H "Authorization: Bearer $DOMAINHAWK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com","notify":true,"notifyExpiry":true}' \
  "https://domainhawk.chaops.de/api/v1/watchlist"

curl -X PATCH -H "Authorization: Bearer $DOMAINHAWK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"notifyExpiry":false}' \
  "https://domainhawk.chaops.de/api/v1/watchlist/<id>"

curl -X POST -H "Authorization: Bearer $DOMAINHAWK_TOKEN" \
  "https://domainhawk.chaops.de/api/v1/watchlist/<id>/check"

The list response contains items, count and the per-user limit. Items include id, domain, status (pending, available, registered or unknown), notify, notifyExpiry, timestamps, checkCount and the latest detail/error. When the registry publishes them, items also include registeredAt, expiresAt, registrar, domainStatus, nameservers and lastSource. dropState is one of expiring, pending_delete, redemption or empty; it is a convenience signal, not an availability status. notifyExpiry controls the 30/7/1-day expiry reminders and drop-status emails.

Errors

• 400 — malformed JSON or a PATCH without notify/notifyExpiry.
• 401 — missing or invalid token.
• 404 — watchlist entry not found.
• 409 — duplicate domain.
• 422 — invalid domain or watchlist cap.
• 429 — API rate limit, daily-add or manual-check limit; see Retry-After.

Request bodies must be JSON objects of at most 1 MiB; unknown fields are rejected. See the User guide for watchlist limits and statuses.