−50%

50% off your first month on any paid plan · code WELCOME50 · until Nov 30

Start free →

API Overview

API Overview

The WatchCron REST API lets you manage all your monitors — cron jobs, uptime, Cloud Cron, ports, domains, blocklists — plus incidents, status pages, and notification channels. Every action you can take in the dashboard is available through the API.

Base URL

All API endpoints use the following base URL:

Base URL
https://watchcron.com/api/v1

Authentication

Every request must include your API key in the Authorization header as a Bearer token. You can generate API keys in your dashboard under Project Settings → API Keys.

Each API key is scoped to a single project. All resources returned by the API — checks, monitors, incidents, channels — belong to that project only.

Authentication header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://watchcron.com/api/v1/checks
Your API key is shown only once when you create it. Store it securely — WatchCron cannot retrieve it later. If you lose a key, delete it and generate a new one.

Required headers

HeaderValueRequired
AuthorizationBearer YOUR_API_KEYAlways
Content-Typeapplication/jsonPOST / PUT requests
Acceptapplication/jsonRecommended

Rate limits

API requests are rate-limited per API key on a 60-second rolling window. The limit depends on your plan:

PlanRequests / minute
Free100
Starter200
Pro500
Business1,000

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

429 response
HTTP/1.1 429 Too Many Requests
Retry-After: 45

{
  "error": "Rate limit exceeded",
  "retry_after": 45
}

Pagination

Endpoints that return lists use offset-based pagination. Pass per_page (default: 25) and page as query parameters. Every paginated response includes a meta.pagination object:

Pagination meta
{
  "data": [...],
  "meta": {
    "pagination": {
      "total": 87,
      "per_page": 25,
      "current_page": 1,
      "last_page": 4
    }
  }
}

Error responses

The API uses standard HTTP status codes. Error responses include a JSON body with an error field:

StatusMeaningWhen
200OKRequest succeeded
201CreatedResource created successfully
204No ContentResource deleted successfully
401UnauthorizedMissing or invalid API key
404Not FoundResource does not exist or belongs to another project
422Validation ErrorInvalid request body (e.g. bad cron expression)
429Rate LimitedToo many requests — wait and retry
500Server ErrorUnexpected error on our side
Error response example
HTTP/1.1 401 Unauthorized

{
  "error": "Invalid API key"
}

Quick start

Here's a minimal example that creates a check and sends its first ping — the two steps needed to start monitoring a cron job:

Step 1 — Create a check via API
curl -X POST https://watchcron.com/api/v1/checks \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "DB Backup",
       "schedule_type": "cron",
       "cron_expression": "0 3 * * *",
       "grace_seconds": 300
     }'

The response contains the ping_url — add it to the end of your cron job:

Step 2 — Add the ping to your crontab
# crontab -e
0 3 * * *  /usr/local/bin/backup.sh && curl -fsS --retry 3 https://watchcron.com/ping/YOUR-CHECK-UUID

Endpoints overview

Cron Job Monitors — Checks

MethodEndpointDescription
GET/api/v1/checksList all checks
POST/api/v1/checksCreate a check
GET/api/v1/checks/{uuid}Get check details
PUT/api/v1/checks/{uuid}Update a check
DELETE/api/v1/checks/{uuid}Delete a check
PATCH/api/v1/checks/{uuid}/pausePause or unpause
GET/api/v1/checks/{uuid}/pingsList ping history
GET/api/v1/checks/{uuid}/flipsList status changes

HTTP / Uptime Monitors — HTTP Monitors

MethodEndpointDescription
GET/api/v1/http-monitorsList all HTTP monitors
POST/api/v1/http-monitorsCreate an HTTP monitor
GET/api/v1/http-monitors/{uuid}Get monitor details
PUT/api/v1/http-monitors/{uuid}Update a monitor
DELETE/api/v1/http-monitors/{uuid}Delete a monitor
PATCH/api/v1/http-monitors/{uuid}/pausePause or unpause
GET/api/v1/http-monitors/{uuid}/logsList check logs

Cloud Cron Jobs — Cloud Cron

MethodEndpointDescription
GET/api/v1/cloud-cronsList all Cloud Cron jobs
POST/api/v1/cloud-cronsCreate a Cloud Cron job
GET/api/v1/cloud-crons/{uuid}Get job details
PUT/api/v1/cloud-crons/{uuid}Update a job
DELETE/api/v1/cloud-crons/{uuid}Delete a job
PATCH/api/v1/cloud-crons/{uuid}/pausePause or unpause
GET/api/v1/cloud-crons/{uuid}/logsList execution logs

Port / TCP / DNS / ICMP Monitors — Port Monitors

MethodEndpointDescription
GET/api/v1/port-monitorsList all port monitors
POST/api/v1/port-monitorsCreate a port monitor
GET/api/v1/port-monitors/{uuid}Get monitor details
PUT/api/v1/port-monitors/{uuid}Update a monitor
DELETE/api/v1/port-monitors/{uuid}Delete a monitor
PATCH/api/v1/port-monitors/{uuid}/pausePause or unpause
GET/api/v1/port-monitors/{uuid}/logsList check logs

Domain Expiration Monitors — Domain Monitors

MethodEndpointDescription
GET/api/v1/domain-monitorsList all domain monitors
POST/api/v1/domain-monitorsCreate a domain monitor
GET/api/v1/domain-monitors/{uuid}Get monitor details
PUT/api/v1/domain-monitors/{uuid}Update a monitor
DELETE/api/v1/domain-monitors/{uuid}Delete a monitor

Blocklist Monitors — Blocklist Monitors

MethodEndpointDescription
GET/api/v1/blocklist-monitorsList all blocklist monitors
POST/api/v1/blocklist-monitorsCreate a blocklist monitor
GET/api/v1/blocklist-monitors/{uuid}Get monitor details
PUT/api/v1/blocklist-monitors/{uuid}Update a monitor
DELETE/api/v1/blocklist-monitors/{uuid}Delete a monitor
GET/api/v1/blocklist-monitors/{uuid}/logsList scan logs

Incidents — Incidents

MethodEndpointDescription
GET/api/v1/incidentsList all incidents
POST/api/v1/incidentsCreate an incident
GET/api/v1/incidents/{uuid}Get incident details
PUT/api/v1/incidents/{uuid}Update an incident
DELETE/api/v1/incidents/{uuid}Delete an incident

Status Pages — Status Pages read-only

MethodEndpointDescription
GET/api/v1/status-pagesList all status pages
GET/api/v1/status-pages/{slug}Get status page details

Notification Channels — Channels read-only

MethodEndpointDescription
GET/api/v1/channelsList notification channels

Ping endpoints (no auth required)

Ping endpoints are separate from the REST API. They accept both GET and POST requests and do not require authentication — just the check UUID or slug in the URL:

MethodEndpointDescription
ANY/ping/{uuid}Report success
ANY/ping/{uuid}/startSignal job started
ANY/ping/{uuid}/failReport failure
POST/ping/{uuid}/logAttach log output (max 100 KB)
Ping endpoints are designed for high-frequency use and have no rate limits. Use the check UUID or a custom slug as the identifier.

MCP Server (AI agent integration)

WatchCron provides an MCP server (Model Context Protocol) that lets AI assistants manage your monitors through natural language. Instead of writing API calls, your AI agent — Claude, ChatGPT, Cursor, Windsurf, or any MCP-compatible client — can create monitors, check statuses, manage incidents, and more.

Install via npx
npx watchcron-mcp

The MCP server exposes 43 tools covering all 9 API resource types — checks, HTTP monitors, Cloud Cron, port monitors, domain monitors, blocklist monitors, incidents, status pages, and channels. See the MCP Server documentation for setup instructions and the full tool reference.

Versioning

The current API version is v1. The version is included in the URL path. We will not introduce breaking changes within a version. If a new version is released, v1 will continue to work for at least 12 months after the announcement.

Pricing Docs
Log in Start free →