docs/api_v1/index.html
ChangeDetection.io Web page monitoring and notifications API
Watch Management
Watch History
Snapshots
Favicon
Group / Tag Management
Notifications
Search
Import
System Information
Plugin API Extensions
Download OpenAPI specification:
URL: https://github.com/dgtlmoon/changedetection.io License: Apache 2.0
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.
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.
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
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
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.
Return concise list of available web page change monitors (watches) and basic info
ApiKeyAuth
| recheck_all |
string
Value: "1"
Set to 1 to force recheck of all watches
| | tag |
string
Tag name to filter results
|
200
List of watches
get/watch
Development server
http://localhost:5000/api/v1/watch
Production server
https://yourdomain.com/api/v1/watch
Custom server
{protocol}://{host}/api/v1/watch
Copy
curl-X GET"http://localhost:5000/api/v1/watch"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/json
Copy Expand all Collapse all
`{
"095be615-a8ad-4c33-8e9c-c7612fbf6c9f": {
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"url": "http://example.com?id={{1+1}} - the raw URL",
"link": "http://example.com?id=2 - the rendered URL, always use this for listing.",
"title": "Example Website Monitor - manually entered title/description",
"page_title": "The HTML <title> from the page",
"tags": ["550e8400-e29b-41d4-a716-446655440000" ],
"paused": false,
"notification_muted": false,
"method": "GET",
"fetch_backend": "html_requests",
"last_checked": 1640995200,
"last_changed": 1640995200
},
"7c9e6b8d-f2a1-4e5c-9d3b-8a7f6e4c2d1a": {
"uuid": "7c9e6b8d-f2a1-4e5c-9d3b-8a7f6e4c2d1a",
"url": "http://example.com?id={{1+1}} - the raw URL",
"link": "http://example.com?id=2 - the rendered URL, always use this for listing.",
"title": "News Site Tracker - manually entered title/description",
"page_title": "The HTML <title> from the page",
"tags": ["330e8400-e29b-41d4-a716-446655440001" ],
"paused": false,
"notification_muted": true,
"method": "GET",
"fetch_backend": "html_webdriver",
"last_checked": 1640998800,
"last_changed": 1640995200
}
}`
Create a single web page change monitor (watch). Requires at least url to be set.
Every watch can be configured with:
processor field (restock_diff or text_json_diff - default)notification_urls (array), notification_title, notification_body, notification_format, notification_mutedtag (UUID string) or tags (array of UUIDs)time_between_check, paused, method, fetch_backendheaders, body, proxy, browser_steps, and moreApiKeyAuth
| url required |
string <uri> <= 5000 characters
URL to monitor for changes
| | title |
string or null <= 5000 characters
Custom title for the web page change monitor (watch), not to be confused with page_title
| | 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
| | notification_muted |
boolean
Whether notifications are muted
| | method |
string
Enum: "GET" "POST" "DELETE" "PUT"
HTTP method to use
| | fetch_backend |
string^(system|html_requests|html_webdriver|extra_b...Show pattern
Default: "system"
Backend to use for fetching content. Common values:
system (default) - Use the system-wide default fetcherhtml_requests - Fast requests-based fetcherhtml_webdriver - Browser-based fetcher (Playwright/Puppeteer)extra_browser_* - Custom browser configurations (if configured)| | headers |
object
HTTP headers to include in requests
| | body |
string or null <= 5000 characters
HTTP request body
| | proxy |
string or null <= 5000 characters
Proxy configuration
| | ignore_status_codes |
boolean or null
Ignore HTTP status code errors (boolean or null)
| | webdriver_delay |
integer or null
Delay in seconds for webdriver
| | webdriver_js_execute_code |
string or null <= 5000 characters
JavaScript code to execute
| | time_between_check |
object
Time intervals between checks. All fields must be non-negative. At least one non-zero value required when not using default settings.
| | time_between_check_use_default |
boolean
Default: true
Whether to use global settings for time between checks - defaults to true if not set
| | notification_urls |
Array of strings <= 100 items [items <= 1000 characters]
Notification URLs for this web page change monitor (watch). Maximum 100 URLs.
| | notification_title |
string or null <= 5000 characters
Custom notification title
| | notification_body |
string or null <= 5000 characters
Custom notification body
| | notification_format |
string
Enum: "text" "html" "htmlcolor" "markdown" "System default"
Format for notifications
| | track_ldjson_price_data |
boolean or null
Whether to track JSON-LD price data
| | browser_steps |
Array of objects <= 100 items
Browser automation steps. Maximum 100 steps allowed.
| | processor |
string
Default: "text_json_diff"
Enum: "restock_diff" "text_json_diff"
Optional processor mode to use for change detection. Defaults to text_json_diff if not specified.
| | include_filters |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to extract specific content from the page
| | subtractive_selectors |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to remove content from the page
| | ignore_text |
Array of strings <= 100 items [items <= 5000 characters]
Text patterns to ignore in change detection
| | trigger_text |
Array of strings <= 100 items [items <= 5000 characters]
Text/regex patterns that must be present to trigger a change
| | text_should_not_be_present |
Array of strings <= 100 items [items <= 5000 characters]
Text that should NOT be present (triggers alert if found)
| | extract_lines_containing |
Array of strings <= 100 items [items <= 5000 characters]
Keep only lines containing these substrings (plain text, case-insensitive) — simpler alternative to regex
| | extract_text |
Array of strings <= 100 items [items <= 5000 characters]
Regex patterns to extract specific text after filtering
| | trim_text_whitespace |
boolean
Default: false
Strip leading/trailing whitespace from text
| | sort_text_alphabetically |
boolean
Default: false
Sort lines alphabetically before comparison
| | remove_duplicate_lines |
boolean
Default: false
Remove duplicate lines from content
| | check_unique_lines |
boolean
Default: false
Compare against all history for unique lines
| | strip_ignored_lines |
boolean or null
Remove lines matching ignore patterns
| | filter_text_added |
boolean
Default: true
Include added text in change detection
| | filter_text_removed |
boolean
Default: true
Include removed text in change detection
| | filter_text_replaced |
boolean
Default: true
Include replaced text in change detection
| | in_stock_only |
boolean
Default: true
Only trigger on in-stock transitions (restock_diff processor)
| | follow_price_changes |
boolean
Default: true
Monitor and track price changes (restock_diff processor)
| | price_change_threshold_percent |
number or null
Minimum price change percentage to trigger notification
| | notification_screenshot |
boolean
Default: false
Include screenshot in notifications (if supported by notification URL)
| | filter_failure_notification_send |
boolean
Default: true
Send notification when filters fail to match content
| | use_page_title_in_list |
boolean or null
Display page title in watch list (null = use system default)
| | history_snapshot_max_length |
integer or null [1 .. 1000]
Maximum number of history snapshots to keep (null = use system default)
| | time_schedule_limit |
object
Weekly schedule limiting when checks can run
| | conditions |
Array of objects <= 100 items
Array of condition rules for change detection logic (empty array when not set)
| | conditions_match_logic |
string
Default: "ALL"
Enum: "ALL" "ANY"
Logic operator - ALL (match all conditions) or ANY (match any condition)
|
200
Web page change monitor (watch) created successfully
500
Server error
post/watch
Development server
http://localhost:5000/api/v1/watch
Production server
https://yourdomain.com/api/v1/watch
Custom server
{protocol}://{host}/api/v1/watch
Content type application/json
Copy Expand all Collapse all
`{
"url": "https://example.com",
"title": "Example Site Monitor",
"time_between_check": { "hours": 1
}
}`
Retrieve web page change monitor (watch) information and set muted/paused status. Returns the FULL Watch JSON.
ApiKeyAuth
| uuid required |
string <uuid>
Web page change monitor (watch) unique ID
|
| 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
|
200
Watch information or operation result
404
Web page change monitor (watch) not found
get/watch/{uuid}
Development server
http://localhost:5000/api/v1/watch/{uuid}
Production server
https://yourdomain.com/api/v1/watch/{uuid}
Custom server
{protocol}://{host}/api/v1/watch/{uuid}
Copy
curl-X GET"http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/jsontext/plainapplication/json
Copy Expand all Collapse all
`{
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"date_created": 0,
"url": "http://example.com",
"title": "string",
"tag": "string",
"tags": ["string" ],
"paused": true,
"notification_muted": true,
"method": "GET",
"fetch_backend": "system",
"headers": {
"property1": "string",
"property2": "string"
},
"body": "string",
"proxy": "string",
"ignore_status_codes": true,
"webdriver_delay": 0,
"webdriver_js_execute_code": "string",
"time_between_check": {
"weeks": 52000,
"days": 365000,
"hours": 8760000,
"minutes": 525600000,
"seconds": 31536000000
},
"time_between_check_use_default": true,
"notification_urls": ["string" ],
"notification_title": "string",
"notification_body": "string",
"notification_format": "text",
"track_ldjson_price_data": true,
"browser_steps": [ {
"operation": "string",
"selector": "string",
"optional_value": "string"
}
],
"processor": "restock_diff",
"include_filters": ["string" ],
"subtractive_selectors": ["string" ],
"ignore_text": ["string" ],
"trigger_text": ["string" ],
"text_should_not_be_present": ["string" ],
"extract_lines_containing": ["string" ],
"extract_text": ["string" ],
"trim_text_whitespace": false,
"sort_text_alphabetically": false,
"remove_duplicate_lines": false,
"check_unique_lines": false,
"strip_ignored_lines": true,
"filter_text_added": true,
"filter_text_removed": true,
"filter_text_replaced": true,
"in_stock_only": true,
"follow_price_changes": true,
"price_change_threshold_percent": 0,
"has_ldjson_price_data": true,
"notification_screenshot": false,
"filter_failure_notification_send": true,
"use_page_title_in_list": true,
"history_snapshot_max_length": 1,
"time_schedule_limit": {
"enabled": false,
"monday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"tuesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"wednesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"thursday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"friday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"saturday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"sunday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
}
},
"conditions": [ {
"field": "string",
"operator": "string",
"value": "string"
}
],
"conditions_match_logic": "ALL",
"last_checked": 0,
"last_changed": 0,
"last_error": "string",
"last_viewed": 0,
"link": "string",
"page_title": "string",
"check_count": 0,
"fetch_time": 0,
"previous_md5": "string",
"previous_md5_before_filters": "string",
"consecutive_filter_failures": 0,
"last_notification_error": "string",
"notification_alert_count": 0,
"content-type": "string",
"remote_server_reply": "string",
"browser_steps_last_error_step": 0,
"viewed": 0,
"history_n": 0
}`
Update an existing web page change monitor (watch) using JSON. Accepts the same structure as returned in get single watch information.
ApiKeyAuth
| uuid required |
string <uuid>
Web page change monitor (watch) unique ID
|
| url |
string <uri> <= 5000 characters
URL to monitor for changes
| | title |
string or null <= 5000 characters
Custom title for the web page change monitor (watch), not to be confused with page_title
| | 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
| | notification_muted |
boolean
Whether notifications are muted
| | method |
string
Enum: "GET" "POST" "DELETE" "PUT"
HTTP method to use
| | fetch_backend |
string^(system|html_requests|html_webdriver|extra_b...Show pattern
Default: "system"
Backend to use for fetching content. Common values:
system (default) - Use the system-wide default fetcherhtml_requests - Fast requests-based fetcherhtml_webdriver - Browser-based fetcher (Playwright/Puppeteer)extra_browser_* - Custom browser configurations (if configured)| | headers |
object
HTTP headers to include in requests
| | body |
string or null <= 5000 characters
HTTP request body
| | proxy |
string or null <= 5000 characters
Proxy configuration
| | ignore_status_codes |
boolean or null
Ignore HTTP status code errors (boolean or null)
| | webdriver_delay |
integer or null
Delay in seconds for webdriver
| | webdriver_js_execute_code |
string or null <= 5000 characters
JavaScript code to execute
| | time_between_check |
object
Time intervals between checks. All fields must be non-negative. At least one non-zero value required when not using default settings.
| | time_between_check_use_default |
boolean
Default: true
Whether to use global settings for time between checks - defaults to true if not set
| | notification_urls |
Array of strings <= 100 items [items <= 1000 characters]
Notification URLs for this web page change monitor (watch). Maximum 100 URLs.
| | notification_title |
string or null <= 5000 characters
Custom notification title
| | notification_body |
string or null <= 5000 characters
Custom notification body
| | notification_format |
string
Enum: "text" "html" "htmlcolor" "markdown" "System default"
Format for notifications
| | track_ldjson_price_data |
boolean or null
Whether to track JSON-LD price data
| | browser_steps |
Array of objects <= 100 items
Browser automation steps. Maximum 100 steps allowed.
| | processor |
string
Default: "text_json_diff"
Enum: "restock_diff" "text_json_diff"
Optional processor mode to use for change detection. Defaults to text_json_diff if not specified.
| | include_filters |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to extract specific content from the page
| | subtractive_selectors |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to remove content from the page
| | ignore_text |
Array of strings <= 100 items [items <= 5000 characters]
Text patterns to ignore in change detection
| | trigger_text |
Array of strings <= 100 items [items <= 5000 characters]
Text/regex patterns that must be present to trigger a change
| | text_should_not_be_present |
Array of strings <= 100 items [items <= 5000 characters]
Text that should NOT be present (triggers alert if found)
| | extract_lines_containing |
Array of strings <= 100 items [items <= 5000 characters]
Keep only lines containing these substrings (plain text, case-insensitive) — simpler alternative to regex
| | extract_text |
Array of strings <= 100 items [items <= 5000 characters]
Regex patterns to extract specific text after filtering
| | trim_text_whitespace |
boolean
Default: false
Strip leading/trailing whitespace from text
| | sort_text_alphabetically |
boolean
Default: false
Sort lines alphabetically before comparison
| | remove_duplicate_lines |
boolean
Default: false
Remove duplicate lines from content
| | check_unique_lines |
boolean
Default: false
Compare against all history for unique lines
| | strip_ignored_lines |
boolean or null
Remove lines matching ignore patterns
| | filter_text_added |
boolean
Default: true
Include added text in change detection
| | filter_text_removed |
boolean
Default: true
Include removed text in change detection
| | filter_text_replaced |
boolean
Default: true
Include replaced text in change detection
| | in_stock_only |
boolean
Default: true
Only trigger on in-stock transitions (restock_diff processor)
| | follow_price_changes |
boolean
Default: true
Monitor and track price changes (restock_diff processor)
| | price_change_threshold_percent |
number or null
Minimum price change percentage to trigger notification
| | notification_screenshot |
boolean
Default: false
Include screenshot in notifications (if supported by notification URL)
| | filter_failure_notification_send |
boolean
Default: true
Send notification when filters fail to match content
| | use_page_title_in_list |
boolean or null
Display page title in watch list (null = use system default)
| | history_snapshot_max_length |
integer or null [1 .. 1000]
Maximum number of history snapshots to keep (null = use system default)
| | time_schedule_limit |
object
Weekly schedule limiting when checks can run
| | conditions |
Array of objects <= 100 items
Array of condition rules for change detection logic (empty array when not set)
| | conditions_match_logic |
string
Default: "ALL"
Enum: "ALL" "ANY"
Logic operator - ALL (match all conditions) or ANY (match any condition)
| | 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.
|
200
Web page change monitor (watch) updated successfully
500
Server error
put/watch/{uuid}
Development server
http://localhost:5000/api/v1/watch/{uuid}
Production server
https://yourdomain.com/api/v1/watch/{uuid}
Custom server
{protocol}://{host}/api/v1/watch/{uuid}
Content type application/json
Copy Expand all Collapse all
`{
"url": "http://example.com",
"title": "string",
"tag": "string",
"tags": ["string" ],
"paused": true,
"notification_muted": true,
"method": "GET",
"fetch_backend": "system",
"headers": {
"property1": "string",
"property2": "string"
},
"body": "string",
"proxy": "string",
"ignore_status_codes": true,
"webdriver_delay": 0,
"webdriver_js_execute_code": "string",
"time_between_check": {
"weeks": 52000,
"days": 365000,
"hours": 8760000,
"minutes": 525600000,
"seconds": 31536000000
},
"time_between_check_use_default": true,
"notification_urls": ["string" ],
"notification_title": "string",
"notification_body": "string",
"notification_format": "text",
"track_ldjson_price_data": true,
"browser_steps": [ {
"operation": "string",
"selector": "string",
"optional_value": "string"
}
],
"processor": "restock_diff",
"include_filters": ["string" ],
"subtractive_selectors": ["string" ],
"ignore_text": ["string" ],
"trigger_text": ["string" ],
"text_should_not_be_present": ["string" ],
"extract_lines_containing": ["string" ],
"extract_text": ["string" ],
"trim_text_whitespace": false,
"sort_text_alphabetically": false,
"remove_duplicate_lines": false,
"check_unique_lines": false,
"strip_ignored_lines": true,
"filter_text_added": true,
"filter_text_removed": true,
"filter_text_replaced": true,
"in_stock_only": true,
"follow_price_changes": true,
"price_change_threshold_percent": 0,
"notification_screenshot": false,
"filter_failure_notification_send": true,
"use_page_title_in_list": true,
"history_snapshot_max_length": 1,
"time_schedule_limit": {
"enabled": false,
"monday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"tuesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"wednesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"thursday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"friday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"saturday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"sunday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
}
},
"conditions": [ {
"field": "string",
"operator": "string",
"value": "string"
}
],
"conditions_match_logic": "ALL",
"last_viewed": 0
}`
Delete a web page change monitor (watch) and all related history
ApiKeyAuth
| uuid required |
string <uuid>
Web page change monitor (watch) unique ID
|
200
Web page change monitor (watch) deleted successfully
delete/watch/{uuid}
Development server
http://localhost:5000/api/v1/watch/{uuid}
Production server
https://yourdomain.com/api/v1/watch/{uuid}
Custom server
{protocol}://{host}/api/v1/watch/{uuid}
Copy
curl-X DELETE"http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f"\-H"x-api-key: YOUR\_API\_KEY"
Get a list of timestamps of all changes detected for a watch.
Get a list of all historical snapshots available for a web page change monitor (watch), use the key timestamp as the query argument for fetching a single watch history snapshot.
ApiKeyAuth
| uuid required |
string <uuid>
Web page change monitor (watch) unique ID
|
200
List of available snapshots
404
Web page change monitor (watch) not found
get/watch/{uuid}/history
Development server
http://localhost:5000/api/v1/watch/{uuid}/history
Production server
https://yourdomain.com/api/v1/watch/{uuid}/history
Custom server
{protocol}://{host}/api/v1/watch/{uuid}/history
Copy
curl-X GET"http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/json
Copy
`{
"1640995200": "/path/to/snapshot1.txt",
"1640998800": "/path/to/snapshot2.txt"
}`
Generate a difference (comparison) between two historical snapshots of a web page change monitor (watch).
This endpoint compares content between two points in time and returns the differences in your chosen format. Perfect for reviewing what changed between specific versions or comparing recent changes.
Timestamp Keywords:
'latest' for the most recent snapshot (to_timestamp)'previous' for the second-most-recent snapshot (from_timestamp)Format Options:
text (default): Plain text with (removed) and (added) prefixeshtml: HTML format with (removed) and (added) texthtmlcolor: Rich HTML with colored highlights (green for additions, red for deletions)Word-Level Diffing:
word_diff=true for detailed inline comparisonsword_diff=false for line-level comparisons only (default false/off, line-level mode by default)Raw Diff Output:
no_markup=true to get raw diff content without any formatting appliedApiKeyAuth
| uuid required |
string <uuid>
Web page change monitor (watch) unique ID
| | from_timestamp required |
integer or string
Example: previous
Starting snapshot timestamp, 'previous' for second-most-recent, or specific Unix timestamp
| | to_timestamp required |
integer or string
Example: latest
Ending snapshot timestamp, 'latest' for most recent, or specific Unix timestamp
|
| format |
string
Default: "text"
Enum: "text" "html" "htmlcolor" "markdown"
Output format for the diff:
text (default): Plain text with (removed) and (added) prefixeshtml: Basic HTML formathtmlcolor: Rich HTML with colored backgrounds (red for deletions, green for additions)markdown: Markdown format with HTML rendering| | word_diff |
string
Default: "false"
Enum: "true" "false" "1" "0" "yes" "no" "on" "off"
Enable word-level diffing for more granular comparisons. When enabled, changes are highlighted at the word level rather than line level. Default is false (line-level mode). Accepts: true, false, 1, 0, yes, no, on, off
| | no_markup |
string
Default: "false"
Enum: "true" "false" "1" "0" "yes" "no" "on" "off"
When set to true, returns the raw diff content without any markup formatting. The content will include placeholders for opening/closing tags of the changes, allowing you to implement your own custom colorisation or formatting. This skips all HTML color application and service tweaks. Accepts: true, false, 1, 0, yes, no, on, off
| | type |
string
Default: "diffLines"
Enum: "diffLines" "diffWords"
Diff granularity type:
diffLines (default): Line-level comparison, showing which lines changeddiffWords: Word-level comparison, showing which words changed within linesThis parameter is an alternative to word_diff for better alignment with the UI. If both are specified, type=diffWords will enable word-level diffing.
| | changesOnly |
string
Default: "true"
Enum: "true" "false" "1" "0" "yes" "no" "on" "off"
When enabled, only show lines/content that changed (no surrounding context). When disabled, include unchanged lines for context around changes. Accepts: true, false, 1, 0, yes, no, on, off
| | ignoreWhitespace |
string
Default: "false"
Enum: "true" "false" "1" "0" "yes" "no" "on" "off"
When enabled, ignore whitespace-only changes (spaces, tabs, newlines). Useful for focusing on content changes and ignoring formatting differences. Accepts: true, false, 1, 0, yes, no, on, off
| | removed |
string
Default: "true"
Enum: "true" "false" "1" "0" "yes" "no" "on" "off"
Include removed/deleted content in the diff output. When disabled, content that was deleted will not appear in the diff. Accepts: true, false, 1, 0, yes, no, on, off
| | added |
string
Default: "true"
Enum: "true" "false" "1" "0" "yes" "no" "on" "off"
Include added/new content in the diff output. When disabled, content that was added will not appear in the diff. Accepts: true, false, 1, 0, yes, no, on, off
| | replaced |
string
Default: "true"
Enum: "true" "false" "1" "0" "yes" "no" "on" "off"
Include replaced/modified content in the diff output. When disabled, content that was modified (changed from one value to another) will not appear in the diff. Accepts: true, false, 1, 0, yes, no, on, off
|
200
Formatted diff between the two snapshots
400
Invalid format parameter or invalid request
404
Watch not found, timestamps not found, or insufficient history
get/watch/{uuid}/difference/{from_timestamp}/{to_timestamp}
Development server
http://localhost:5000/api/v1/watch/{uuid}/difference/{from\_timestamp}/{to\_timestamp}
Production server
https://yourdomain.com/api/v1/watch/{uuid}/difference/{from\_timestamp}/{to\_timestamp}
Custom server
{protocol}://{host}/api/v1/watch/{uuid}/difference/{from_timestamp}/{to_timestamp}
Copy
# Compare previous snapshot to latest with colored HTML
curl-X GET"http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/difference/previous/latest?format=htmlcolor"\-H"x-api-key: YOUR\_API\_KEY"# Compare two specific timestampsinplain text with word-level diff
curl-X GET"http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/difference/1640995200/1640998800?format=text&word\_diff=true"\-H"x-api-key: YOUR\_API\_KEY"# Show only additions(hide removed/replaced content),ignore whitespace
curl-X GET"http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/difference/previous/latest?format=htmlcolor&removed=false&replaced=false&ignoreWhitespace=true"\-H"x-api-key: YOUR\_API\_KEY"
Retrieve individual text snapshot of monitored content according to the timestamp. The text snapshot is the HTML to Text at page check time.
Set the query argument html to any value to retrieve the last HTML fetched, the system only keeps the last two (2) HTML files fetched.
Use the Watch History API endpoint to get a list of timestamps to pass to this query.
Get single snapshot from web page change monitor (watch). Use 'latest' for the most recent snapshot. Use the Watch History API to get a list of timestamps to pass.
ApiKeyAuth
| uuid required |
string <uuid>
Web page change monitor (watch) unique ID
| | timestamp required |
integer or string
Snapshot timestamp or 'latest'
|
| html |
string
Value: "1"
Set to 1 to return the last HTML
|
200
Snapshot content
404
Snapshot not found
get/watch/{uuid}/history/{timestamp}
Development server
http://localhost:5000/api/v1/watch/{uuid}/history/{timestamp}
Production server
https://yourdomain.com/api/v1/watch/{uuid}/history/{timestamp}
Custom server
{protocol}://{host}/api/v1/watch/{uuid}/history/{timestamp}
Copy
curl-X GET"http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history/latest"\-H"x-api-key: YOUR\_API\_KEY"
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 the favicon for a web page change monitor (watch) as displayed in the watch overview list.
ApiKeyAuth
| uuid required |
string <uuid>
Web page change monitor (watch) unique ID
|
200
Favicon binary data
404
Favicon not found
get/watch/{uuid}/favicon
Development server
http://localhost:5000/api/v1/watch/{uuid}/favicon
Production server
https://yourdomain.com/api/v1/watch/{uuid}/favicon
Custom server
{protocol}://{host}/api/v1/watch/{uuid}/favicon
Copy
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
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.
Return list of available tags/groups
ApiKeyAuth
200
List of tags
get/tags
Development server
http://localhost:5000/api/v1/tags
Production server
https://yourdomain.com/api/v1/tags
Custom server
{protocol}://{host}/api/v1/tags
Copy
curl-X GET"http://localhost:5000/api/v1/tags"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/json
Copy Expand all Collapse all
`{
"550e8400-e29b-41d4-a716-446655440000": {
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"title": "Production Sites",
"notification_urls": ["mailto:[email protected]" ],
"notification_muted": false
},
"330e8400-e29b-41d4-a716-446655440001": {
"uuid": "330e8400-e29b-41d4-a716-446655440001",
"title": "News Sources",
"notification_urls": ["discord://webhook_id/webhook_token" ],
"notification_muted": false
}
}`
Create a single tag/group
ApiKeyAuth
| url |
string <uri> <= 5000 characters
URL to monitor for changes
| | title required |
string or null <= 5000 characters
Custom title for the web page change monitor (watch), not to be confused with page_title
| | 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
| | notification_muted |
boolean
Whether notifications are muted
| | method |
string
Enum: "GET" "POST" "DELETE" "PUT"
HTTP method to use
| | fetch_backend |
string^(system|html_requests|html_webdriver|extra_b...Show pattern
Default: "system"
Backend to use for fetching content. Common values:
system (default) - Use the system-wide default fetcherhtml_requests - Fast requests-based fetcherhtml_webdriver - Browser-based fetcher (Playwright/Puppeteer)extra_browser_* - Custom browser configurations (if configured)| | headers |
object
HTTP headers to include in requests
| | body |
string or null <= 5000 characters
HTTP request body
| | proxy |
string or null <= 5000 characters
Proxy configuration
| | ignore_status_codes |
boolean or null
Ignore HTTP status code errors (boolean or null)
| | webdriver_delay |
integer or null
Delay in seconds for webdriver
| | webdriver_js_execute_code |
string or null <= 5000 characters
JavaScript code to execute
| | time_between_check |
object
Time intervals between checks. All fields must be non-negative. At least one non-zero value required when not using default settings.
| | time_between_check_use_default |
boolean
Default: true
Whether to use global settings for time between checks - defaults to true if not set
| | notification_urls |
Array of strings <= 100 items [items <= 1000 characters]
Notification URLs for this web page change monitor (watch). Maximum 100 URLs.
| | notification_title |
string or null <= 5000 characters
Custom notification title
| | notification_body |
string or null <= 5000 characters
Custom notification body
| | notification_format |
string
Enum: "text" "html" "htmlcolor" "markdown" "System default"
Format for notifications
| | track_ldjson_price_data |
boolean or null
Whether to track JSON-LD price data
| | browser_steps |
Array of objects <= 100 items
Browser automation steps. Maximum 100 steps allowed.
| | processor |
string
Default: "text_json_diff"
Enum: "restock_diff" "text_json_diff"
Optional processor mode to use for change detection. Defaults to text_json_diff if not specified.
| | include_filters |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to extract specific content from the page
| | subtractive_selectors |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to remove content from the page
| | ignore_text |
Array of strings <= 100 items [items <= 5000 characters]
Text patterns to ignore in change detection
| | trigger_text |
Array of strings <= 100 items [items <= 5000 characters]
Text/regex patterns that must be present to trigger a change
| | text_should_not_be_present |
Array of strings <= 100 items [items <= 5000 characters]
Text that should NOT be present (triggers alert if found)
| | extract_lines_containing |
Array of strings <= 100 items [items <= 5000 characters]
Keep only lines containing these substrings (plain text, case-insensitive) — simpler alternative to regex
| | extract_text |
Array of strings <= 100 items [items <= 5000 characters]
Regex patterns to extract specific text after filtering
| | trim_text_whitespace |
boolean
Default: false
Strip leading/trailing whitespace from text
| | sort_text_alphabetically |
boolean
Default: false
Sort lines alphabetically before comparison
| | remove_duplicate_lines |
boolean
Default: false
Remove duplicate lines from content
| | check_unique_lines |
boolean
Default: false
Compare against all history for unique lines
| | strip_ignored_lines |
boolean or null
Remove lines matching ignore patterns
| | filter_text_added |
boolean
Default: true
Include added text in change detection
| | filter_text_removed |
boolean
Default: true
Include removed text in change detection
| | filter_text_replaced |
boolean
Default: true
Include replaced text in change detection
| | in_stock_only |
boolean
Default: true
Only trigger on in-stock transitions (restock_diff processor)
| | follow_price_changes |
boolean
Default: true
Monitor and track price changes (restock_diff processor)
| | price_change_threshold_percent |
number or null
Minimum price change percentage to trigger notification
| | notification_screenshot |
boolean
Default: false
Include screenshot in notifications (if supported by notification URL)
| | filter_failure_notification_send |
boolean
Default: true
Send notification when filters fail to match content
| | use_page_title_in_list |
boolean or null
Display page title in watch list (null = use system default)
| | history_snapshot_max_length |
integer or null [1 .. 1000]
Maximum number of history snapshots to keep (null = use system default)
| | time_schedule_limit |
object
Weekly schedule limiting when checks can run
| | conditions |
Array of objects <= 100 items
Array of condition rules for change detection logic (empty array when not set)
| | conditions_match_logic |
string
Default: "ALL"
Enum: "ALL" "ANY"
Logic operator - ALL (match all conditions) or ANY (match any condition)
| | overrides_watch |
boolean or null
Whether this tag's settings override watch settings for all watches in this tag/group.
| | url_match_pattern |
string
Automatically apply this tag to any watch whose URL matches this pattern. Supports fnmatch wildcards (* and ?): e.g. ://example.com/ or github.com/myorg. Plain strings are matched as case-insensitive substrings. Leave empty to disable auto-matching.
|
201
Tag created successfully
400
Invalid or unsupported tag
post/tag
Development server
http://localhost:5000/api/v1/tag
Production server
https://yourdomain.com/api/v1/tag
Custom server
{protocol}://{host}/api/v1/tag
Content type application/json
Copy
`{ "title": "Important Sites"
}`
Content type application/json
Copy
`{ "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}`
Retrieve tag information, set notification_muted status, recheck all web page change monitors (watches) in tag.
ApiKeyAuth
| uuid required |
string <uuid>
Tag unique ID
|
| muted |
string
Enum: "muted" "unmuted"
Set mute state
| | recheck |
string
Value: "true"
Queue all web page change monitors (watches) with this tag for recheck
|
200
Tag information or operation result
404
Tag not found
get/tag/{uuid}
Development server
http://localhost:5000/api/v1/tag/{uuid}
Production server
https://yourdomain.com/api/v1/tag/{uuid}
Custom server
{protocol}://{host}/api/v1/tag/{uuid}
Copy
curl-X GET"http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/jsontext/plainapplication/json
Copy Expand all Collapse all
`{
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"date_created": 0,
"url": "http://example.com",
"title": "string",
"tag": "string",
"tags": ["string" ],
"paused": true,
"notification_muted": true,
"method": "GET",
"fetch_backend": "system",
"headers": {
"property1": "string",
"property2": "string"
},
"body": "string",
"proxy": "string",
"ignore_status_codes": true,
"webdriver_delay": 0,
"webdriver_js_execute_code": "string",
"time_between_check": {
"weeks": 52000,
"days": 365000,
"hours": 8760000,
"minutes": 525600000,
"seconds": 31536000000
},
"time_between_check_use_default": true,
"notification_urls": ["string" ],
"notification_title": "string",
"notification_body": "string",
"notification_format": "text",
"track_ldjson_price_data": true,
"browser_steps": [ {
"operation": "string",
"selector": "string",
"optional_value": "string"
}
],
"processor": "restock_diff",
"include_filters": ["string" ],
"subtractive_selectors": ["string" ],
"ignore_text": ["string" ],
"trigger_text": ["string" ],
"text_should_not_be_present": ["string" ],
"extract_lines_containing": ["string" ],
"extract_text": ["string" ],
"trim_text_whitespace": false,
"sort_text_alphabetically": false,
"remove_duplicate_lines": false,
"check_unique_lines": false,
"strip_ignored_lines": true,
"filter_text_added": true,
"filter_text_removed": true,
"filter_text_replaced": true,
"in_stock_only": true,
"follow_price_changes": true,
"price_change_threshold_percent": 0,
"has_ldjson_price_data": true,
"notification_screenshot": false,
"filter_failure_notification_send": true,
"use_page_title_in_list": true,
"history_snapshot_max_length": 1,
"time_schedule_limit": {
"enabled": false,
"monday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"tuesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"wednesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"thursday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"friday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"saturday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"sunday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
}
},
"conditions": [ {
"field": "string",
"operator": "string",
"value": "string"
}
],
"conditions_match_logic": "ALL",
"overrides_watch": true,
"url_match_pattern": "string"
}`
Update an existing tag using JSON
ApiKeyAuth
| uuid required |
string <uuid>
Tag unique ID
|
| url |
string <uri> <= 5000 characters
URL to monitor for changes
| | title |
string or null <= 5000 characters
Custom title for the web page change monitor (watch), not to be confused with page_title
| | 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
| | notification_muted |
boolean
Whether notifications are muted
| | method |
string
Enum: "GET" "POST" "DELETE" "PUT"
HTTP method to use
| | fetch_backend |
string^(system|html_requests|html_webdriver|extra_b...Show pattern
Default: "system"
Backend to use for fetching content. Common values:
system (default) - Use the system-wide default fetcherhtml_requests - Fast requests-based fetcherhtml_webdriver - Browser-based fetcher (Playwright/Puppeteer)extra_browser_* - Custom browser configurations (if configured)| | headers |
object
HTTP headers to include in requests
| | body |
string or null <= 5000 characters
HTTP request body
| | proxy |
string or null <= 5000 characters
Proxy configuration
| | ignore_status_codes |
boolean or null
Ignore HTTP status code errors (boolean or null)
| | webdriver_delay |
integer or null
Delay in seconds for webdriver
| | webdriver_js_execute_code |
string or null <= 5000 characters
JavaScript code to execute
| | time_between_check |
object
Time intervals between checks. All fields must be non-negative. At least one non-zero value required when not using default settings.
| | time_between_check_use_default |
boolean
Default: true
Whether to use global settings for time between checks - defaults to true if not set
| | notification_urls |
Array of strings <= 100 items [items <= 1000 characters]
Notification URLs for this web page change monitor (watch). Maximum 100 URLs.
| | notification_title |
string or null <= 5000 characters
Custom notification title
| | notification_body |
string or null <= 5000 characters
Custom notification body
| | notification_format |
string
Enum: "text" "html" "htmlcolor" "markdown" "System default"
Format for notifications
| | track_ldjson_price_data |
boolean or null
Whether to track JSON-LD price data
| | browser_steps |
Array of objects <= 100 items
Browser automation steps. Maximum 100 steps allowed.
| | processor |
string
Default: "text_json_diff"
Enum: "restock_diff" "text_json_diff"
Optional processor mode to use for change detection. Defaults to text_json_diff if not specified.
| | include_filters |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to extract specific content from the page
| | subtractive_selectors |
Array of strings <= 100 items [items <= 5000 characters]
CSS/XPath selectors to remove content from the page
| | ignore_text |
Array of strings <= 100 items [items <= 5000 characters]
Text patterns to ignore in change detection
| | trigger_text |
Array of strings <= 100 items [items <= 5000 characters]
Text/regex patterns that must be present to trigger a change
| | text_should_not_be_present |
Array of strings <= 100 items [items <= 5000 characters]
Text that should NOT be present (triggers alert if found)
| | extract_lines_containing |
Array of strings <= 100 items [items <= 5000 characters]
Keep only lines containing these substrings (plain text, case-insensitive) — simpler alternative to regex
| | extract_text |
Array of strings <= 100 items [items <= 5000 characters]
Regex patterns to extract specific text after filtering
| | trim_text_whitespace |
boolean
Default: false
Strip leading/trailing whitespace from text
| | sort_text_alphabetically |
boolean
Default: false
Sort lines alphabetically before comparison
| | remove_duplicate_lines |
boolean
Default: false
Remove duplicate lines from content
| | check_unique_lines |
boolean
Default: false
Compare against all history for unique lines
| | strip_ignored_lines |
boolean or null
Remove lines matching ignore patterns
| | filter_text_added |
boolean
Default: true
Include added text in change detection
| | filter_text_removed |
boolean
Default: true
Include removed text in change detection
| | filter_text_replaced |
boolean
Default: true
Include replaced text in change detection
| | in_stock_only |
boolean
Default: true
Only trigger on in-stock transitions (restock_diff processor)
| | follow_price_changes |
boolean
Default: true
Monitor and track price changes (restock_diff processor)
| | price_change_threshold_percent |
number or null
Minimum price change percentage to trigger notification
| | notification_screenshot |
boolean
Default: false
Include screenshot in notifications (if supported by notification URL)
| | filter_failure_notification_send |
boolean
Default: true
Send notification when filters fail to match content
| | use_page_title_in_list |
boolean or null
Display page title in watch list (null = use system default)
| | history_snapshot_max_length |
integer or null [1 .. 1000]
Maximum number of history snapshots to keep (null = use system default)
| | time_schedule_limit |
object
Weekly schedule limiting when checks can run
| | conditions |
Array of objects <= 100 items
Array of condition rules for change detection logic (empty array when not set)
| | conditions_match_logic |
string
Default: "ALL"
Enum: "ALL" "ANY"
Logic operator - ALL (match all conditions) or ANY (match any condition)
| | overrides_watch |
boolean or null
Whether this tag's settings override watch settings for all watches in this tag/group.
| | url_match_pattern |
string
Automatically apply this tag to any watch whose URL matches this pattern. Supports fnmatch wildcards (* and ?): e.g. ://example.com/ or github.com/myorg. Plain strings are matched as case-insensitive substrings. Leave empty to disable auto-matching.
|
200
Tag updated successfully
500
Server error
put/tag/{uuid}
Development server
http://localhost:5000/api/v1/tag/{uuid}
Production server
https://yourdomain.com/api/v1/tag/{uuid}
Custom server
{protocol}://{host}/api/v1/tag/{uuid}
Content type application/json
Copy Expand all Collapse all
`{
"url": "http://example.com",
"title": "string",
"tag": "string",
"tags": ["string" ],
"paused": true,
"notification_muted": true,
"method": "GET",
"fetch_backend": "system",
"headers": {
"property1": "string",
"property2": "string"
},
"body": "string",
"proxy": "string",
"ignore_status_codes": true,
"webdriver_delay": 0,
"webdriver_js_execute_code": "string",
"time_between_check": {
"weeks": 52000,
"days": 365000,
"hours": 8760000,
"minutes": 525600000,
"seconds": 31536000000
},
"time_between_check_use_default": true,
"notification_urls": ["string" ],
"notification_title": "string",
"notification_body": "string",
"notification_format": "text",
"track_ldjson_price_data": true,
"browser_steps": [ {
"operation": "string",
"selector": "string",
"optional_value": "string"
}
],
"processor": "restock_diff",
"include_filters": ["string" ],
"subtractive_selectors": ["string" ],
"ignore_text": ["string" ],
"trigger_text": ["string" ],
"text_should_not_be_present": ["string" ],
"extract_lines_containing": ["string" ],
"extract_text": ["string" ],
"trim_text_whitespace": false,
"sort_text_alphabetically": false,
"remove_duplicate_lines": false,
"check_unique_lines": false,
"strip_ignored_lines": true,
"filter_text_added": true,
"filter_text_removed": true,
"filter_text_replaced": true,
"in_stock_only": true,
"follow_price_changes": true,
"price_change_threshold_percent": 0,
"notification_screenshot": false,
"filter_failure_notification_send": true,
"use_page_title_in_list": true,
"history_snapshot_max_length": 1,
"time_schedule_limit": {
"enabled": false,
"monday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"tuesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"wednesday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"thursday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"friday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"saturday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
},
"sunday": {
"enabled": true,
"start_time": "00:00",
"duration": {
"hours": "24",
"minutes": "00"
}
}
},
"conditions": [ {
"field": "string",
"operator": "string",
"value": "string"
}
],
"conditions_match_logic": "ALL",
"overrides_watch": true,
"url_match_pattern": "string"
}`
Delete a tag/group and remove it from all web page change monitors (watches)
ApiKeyAuth
| uuid required |
string <uuid>
Tag unique ID
|
200
Tag deleted successfully
delete/tag/{uuid}
Development server
http://localhost:5000/api/v1/tag/{uuid}
Production server
https://yourdomain.com/api/v1/tag/{uuid}
Custom server
{protocol}://{host}/api/v1/tag/{uuid}
Copy
curl-X DELETE"http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000"\-H"x-api-key: YOUR\_API\_KEY"
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.
Return the notification URL list from the configuration
ApiKeyAuth
200
List of notification URLs
get/notifications
Development server
http://localhost:5000/api/v1/notifications
Production server
https://yourdomain.com/api/v1/notifications
Custom server
{protocol}://{host}/api/v1/notifications
Copy
curl-X GET"http://localhost:5000/api/v1/notifications"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/json
Copy Expand all Collapse all
`{ "notification_urls": [ "http://example.com"
]
}`
Add one or more notification URLs to the configuration
ApiKeyAuth
| notification_urls required |
Array of strings <uri> [items <uri >]
List of notification URLs
|
201
Notification URLs added successfully
400
Invalid input
post/notifications
Development server
http://localhost:5000/api/v1/notifications
Production server
https://yourdomain.com/api/v1/notifications
Custom server
{protocol}://{host}/api/v1/notifications
Content type application/json
Copy Expand all Collapse all
`{ "notification_urls": [
"mailto:[email protected]", "discord://webhook_id/webhook_token"
]
}`
Content type application/json
Copy Expand all Collapse all
`{ "notification_urls": [ "http://example.com"
]
}`
Replace all notification URLs with the provided list (can be empty)
ApiKeyAuth
| notification_urls required |
Array of strings <uri> [items <uri >]
List of notification URLs
|
200
Notification URLs replaced successfully
400
Invalid input
put/notifications
Development server
http://localhost:5000/api/v1/notifications
Production server
https://yourdomain.com/api/v1/notifications
Custom server
{protocol}://{host}/api/v1/notifications
Content type application/json
Copy Expand all Collapse all
`{ "notification_urls": [ "http://example.com"
]
}`
Content type application/json
Copy Expand all Collapse all
`{ "notification_urls": [ "http://example.com"
]
}`
Delete one or more notification URLs from the configuration
ApiKeyAuth
| notification_urls required |
Array of strings <uri> [items <uri >]
List of notification URLs
|
204
Notification URLs deleted successfully
400
No matching notification URLs found
delete/notifications
Development server
http://localhost:5000/api/v1/notifications
Production server
https://yourdomain.com/api/v1/notifications
Custom server
{protocol}://{host}/api/v1/notifications
Content type application/json
Copy Expand all Collapse all
`{ "notification_urls": [ "http://example.com"
]
}`
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 web page change monitors (watches) by URL or title text
ApiKeyAuth
| 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
|
200
Search results
get/search
Development server
http://localhost:5000/api/v1/search
Production server
https://yourdomain.com/api/v1/search
Custom server
{protocol}://{host}/api/v1/search
Copy
curl-X GET"http://localhost:5000/api/v1/search?q=example.com"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/json
Copy Expand all Collapse all
`{ "watches": { "095be615-a8ad-4c33-8e9c-c7612fbf6c9f": {
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"url": "http://example.com",
"title": "Example Website Monitor",
"tags": ["550e8400-e29b-41d4-a716-446655440000" ],
"paused": false,
"notification_muted": false
}
}
}`
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 a list of URLs to monitor with optional watch configuration. Accepts line-separated URLs in request body.
Configuration via Query Parameters:
You can pass ANY watch configuration field as query parameters to apply settings to all imported watches. All parameters from the Watch schema are supported (processor, fetch_backend, notification_urls, etc.).
Special Parameters:
tag / tag_uuids - Assign tags to imported watchesproxy - Use specific proxy for imported watchesdedupe - Skip duplicate URLs (default: true)Type Conversion:
true, false, 1, 0, yes, no[item1,item2]){"key":"value"})ApiKeyAuth
| tag_uuids |
string
Example: tag_uuids=550e8400-e29b-41d4-a716-446655440000
Tag UUID(s) to apply to imported watches (comma-separated for multiple)
| | tag |
string
Example: tag=production
Tag name to apply to imported watches
| | proxy |
string
Example: proxy=proxy1
Proxy key to use for imported watches
| | dedupe |
boolean
Default: true
Skip duplicate URLs (default true)
|
string
200
URLs imported successfully
500
Server error
post/import
Development server
http://localhost:5000/api/v1/import
Production server
https://yourdomain.com/api/v1/import
Custom server
{protocol}://{host}/api/v1/import
Content type text/plain
Copy
https://example.com
https://example.org
https://example.net
Content type application/json
Copy
["497f6eca-6276-4993-bfeb-53cbbbba6f08" ]
Retrieve system status and statistics about your changedetection.io instance, including total watch counts, uptime information, and version details.
Return information about the current system state
ApiKeyAuth
200
System information
get/systeminfo
Development server
http://localhost:5000/api/v1/systeminfo
Production server
https://yourdomain.com/api/v1/systeminfo
Custom server
{protocol}://{host}/api/v1/systeminfo
Copy
curl-X GET"http://localhost:5000/api/v1/systeminfo"\-H"x-api-key: YOUR\_API\_KEY"
Content type application/json
Copy
`{
"watch_count": 42,
"tag_count": 5,
"uptime": "2 days, 3:45:12",
"version": "0.50.10"
}`
changedetection.io uses a processor plugin system to handle different types of change detection. Each processor lives in changedetectionio/processors/<name>/ and may include an api.yaml file that extends the core Watch schema with processor-specific configuration fields.
At startup, changedetection.io scans all installed processors for an api.yaml file. Any schemas and code samples defined there are deep-merged into the live API specification, making the processor's configuration fields valid on all watch create and update requests.
The live, fully-merged spec is always available at /api/v1/full-spec — use that URL with Swagger UI or Redoc to see the complete schema for your specific installation.
api.yamlPlace an api.yaml in the processor plugin's own directory, alongside its __init__.py (e.g. changedetectionio/processors/my_processor/api.yaml). The schema name must follow the convention processor_config_<processor_name> (e.g. processor_config_restock_diff). That same key is used as the JSON field name when creating or updating a watch.
A minimal api.yaml for a hypothetical my_processor:
components:
schemas:
processor_config_my_processor:
type: object
description: Configuration for my_processor
properties:
some_option:
type: boolean
default: true
description: Enable some behaviour
paths:
/watch:
post:
x-code-samples:
- lang: curl
label: my_processor example
source: |
curl -X POST "http://localhost:5000/api/v1/watch" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"processor": "my_processor",
"processor_config_my_processor": { "some_option": true }
}'
The paths section in api.yaml is used only for injecting additional x-code-samples into existing endpoints — you cannot define new routes via plugin.
restock_diffThe restock_diff processor is always shipped with changedetection.io. It monitors product availability and price changes using structured data (JSON-LD / schema.org microdata) and text heuristics. It is activated by setting "processor": "restock_diff" on a watch.
It adds the processor_config_restock_diff block to the Watch schema with these fields:
| Field | Type | Default | Description |
|---|---|---|---|
in_stock_processing | string | in_stock_only | in_stock_only — only alert Out-of-Stock→In-Stock · all_changes — alert any availability change · off — disable stock tracking |
follow_price_changes | boolean | true | Monitor and alert on price changes |
price_change_min | number | null | — |
price_change_max | number | null | — |
price_change_threshold_percent | number | null | — |
curl -X POST "http://localhost:5000/api/v1/watch" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/product/widget",
"processor": "restock_diff",
"processor_config_restock_diff": {
"in_stock_processing": "in_stock_only",
"follow_price_changes": true,
"price_change_threshold_percent": 5
}
}'
The response JSON includes processor_config_restock_diff alongside all standard watch fields:
curl -X GET "http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091" \
-H "x-api-key: YOUR_API_KEY"
{
"uuid": "cc0cfffa-f449-477b-83ea-0caafd1dc091",
"url": "https://example.com/product/widget",
"processor": "restock_diff",
"processor_config_restock_diff": {
"in_stock_processing": "in_stock_only",
"follow_price_changes": true,
"price_change_threshold_percent": 5,
"price_change_min": null,
"price_change_max": null
}
}
Only fields included in the request body are updated; omitted fields are left unchanged.
curl -X PUT "http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"processor_config_restock_diff": {
"in_stock_processing": "all_changes",
"follow_price_changes": true,
"price_change_min": 10.00,
"price_change_max": 500.00
}
}'
curl -X DELETE "http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091" \
-H "x-api-key: YOUR_API_KEY"
For the complete schema-validated documentation including all processor fields, fetch the live spec and load it into Swagger UI or Redoc:
GET /api/v1/full-spec
Return the fully merged OpenAPI specification for this instance.
Unlike the static api-spec.yaml shipped with the application, this endpoint returns the spec dynamically merged with any api.yaml schemas provided by installed processor plugins.
Use this URL with Swagger UI or Redoc to get schema-accurate documentation for your specific install — it includes every processor_config_<name> schema block contributed by installed processors (e.g. processor_config_restock_diff from the built-in restock plugin).
This endpoint requires no authentication and returns YAML.
To load it directly in Swagger UI, paste the URL into the "Explore" box:
http://localhost:5000/api/v1/full-spec
200
Merged OpenAPI specification in YAML format. Includes all processor plugin schemas (e.g. processor_config_restock_diff) not present in the static api-spec.yaml.
get/full-spec
Development server
http://localhost:5000/api/v1/full-spec
Production server
https://yourdomain.com/api/v1/full-spec
Custom server
{protocol}://{host}/api/v1/full-spec
Copy
# Fetch the live merged spec(no API key needed)curl-X GET"http://localhost:5000/api/v1/full-spec"