Skip to main content

​
ChangeDetection.io REST API

The changedetection.io REST API allows you to programmatically manage web page monitors (watches), tags/groups, and notification settings. All API endpoints require authentication using an API key.

​
Base URL

The API is available at /api/v1/ from your changedetection.io instance:
  • Local development: http://localhost:5000/api/v1
  • Production/hosted: https://yourdomain.com/api/v1
  • Subscription version: https://<your-login-url>/api/v1

​
API Versioning

The current API version is v1. All endpoints are prefixed with /api/v1/.
The API follows semantic versioning. Breaking changes will result in a new API version (v2, v3, etc.).

​
Rate Limits

There are currently no enforced rate limits on API requests. However, please be considerate when making bulk requests:
  • For bulk imports (20+ URLs), the API automatically switches to background processing
  • For bulk rechecks (20+ watches), operations are queued in the background
  • The API will return a 202 status code when background processing is initiated

​
Response Formats

The API returns responses in the following formats:
  • JSON - Most endpoints return JSON (application/json)
  • Plain text - Some endpoints return plain text (text/plain)
  • HTML - Diff endpoints can return HTML (text/html)
  • Binary - Favicon endpoint returns image data

​
Error Handling

The API uses standard HTTP status codes:
Status CodeMeaning
200Success
201Created
202Accepted (background processing)
204No Content (successful deletion)
400Bad Request (validation error)
403Forbidden (invalid API key)
404Not Found
429Too Many Requests (watch limit reached)
500Internal Server Error
Error responses typically include a descriptive message: 
{
  "message": "No watch exists with the UUID of {uuid}"
}
Or as plain text: 
Validation failed: url: Invalid URL format

​
Quick Start Example

Here’s a complete example showing how to authenticate and create a watch: 
# Set your API key
API_KEY="your_api_key_here"

# Create a new watch
curl -X POST "http://localhost:5000/api/v1/watch" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "title": "Example Site Monitor",
    "time_between_check": {
      "hours": 1
    }
  }'

# Response: {"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"}

​
Next Steps

Authentication

Learn how to get and use your API key

Watches

Create and manage web page monitors

Tags

Organize watches with tags and groups

Notifications

Configure notification endpoints

​
OpenAPI Specification

The complete OpenAPI 3.1 specification is available at: 
GET /api/v1/full-spec
This endpoint returns the live, fully-merged specification including all processor plugin schemas. You can use this with Swagger UI or Redoc for interactive API exploration.
No authentication is required to fetch the OpenAPI spec.

Build docs developers (and LLMs) love

Get started for freeTalk to us