API docs by Redocly

ChangeDetection.io API (0.1.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 and python examples to help you get started faster.

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 web page change monitors (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 web page change monitor (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 web page change monitor (watch)

tag
string <= 5000 characters

Tag UUID to associate with this web page change monitor (watch)

tags
Array of strings

Array of tag UUIDs

paused
boolean

Whether the web page change monitor (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 web page change monitor (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 web page change monitor (watch) information and set muted/paused status. Returns the FULL Watch JSON.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Web page change monitor (watch) unique ID

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

Recheck this web page change monitor (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
{
  • "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": [
    ],
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "last_checked": 0,
  • "last_changed": 0,
  • "last_error": "string",
  • "last_viewed": 0
}

Update watch

Update an existing web page change monitor (watch) using JSON. Accepts the same structure as returned in get single watch information.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Web page change monitor (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 web page change monitor (watch)

tag
string <= 5000 characters

Tag UUID to associate with this web page change monitor (watch)

tags
Array of strings

Array of tag UUIDs

paused
boolean

Whether the web page change monitor (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 web page change monitor (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

last_viewed
integer >= 0

Unix timestamp in seconds of the last time the watch was viewed. Setting it to a value higher than last_changed in the "Update watch" endpoint marks the watch as viewed.

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": [
    ],
  • "last_viewed": 0
}

Delete watch

Delete a web page change monitor (watch) and all related history

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Web page change monitor (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 web page change monitor (watch)

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Web page change monitor (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 web page change monitor (watch). Use 'latest' for the most recent snapshot.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Web page change monitor (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 web page change monitor (watch) as displayed in the watch overview list.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Web page change monitor (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": {
    }
}

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 web page change monitors (watches) with this tag

notification_muted
boolean

Whether notifications are muted for this tag

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Get single tag

Retrieve tag information, set notification_muted status, recheck all web page change monitors (watches) 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 web page change monitors (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 web page change monitors (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 web page change monitors (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"

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.

The notification syntax uses https://github.com/caronc/apprise.

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 web page change monitors (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 web page change monitors (watches)

tag
string

Tag name to apply to imported web page change monitors (watches)

proxy
string

Proxy key to use for imported web page change monitors (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"
}