Domain Monitors
Domain Expiration Monitors
Domain expiration monitors track the expiration dates of your domains and warn you before they expire. The API lets you create, list, update, and delete domain monitors programmatically.
List domain monitors
/api/v1/domain-monitors
Returns a paginated list of all domain monitors in the project associated with your API key.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | — | Filter by status (ok, warning, critical, unknown) |
per_page | integer | 25 | Results per page |
page | integer | 1 | Page number |
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/domain-monitors?status=warning&per_page=10"
$response = Http::withToken('YOUR_API_KEY') ->get('https://watchcron.com/api/v1/domain-monitors', [ 'status' => 'warning', 'per_page' => 10, ]); $monitors = $response->json('data');
import requests response = requests.get( "https://watchcron.com/api/v1/domain-monitors", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"status": "warning", "per_page": 10}, ) monitors = response.json()["data"]
const response = await fetch( "https://watchcron.com/api/v1/domain-monitors?status=warning&per_page=10", { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: monitors } = await response.json();
req, _ := http.NewRequest("GET", "https://watchcron.com/api/v1/domain-monitors?status=warning&per_page=10", nil) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 200 OK
{
"data": [
{
"uuid": "e5f6a7b8-c9d0-1234-efab-345678901234",
"domain": "example.com",
"registrar": "Cloudflare, Inc.",
"status": "ok",
"expires_at": "2027-11-15T00:00:00Z",
"days_until_expiry": 385,
"warn_before_days": 30,
"is_active": true,
"last_checked_at": "2026-10-26T08:00:00Z",
"last_error": null,
"created_at": "2026-06-10T12:00:00Z",
"updated_at": "2026-10-26T08:00:00Z"
}
],
"meta": {
"pagination": {
"total": 8,
"per_page": 10,
"current_page": 1,
"last_page": 1
}
}
}
Domain monitor object
Every domain monitor response includes these fields:
| Field | Type | Description |
|---|---|---|
uuid | string | Unique identifier (UUID v4). Used in all API URLs. |
domain | string | The domain name being monitored (e.g. example.com) |
registrar | string|null | Domain registrar name, detected automatically via WHOIS |
status | string | Current status: ok, warning, critical, or unknown |
expires_at | string|null | ISO 8601 expiration date of the domain |
days_until_expiry | integer|null | Number of days remaining until the domain expires |
warn_before_days | integer | Alert threshold — triggers a warning this many days before expiration |
is_active | boolean | Whether monitoring is active |
last_checked_at | string|null | ISO 8601 timestamp of the most recent WHOIS check |
last_error | string|null | Error message from the last failed check, if any |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Status values
| Status | Meaning |
|---|---|
ok | Domain expiration is more than warn_before_days away |
warning | Domain expires within warn_before_days — renewal recommended |
critical | Domain has expired or expires within 7 days |
unknown | WHOIS lookup failed — expiration date could not be determined |
Create a domain monitor
/api/v1/domain-monitors
Request body
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain name to monitor (max 255 characters) |
warn_before_days | integer | No | Days before expiration to trigger warning (1–365, default: 30) |
registrar, expires_at, and days_until_expiry fields are populated automatically.curl -X POST https://watchcron.com/api/v1/domain-monitors \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "warn_before_days": 30 }'
$response = Http::withToken('YOUR_API_KEY') ->post('https://watchcron.com/api/v1/domain-monitors', [ 'domain' => 'example.com', 'warn_before_days' => 30, ]); $monitor = $response->json('data');
import requests response = requests.post( "https://watchcron.com/api/v1/domain-monitors", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "domain": "example.com", "warn_before_days": 30, }, ) monitor = response.json()["data"]
const response = await fetch("https://watchcron.com/api/v1/domain-monitors", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ domain: "example.com", warn_before_days: 30, }), }); const { data: monitor } = await response.json();
body := strings.NewReader(`{ "domain": "example.com", "warn_before_days": 30 }`) req, _ := http.NewRequest("POST", "https://watchcron.com/api/v1/domain-monitors", body) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 201 Created
{
"data": {
"uuid": "e5f6a7b8-c9d0-1234-efab-345678901234",
"domain": "example.com",
"registrar": null,
"status": "unknown",
"expires_at": null,
"days_until_expiry": null,
"warn_before_days": 30,
"is_active": true,
"last_checked_at": null,
"last_error": null,
"created_at": "2026-10-26T10:00:00Z",
"updated_at": "2026-10-26T10:00:00Z"
}
}
Validation errors
If the domain is missing or invalid, the API returns 422:
{
"error": "The domain field is required."
}
Get a domain monitor
/api/v1/domain-monitors/{uuid}
Returns full details for a single domain monitor.
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/domain-monitors/e5f6a7b8-c9d0-1234-efab-345678901234"
$uuid = 'e5f6a7b8-c9d0-1234-efab-345678901234'; $response = Http::withToken('YOUR_API_KEY') ->get("https://watchcron.com/api/v1/domain-monitors/{$uuid}"); $monitor = $response->json('data');
uuid = "e5f6a7b8-c9d0-1234-efab-345678901234" response = requests.get( f"https://watchcron.com/api/v1/domain-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) monitor = response.json()["data"]
const uuid = "e5f6a7b8-c9d0-1234-efab-345678901234"; const response = await fetch( `https://watchcron.com/api/v1/domain-monitors/${uuid}`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: monitor } = await response.json();
Returns the same domain monitor object as shown in Domain monitor object. Returns 404 if the UUID does not exist or belongs to a different project.
Update a domain monitor
/api/v1/domain-monitors/{uuid}
Updates one or more fields on an existing domain monitor. Only include the fields you want to change — all fields are optional.
Request body
| Field | Type | Description |
|---|---|---|
domain | string | Domain name (max 255 characters) |
warn_before_days | integer | Days before expiration to trigger warning (1–365) |
curl -X PUT https://watchcron.com/api/v1/domain-monitors/e5f6a7b8-c9d0-1234-efab-345678901234 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "warn_before_days": 60 }'
$response = Http::withToken('YOUR_API_KEY') ->put("https://watchcron.com/api/v1/domain-monitors/{$uuid}", [ 'warn_before_days' => 60, ]);
response = requests.put( f"https://watchcron.com/api/v1/domain-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "warn_before_days": 60, }, )
const response = await fetch(`https://watchcron.com/api/v1/domain-monitors/${uuid}`, { method: "PUT", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ warn_before_days: 60, }), });
Returns 200 OK with the updated domain monitor object.
Delete a domain monitor
/api/v1/domain-monitors/{uuid}
Permanently deletes a domain monitor.
curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/domain-monitors/e5f6a7b8-c9d0-1234-efab-345678901234"
$response = Http::withToken('YOUR_API_KEY') ->delete("https://watchcron.com/api/v1/domain-monitors/{$uuid}");
response = requests.delete( f"https://watchcron.com/api/v1/domain-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, )
const response = await fetch( `https://watchcron.com/api/v1/domain-monitors/${uuid}`, { method: "DELETE", headers: { "Authorization": "Bearer YOUR_API_KEY" }, } );
Returns 204 No Content on success. This action is irreversible.