API docs by Redocly

ChangeDetection.io API (1.0.0)

Download OpenAPI specification:

URL: https://github.com/dgtlmoon/changedetection.io License: Apache 2.0

ChangeDetection.io Web page monitoring and notifications API

REST API for managing Page watches, Group tags, and Notifications.

changedetection.io can be driven by its built in simple API, in the examples below you will also find curl command line examples to help you.

Where to find my API key?

The API key can be easily found under the SETTINGS then API tab of changedetection.io dashboard.
Simply click the API key to automatically copy it to your clipboard.

Where to find the API key

Connection URL

The API can be found at /api/v1/, so for example if you run changedetection.io locally on port 5000, then URL would be http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091/history.

If you are using the hosted/subscription version of changedetection.io, then the URL is based on your login URL, for example:
https://<your login url>/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091/history

Authentication

Almost all API requests require some authentication, this is provided as an API Key in the header of the HTTP request.

For example: x-api-key: YOUR_API_KEY

Watch Management

Core functionality for managing web page monitors. Create, retrieve, update, and delete individual watches. Each watch represents a single URL being monitored for changes, with configurable settings for check intervals, notification preferences, and content filtering options.

List all watches

Return concise list of available watches and basic info

Authorizations:
ApiKeyAuth
query Parameters
recheck_all
string
Value: "1"

Set to 1 to force recheck of all watches

tag
string

Tag name to filter results

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/watch" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "095be615-a8ad-4c33-8e9c-c7612fbf6c9f": {
    },
  • "7c9e6b8d-f2a1-4e5c-9d3b-8a7f6e4c2d1a": {
    }
}

Create a new watch

Create a single watch. Requires at least 'url' to be set.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri> <= 5000 characters

URL to monitor for changes

title
string <= 5000 characters

Custom title for the watch

tag
string <= 5000 characters

Tag UUID to associate with this watch

tags
Array of strings

Array of tag UUIDs

paused
boolean

Whether the watch is paused

muted
boolean

Whether notifications are muted

method
string
Enum: "GET" "POST" "DELETE" "PUT"

HTTP method to use

fetch_backend
string
Enum: "html_requests" "html_webdriver"

Backend to use for fetching content

object

HTTP headers to include in requests

body
string <= 5000 characters

HTTP request body

proxy
string <= 5000 characters

Proxy configuration

webdriver_delay
integer

Delay in seconds for webdriver

webdriver_js_execute_code
string <= 5000 characters

JavaScript code to execute

object

Time intervals between checks

notification_urls
Array of strings

Notification URLs for this watch

notification_title
string <= 5000 characters

Custom notification title

notification_body
string <= 5000 characters

Custom notification body

notification_format
string
Enum: "Text" "HTML" "Markdown"

Format for notifications

track_ldjson_price_data
boolean

Whether to track JSON-LD price data

Array of objects

Browser automation steps

Responses

Request samples

Content type
application/json
{
  • "url": "https://example.com",
  • "title": "Example Site Monitor",
  • "time_between_check": {
    }
}

Get single watch

Retrieve watch information and set muted/paused status. Returns the FULL Watch JSON.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

query Parameters
recheck
string
Enum: "1" "true"

Recheck this watch

paused
string
Enum: "paused" "unpaused"

Set pause state

muted
string
Enum: "muted" "unmuted"

Set mute state

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "Text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ],
  • "last_checked": 0,
  • "last_changed": 0,
  • "last_error": "string"
}

Update watch

Update an existing watch using JSON. Accepts the same structure as returned in get single watch information.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

Request Body schema: application/json
required
url
required
string <uri> <= 5000 characters

URL to monitor for changes

title
string <= 5000 characters

Custom title for the watch

tag
string <= 5000 characters

Tag UUID to associate with this watch

tags
Array of strings

Array of tag UUIDs

paused
boolean

Whether the watch is paused

muted
boolean

Whether notifications are muted

method
string
Enum: "GET" "POST" "DELETE" "PUT"

HTTP method to use

fetch_backend
string
Enum: "html_requests" "html_webdriver"

Backend to use for fetching content

object

HTTP headers to include in requests

body
string <= 5000 characters

HTTP request body

proxy
string <= 5000 characters

Proxy configuration

webdriver_delay
integer

Delay in seconds for webdriver

webdriver_js_execute_code
string <= 5000 characters

JavaScript code to execute

object

Time intervals between checks

notification_urls
Array of strings

Notification URLs for this watch

notification_title
string <= 5000 characters

Custom notification title

notification_body
string <= 5000 characters

Custom notification body

notification_format
string
Enum: "Text" "HTML" "Markdown"

Format for notifications

track_ldjson_price_data
boolean

Whether to track JSON-LD price data

Array of objects

Browser automation steps

Responses

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "Text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ]
}

Delete watch

Delete a watch and all related history

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

Responses

Request samples 

curl -X DELETE "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" \
  -H "x-api-key: YOUR_API_KEY"

Watch History

Access historical snapshots and change data for your watches. View the complete timeline of detected changes and retrieve specific versions of monitored content for comparison and analysis.

Get watch history

Get a list of all historical snapshots available for a watch

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "1640995200": "/path/to/snapshot1.txt",
  • "1640998800": "/path/to/snapshot2.txt"
}

Snapshots

Retrieve individual snapshots of monitored content. Access both the processed change detection data and the raw HTML content that was captured during monitoring checks.

Get single snapshot

Get single snapshot from watch. Use 'latest' for the most recent snapshot.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

required
integer or string

Snapshot timestamp or 'latest'

query Parameters
html
string
Value: "1"

Set to 1 to return the last HTML

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history/latest" \
  -H "x-api-key: YOUR_API_KEY"

Favicon

Retrieve favicon images associated with monitored web pages. These are used in the dashboard interface to visually identify different watches in your monitoring list.

Get watch favicon

Get the favicon for a watch as displayed in the watch overview list.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/favicon" \
  -H "x-api-key: YOUR_API_KEY" \
  --output favicon.ico

Group / Tag Management

Organize your watches using tags and groups. Tags (also known as Groups) allow you to categorize monitors, set group-wide notification preferences, and perform bulk operations like mass rechecking or status changes across multiple related watches.

List all tags

Return list of available tags/groups

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/tags" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "550e8400-e29b-41d4-a716-446655440000": {
    },
  • "330e8400-e29b-41d4-a716-446655440001": {
    }
}

Get single tag

Retrieve tag information, set notification_muted status, recheck all in tag.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Tag unique ID

query Parameters
muted
string
Enum: "muted" "unmuted"

Set mute state

recheck
string
Value: "true"

Queue all watches with this tag for recheck

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "title": "string",
  • "notification_urls": [
    ],
  • "notification_muted": true
}

Update tag

Update an existing tag using JSON

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Tag unique ID

Request Body schema: application/json
required
title
required
string <= 5000 characters

Tag title

notification_urls
Array of strings

Default notification URLs for watches with this tag

notification_muted
boolean

Whether notifications are muted for this tag

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "notification_urls": [
    ],
  • "notification_muted": true
}

Delete tag

Delete a tag/group and remove it from all watches

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Tag unique ID

Responses

Request samples 

curl -X DELETE "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

Create tag

Create a single tag/group

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
title
required
string <= 5000 characters

Tag title

notification_urls
Array of strings

Default notification URLs for watches with this tag

notification_muted
boolean

Whether notifications are muted for this tag

Responses

Request samples

Content type
application/json
{
  • "title": "Important Sites"
}

Notifications

Configure global notification endpoints that can be used across all your watches. Supports various notification services including email, Discord, Slack, webhooks, and many other popular platforms. These settings serve as defaults that can be overridden at the individual watch or tag level.

Get notification URLs

Return the notification URL list from the configuration

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{}

Add notification URLs

Add one or more notification URLs to the configuration

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
notification_urls
required
Array of strings <uri> [ items <uri > ]

List of notification URLs

Responses

Request samples

Content type
application/json
{
  • "notification_urls": [
    ]
}

Response samples

Content type
application/json
{}

Replace notification URLs

Replace all notification URLs with the provided list (can be empty)

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
notification_urls
required
Array of strings <uri> [ items <uri > ]

List of notification URLs

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete notification URLs

Delete one or more notification URLs from the configuration

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
notification_urls
required
Array of strings <uri> [ items <uri > ]

List of notification URLs

Responses

Request samples

Content type
application/json
{}

Search

Search and filter your watches by URL patterns, titles, or tags. Useful for quickly finding specific monitors in large collections or identifying watches that match certain criteria.

Search watches

Search watches by URL or title text

Authorizations:
ApiKeyAuth
query Parameters
q
required
string

Search query to match against watch URLs and titles

tag
string

Tag name to limit results (name not UUID)

partial
string

Allow partial matching of URL query

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/search?q=example.com" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "watches": {
    }
}

Import

Bulk import multiple URLs for monitoring. Accepts plain text lists of URLs and can automatically apply tags, proxy settings, and other configurations to all imported watches simultaneously.

Import watch URLs

Import a list of URLs to monitor. Accepts line-separated URLs in request body.

Authorizations:
ApiKeyAuth
query Parameters
tag_uuids
string

Tag UUID to apply to imported watches

tag
string

Tag name to apply to imported watches

proxy
string

Proxy key to use for imported watches

dedupe
boolean
Default: true

Remove duplicate URLs (default true)

Request Body schema: text/plain
required
string

Responses

Request samples

Content type
text/plain
https://example.com
https://example.org
https://example.net

Response samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

System Information

Retrieve system status and statistics about your changedetection.io instance, including total watch counts, uptime information, and version details.

Get system information

Return information about the current system state

Authorizations:
ApiKeyAuth

Responses

Request samples 

curl -X GET "http://localhost:5000/api/v1/systeminfo" \
  -H "x-api-key: YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "watch_count": 42,
  • "tag_count": 5,
  • "uptime": "2 days, 3:45:12",
  • "version": "0.50.10"
}