Getting Started with the REST API

The Domainyze REST API gives your scripts and systems the same view of your account as the dashboard: your watchlist and portfolio, each domain's stage, forecast and DNS, your alert history, and the actions to add, configure, pause, move, group, remove and re-check domains.

The API is included on the Business plan. On other plans, requests are refused with the code plan_required. If you want an AI assistant rather than your own code to read your account, the MCP server is available on Pro too.

1. Create a token

Go to Settings → API & MCP, give the token a name you will recognise later (for example "Reporting script"), tick only the scopes it needs, choose how long it lasts, and choose Create token.

The token is shown once. Copy it into your secret store straight away; Domainyze keeps only an identifier to revoke it by and cannot show it again. Managing API tokens covers scopes, expiry and revoking.

2. Make your first request

Every request goes to https://domainyze.com/api/v1 and carries the token in the Authorization header:

curl https://domainyze.com/api/v1/me \
  -H "Authorization: Bearer $DOMAINYZE_TOKEN"

The answer describes your account: plan, how many domains you can still add, how many lookups (scans and domain tools) remain today, and the scopes this token holds. If it answers 401, the token is missing, mistyped, expired or revoked.

Never put the token in a URL or query string. The API reads it only from the header.

3. Explore the reference

The full reference, with every field, parameter and example response, is at developers.domainyze.com. It is generated from the API itself, so it is always current, and you can try requests from the page with your own token.

What you can do

How requests work

• Address a domain by its full name, such as example.co.uk. A name you do not monitor answers 404, exactly as one that does not exist, so the API never reveals what other accounts watch.
• Batch endpoints take a domains list of up to 100 names. If any of them is not yours, the request answers 404 with those names in details.domains and changes nothing.
• Adding is per name. POST /domains returns the names it added and, separately, the ones it could not add with a reason (for example already_monitoring). If your plan's domain limit leaves no room for any of them, it answers 403 limit_reached.
• Lists are paginated. Pass page and per_page (15, 30, 50 or 100); the response's meta carries the totals.
• Checks are queued. POST /domains/{domain}/check answers 202 straight away; read the result later with GET /domains/{domain}. Check requests share one budget with the dashboard's Check now button.
• Settings follow your plan. A setting your plan does not include is refused with a message saying so (validation_failed naming the field, or plan_required), the same rule as in the dashboard.

Errors and limits

Every error has the same JSON shape with a stable code to switch on. You can make 60 requests a minute. The codes, the limits and what to do about each are in API and MCP limits and errors.