Welcome
Domainwarden has an API which allows you to interact with your account and view, control or update the domains you are monitoring programmatically. Please be aware that you need an active subscription to utilise the Domainwarden API.Authentication
Domainwarden uses token-based authentication. To generate a new token, visit your account settings and add it to theAuthorization header.
Headers
Domainwarden needs two headers when you send requests to us.Scopes
For security, when you generate your API Token you can control what access the token has. We recommend using least-privilege and only choosing the scopes you need for what you want to accomplish.Rate Limits
API requests are rate limited based on your subscription plan to ensure fair usage and system stability. Rate limits are applied per minute and are tracked per API token.Rate Limits by Plan
| Plan | Requests per Minute |
|---|---|
| Basic Access | 1,000 |
| Premium | 5,000 |
| Ultra | 10,000 |
Rate Limit Headers
Every API response includes headers that help you track your rate limit status:| Header | Description |
|---|---|
X-RateLimit-Limit | The maximum number of requests allowed per minute for your plan |
X-RateLimit-Remaining | The number of requests remaining in the current rate limit window |
X-RateLimit-Reset | Unix timestamp indicating when the rate limit window resets |
Handling Rate Limits
When you exceed your rate limit, the API will return a429 Too Many Requests response with a Retry-After header indicating how many seconds you should wait before making another request.
Example rate limit response:
Response Codes
Below you can find the typical response codes when you interact with our API.| Response Code | Explanation |
|---|---|
| 200 | OK - The request was successful, and the server has returned the requested data. |
| 201 | Created - The request was successful, and a new resource was created. |
| 400 | Bad Request - The server could not understand the request due to invalid syntax or missing parameters. |
| 401 | Unauthorized - The request requires authentication, and the client did not provide valid credentials. |
| 402 | Payment Required - The request cannot be processed until the client has an active subscription. |
| 403 | Forbidden - The client is authenticated but does not have the correct permissions. |
| 404 | Not Found - The server cannot find the requested resource. |
| 429 | Too Many Requests - The client has sent too many requests in a given time period. Check the Retry-After header. |
| 500 | Internal Server Error - The server encountered a problem. |