mirror of
https://github.com/dgtlmoon/changedetection.io.git
synced 2026-02-14 16:37:36 -06:00
1908 lines
67 KiB
YAML
1908 lines
67 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: ChangeDetection.io API
|
|
description: |
|
|
# 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.
|
|
|
|
|
|
|
|
## 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`
|
|
|
|
version: 0.1.6
|
|
contact:
|
|
name: ChangeDetection.io
|
|
url: https://github.com/dgtlmoon/changedetection.io
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://www.apache.org/licenses/LICENSE-2.0.html
|
|
|
|
servers:
|
|
- url: http://localhost:5000/api/v1
|
|
description: Development server
|
|
- url: https://yourdomain.com/api/v1
|
|
description: Production server
|
|
- url: '{protocol}://{host}/api/v1'
|
|
description: Custom server
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: https
|
|
host:
|
|
default: yourdomain.com
|
|
description: Your changedetection.io host
|
|
|
|
security:
|
|
- ApiKeyAuth: []
|
|
|
|
tags:
|
|
- name: Watch Management
|
|
description: |
|
|
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.
|
|
|
|
- name: Watch History
|
|
description: |
|
|
Get a list of timestamps of all changes detected for a watch.
|
|
|
|
- name: Snapshots
|
|
description: |
|
|
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.
|
|
|
|
- name: Favicon
|
|
description: |
|
|
Retrieve favicon images associated with monitored web pages. These are used in the dashboard interface
|
|
to visually identify different watches in your monitoring list.
|
|
|
|
- name: Group / Tag Management
|
|
description: |
|
|
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.
|
|
|
|
- name: Notifications
|
|
description: |
|
|
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](https://github.com/caronc/apprise).
|
|
|
|
- name: Search
|
|
description: |
|
|
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.
|
|
|
|
- name: Import
|
|
description: |
|
|
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.
|
|
|
|
- name: System Information
|
|
description: |
|
|
Retrieve system status and statistics about your changedetection.io instance, including total watch
|
|
counts, uptime information, and version details.
|
|
|
|
components:
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: x-api-key
|
|
description: |
|
|
API key for authentication. You can find your API key in the changedetection.io dashboard under Settings > API.
|
|
|
|
Enter your API key in the "Authorize" button above to automatically populate all code examples.
|
|
|
|
schemas:
|
|
WatchBase:
|
|
type: object
|
|
properties:
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
description: Unique identifier
|
|
readOnly: true
|
|
date_created:
|
|
type: [integer, 'null']
|
|
description: Unix timestamp of creation
|
|
readOnly: true
|
|
url:
|
|
type: string
|
|
format: uri
|
|
description: URL to monitor for changes
|
|
maxLength: 5000
|
|
title:
|
|
type: [string, 'null']
|
|
description: Custom title for the web page change monitor (watch), not to be confused with page_title
|
|
maxLength: 5000
|
|
tag:
|
|
type: string
|
|
description: Tag UUID to associate with this web page change monitor (watch)
|
|
maxLength: 5000
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of tag UUIDs
|
|
paused:
|
|
type: boolean
|
|
description: Whether the web page change monitor (watch) is paused
|
|
notification_muted:
|
|
type: boolean
|
|
description: Whether notifications are muted
|
|
method:
|
|
type: string
|
|
enum: [GET, POST, DELETE, PUT]
|
|
description: HTTP method to use
|
|
fetch_backend:
|
|
type: string
|
|
description: |
|
|
Backend to use for fetching content. Common values:
|
|
- `system` (default) - Use the system-wide default fetcher
|
|
- `html_requests` - Fast requests-based fetcher
|
|
- `html_webdriver` - Browser-based fetcher (Playwright/Puppeteer)
|
|
- `extra_browser_*` - Custom browser configurations (if configured)
|
|
- Plugin-provided fetchers (if installed)
|
|
pattern: '^(system|html_requests|html_webdriver|extra_browser_.+)$'
|
|
default: system
|
|
headers:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: HTTP headers to include in requests
|
|
body:
|
|
type: [string, 'null']
|
|
description: HTTP request body
|
|
maxLength: 5000
|
|
proxy:
|
|
type: [string, 'null']
|
|
description: Proxy configuration
|
|
maxLength: 5000
|
|
ignore_status_codes:
|
|
type: [boolean, 'null']
|
|
description: Ignore HTTP status code errors (boolean or null)
|
|
webdriver_delay:
|
|
type: [integer, 'null']
|
|
description: Delay in seconds for webdriver
|
|
webdriver_js_execute_code:
|
|
type: [string, 'null']
|
|
description: JavaScript code to execute
|
|
maxLength: 5000
|
|
time_between_check:
|
|
type: object
|
|
properties:
|
|
weeks:
|
|
type: [integer, 'null']
|
|
minimum: 0
|
|
maximum: 52000
|
|
days:
|
|
type: [integer, 'null']
|
|
minimum: 0
|
|
maximum: 365000
|
|
hours:
|
|
type: [integer, 'null']
|
|
minimum: 0
|
|
maximum: 8760000
|
|
minutes:
|
|
type: [integer, 'null']
|
|
minimum: 0
|
|
maximum: 525600000
|
|
seconds:
|
|
type: [integer, 'null']
|
|
minimum: 0
|
|
maximum: 31536000000
|
|
description: 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:
|
|
type: boolean
|
|
default: true
|
|
description: Whether to use global settings for time between checks - defaults to true if not set
|
|
notification_urls:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 1000
|
|
maxItems: 100
|
|
description: Notification URLs for this web page change monitor (watch). Maximum 100 URLs.
|
|
notification_title:
|
|
type: [string, 'null']
|
|
description: Custom notification title
|
|
maxLength: 5000
|
|
notification_body:
|
|
type: [string, 'null']
|
|
description: Custom notification body
|
|
maxLength: 5000
|
|
notification_format:
|
|
type: string
|
|
enum: ['text', 'html', 'htmlcolor', 'markdown', 'System default']
|
|
description: Format for notifications
|
|
track_ldjson_price_data:
|
|
type: [boolean, 'null']
|
|
description: Whether to track JSON-LD price data
|
|
browser_steps:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
operation:
|
|
type: [string, 'null']
|
|
maxLength: 5000
|
|
selector:
|
|
type: [string, 'null']
|
|
maxLength: 5000
|
|
optional_value:
|
|
type: [string, 'null']
|
|
maxLength: 5000
|
|
required: [operation, selector, optional_value]
|
|
additionalProperties: false
|
|
maxItems: 100
|
|
description: Browser automation steps. Maximum 100 steps allowed.
|
|
processor:
|
|
type: string
|
|
enum: [restock_diff, text_json_diff]
|
|
default: text_json_diff
|
|
description: Optional processor mode to use for change detection. Defaults to `text_json_diff` if not specified.
|
|
|
|
# Content Filtering
|
|
include_filters:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 5000
|
|
maxItems: 100
|
|
description: CSS/XPath selectors to extract specific content from the page
|
|
subtractive_selectors:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 5000
|
|
maxItems: 100
|
|
description: CSS/XPath selectors to remove content from the page
|
|
ignore_text:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 5000
|
|
maxItems: 100
|
|
description: Text patterns to ignore in change detection
|
|
trigger_text:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 5000
|
|
maxItems: 100
|
|
description: Text/regex patterns that must be present to trigger a change
|
|
text_should_not_be_present:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 5000
|
|
maxItems: 100
|
|
description: Text that should NOT be present (triggers alert if found)
|
|
extract_text:
|
|
type: array
|
|
items:
|
|
type: string
|
|
maxLength: 5000
|
|
maxItems: 100
|
|
description: Regex patterns to extract specific text after filtering
|
|
|
|
# Text Processing
|
|
trim_text_whitespace:
|
|
type: boolean
|
|
default: false
|
|
description: Strip leading/trailing whitespace from text
|
|
sort_text_alphabetically:
|
|
type: boolean
|
|
default: false
|
|
description: Sort lines alphabetically before comparison
|
|
remove_duplicate_lines:
|
|
type: boolean
|
|
default: false
|
|
description: Remove duplicate lines from content
|
|
check_unique_lines:
|
|
type: boolean
|
|
default: false
|
|
description: Compare against all history for unique lines
|
|
strip_ignored_lines:
|
|
type: [boolean, 'null']
|
|
description: Remove lines matching ignore patterns
|
|
|
|
# Change Detection Filters
|
|
filter_text_added:
|
|
type: boolean
|
|
default: true
|
|
description: Include added text in change detection
|
|
filter_text_removed:
|
|
type: boolean
|
|
default: true
|
|
description: Include removed text in change detection
|
|
filter_text_replaced:
|
|
type: boolean
|
|
default: true
|
|
description: Include replaced text in change detection
|
|
|
|
# Restock/Price Detection
|
|
in_stock_only:
|
|
type: boolean
|
|
default: true
|
|
description: Only trigger on in-stock transitions (restock_diff processor)
|
|
follow_price_changes:
|
|
type: boolean
|
|
default: true
|
|
description: Monitor and track price changes (restock_diff processor)
|
|
price_change_threshold_percent:
|
|
type: [number, 'null']
|
|
description: Minimum price change percentage to trigger notification
|
|
has_ldjson_price_data:
|
|
type: [boolean, 'null']
|
|
description: Whether page has LD-JSON price data (auto-detected)
|
|
readOnly: true
|
|
|
|
# Notifications
|
|
notification_screenshot:
|
|
type: boolean
|
|
default: false
|
|
description: Include screenshot in notifications (if supported by notification URL)
|
|
filter_failure_notification_send:
|
|
type: boolean
|
|
default: true
|
|
description: Send notification when filters fail to match content
|
|
|
|
# History & Display
|
|
use_page_title_in_list:
|
|
type: [boolean, 'null']
|
|
description: Display page title in watch list (null = use system default)
|
|
history_snapshot_max_length:
|
|
type: [integer, 'null']
|
|
minimum: 1
|
|
maximum: 1000
|
|
description: Maximum number of history snapshots to keep (null = use system default)
|
|
|
|
# Scheduling
|
|
time_schedule_limit:
|
|
type: object
|
|
description: Weekly schedule limiting when checks can run
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
monday:
|
|
$ref: '#/components/schemas/DaySchedule'
|
|
tuesday:
|
|
$ref: '#/components/schemas/DaySchedule'
|
|
wednesday:
|
|
$ref: '#/components/schemas/DaySchedule'
|
|
thursday:
|
|
$ref: '#/components/schemas/DaySchedule'
|
|
friday:
|
|
$ref: '#/components/schemas/DaySchedule'
|
|
saturday:
|
|
$ref: '#/components/schemas/DaySchedule'
|
|
sunday:
|
|
$ref: '#/components/schemas/DaySchedule'
|
|
|
|
# Conditions (advanced logic)
|
|
conditions:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
field:
|
|
type: string
|
|
description: Field to check (e.g., 'page_filtered_text', 'page_title')
|
|
operator:
|
|
type: string
|
|
description: Comparison operator (e.g., 'contains_regex', 'equals', 'not_equals')
|
|
value:
|
|
type: string
|
|
description: Value to compare against
|
|
required: [field, operator, value]
|
|
maxItems: 100
|
|
description: Array of condition rules for change detection logic (empty array when not set)
|
|
conditions_match_logic:
|
|
type: string
|
|
enum: ['ALL', 'ANY']
|
|
default: 'ALL'
|
|
description: Logic operator - ALL (match all conditions) or ANY (match any condition)
|
|
|
|
DaySchedule:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
default: true
|
|
start_time:
|
|
type: string
|
|
pattern: '^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$'
|
|
default: '00:00'
|
|
description: Start time in HH:MM format
|
|
duration:
|
|
type: object
|
|
properties:
|
|
hours:
|
|
type: string
|
|
pattern: '^[0-9]+$'
|
|
default: '24'
|
|
minutes:
|
|
type: string
|
|
pattern: '^[0-9]+$'
|
|
default: '00'
|
|
|
|
Watch:
|
|
allOf:
|
|
- $ref: '#/components/schemas/WatchBase'
|
|
- type: object
|
|
properties:
|
|
last_checked:
|
|
type: integer
|
|
description: Unix timestamp of last check
|
|
readOnly: true
|
|
last_changed:
|
|
type: integer
|
|
description: Unix timestamp of last change
|
|
readOnly: true
|
|
x-computed: true
|
|
last_error:
|
|
type: [string, boolean, 'null']
|
|
description: Last error message (false when no error, string when error occurred, null if not checked yet)
|
|
readOnly: true
|
|
last_viewed:
|
|
type: integer
|
|
description: 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.
|
|
minimum: 0
|
|
link:
|
|
type: string
|
|
format: string
|
|
description: The watch URL rendered in case of any Jinja2 markup, always use this for listing.
|
|
readOnly: true
|
|
x-computed: true
|
|
page_title:
|
|
type: [string, 'null']
|
|
description: HTML <title> tag extracted from the page
|
|
readOnly: true
|
|
check_count:
|
|
type: integer
|
|
description: Total number of checks performed
|
|
readOnly: true
|
|
fetch_time:
|
|
type: number
|
|
description: Duration of last fetch in seconds
|
|
readOnly: true
|
|
previous_md5:
|
|
type: [string, boolean]
|
|
description: MD5 hash of previous content (false if not set)
|
|
readOnly: true
|
|
previous_md5_before_filters:
|
|
type: [string, boolean]
|
|
description: MD5 hash before filters applied (false if not set)
|
|
readOnly: true
|
|
consecutive_filter_failures:
|
|
type: integer
|
|
description: Counter for consecutive filter match failures
|
|
readOnly: true
|
|
last_notification_error:
|
|
type: [string, 'null']
|
|
description: Last notification error message
|
|
readOnly: true
|
|
notification_alert_count:
|
|
type: integer
|
|
description: Number of notifications sent
|
|
readOnly: true
|
|
content-type:
|
|
type: [string, 'null']
|
|
description: Content-Type from last fetch
|
|
readOnly: true
|
|
remote_server_reply:
|
|
type: [string, 'null']
|
|
description: Server header from last response
|
|
readOnly: true
|
|
browser_steps_last_error_step:
|
|
type: [integer, 'null']
|
|
description: Last browser step that caused an error
|
|
readOnly: true
|
|
viewed:
|
|
type: [integer, boolean]
|
|
description: Computed property - true if watch has been viewed, false otherwise (deprecated, use last_viewed instead)
|
|
readOnly: true
|
|
x-computed: true
|
|
history_n:
|
|
type: integer
|
|
description: Number of history snapshots available
|
|
readOnly: true
|
|
x-computed: true
|
|
|
|
CreateWatch:
|
|
allOf:
|
|
- $ref: '#/components/schemas/WatchBase'
|
|
- type: 'object'
|
|
required:
|
|
- url
|
|
|
|
UpdateWatch:
|
|
allOf:
|
|
- $ref: '#/components/schemas/WatchBase' # Extends WatchBase for user-settable fields
|
|
- type: object
|
|
properties:
|
|
last_viewed:
|
|
type: integer
|
|
description: 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.
|
|
minimum: 0
|
|
# Note: ReadOnly and @property fields are filtered out in the backend before update
|
|
# We don't use unevaluatedProperties:false here to allow roundtrip GET/PUT workflows
|
|
# where the response includes computed fields that should be silently ignored
|
|
|
|
Tag:
|
|
allOf:
|
|
- $ref: '#/components/schemas/WatchBase'
|
|
- type: object
|
|
properties:
|
|
overrides_watch:
|
|
type: [boolean, 'null']
|
|
description: |
|
|
Whether this tag's settings override watch settings for all watches in this tag/group.
|
|
- true: Tag settings override watch settings
|
|
- false: Tag settings do not override (watches use their own settings)
|
|
- null: Not decided yet / inherit default behavior
|
|
# Future: Aggregated statistics from all watches with this tag
|
|
# check_count:
|
|
# type: integer
|
|
# description: Sum of check_count from all watches with this tag
|
|
# readOnly: true
|
|
# x-computed: true
|
|
# last_checked:
|
|
# type: integer
|
|
# description: Most recent last_checked timestamp from all watches with this tag
|
|
# readOnly: true
|
|
# x-computed: true
|
|
# last_changed:
|
|
# type: integer
|
|
# description: Most recent last_changed timestamp from all watches with this tag
|
|
# readOnly: true
|
|
# x-computed: true
|
|
|
|
CreateTag:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Tag'
|
|
- type: object
|
|
required:
|
|
- title
|
|
|
|
NotificationUrls:
|
|
type: object
|
|
properties:
|
|
notification_urls:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uri
|
|
description: List of notification URLs
|
|
required:
|
|
- notification_urls
|
|
|
|
SystemInfo:
|
|
type: object
|
|
properties:
|
|
watch_count:
|
|
type: integer
|
|
description: Total number of web page change monitors (watches)
|
|
tag_count:
|
|
type: integer
|
|
description: Total number of tags
|
|
uptime:
|
|
type: string
|
|
description: System uptime
|
|
version:
|
|
type: string
|
|
description: Application version
|
|
|
|
SearchResult:
|
|
type: object
|
|
properties:
|
|
watches:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/Watch'
|
|
description: Dictionary of matching web page change monitors (watches) keyed by UUID
|
|
|
|
WatchHistory:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Path to snapshot file
|
|
description: Dictionary of timestamps and snapshot paths
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: Error message
|
|
|
|
paths:
|
|
/watch:
|
|
get:
|
|
operationId: listWatches
|
|
tags: [Watch Management]
|
|
summary: List all watches
|
|
description: Return concise list of available web page change monitors (watches) and basic info
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/watch" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
response = requests.get('http://localhost:5000/api/v1/watch', headers=headers)
|
|
print(response.json())
|
|
parameters:
|
|
- name: recheck_all
|
|
in: query
|
|
description: Set to 1 to force recheck of all watches
|
|
schema:
|
|
type: string
|
|
enum: ["1"]
|
|
- name: tag
|
|
in: query
|
|
description: Tag name to filter results
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: List of watches
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/Watch'
|
|
example:
|
|
"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
|
|
post:
|
|
operationId: createWatch
|
|
tags: [Watch Management]
|
|
summary: Create a new watch
|
|
description: |
|
|
Create a single web page change monitor (watch). Requires at least `url` to be set.
|
|
|
|
Every watch can be configured with:
|
|
- **Processor mode**: `processor` field (`restock_diff` or `text_json_diff` - default)
|
|
- **Notification settings**: `notification_urls` (array), `notification_title`, `notification_body`, `notification_format`, `notification_muted`
|
|
- **Tags/Groups**: `tag` (UUID string) or `tags` (array of UUIDs)
|
|
- **Check settings**: `time_between_check`, `paused`, `method`, `fetch_backend`
|
|
- **Advanced options**: `headers`, `body`, `proxy`, `browser_steps`, and more
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
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",
|
|
"title": "Example Site Monitor",
|
|
"time_between_check": {
|
|
"hours": 1
|
|
}
|
|
}'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
import json
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'application/json'
|
|
}
|
|
data = {
|
|
'url': 'https://example.com',
|
|
'title': 'Example Site Monitor',
|
|
'time_between_check': {
|
|
'hours': 1
|
|
}
|
|
}
|
|
response = requests.post('http://localhost:5000/api/v1/watch',
|
|
headers=headers, json=data)
|
|
print(response.text)
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateWatch'
|
|
example:
|
|
url: "https://example.com"
|
|
title: "Example Site Monitor"
|
|
time_between_check:
|
|
hours: 1
|
|
responses:
|
|
'200':
|
|
description: Web page change monitor (watch) created successfully
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: "OK"
|
|
'500':
|
|
description: Server error
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
|
|
/watch/{uuid}:
|
|
get:
|
|
operationId: getWatch
|
|
tags: [Watch Management]
|
|
summary: Get single watch
|
|
description: Retrieve web page change monitor (watch) information and set muted/paused status. Returns the FULL Watch JSON.
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
|
|
response = requests.get(f'http://localhost:5000/api/v1/watch/{uuid}', headers=headers)
|
|
print(response.json())
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Web page change monitor (watch) unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: recheck
|
|
in: query
|
|
description: Recheck this web page change monitor (watch)
|
|
schema:
|
|
type: string
|
|
enum: ["1", "true"]
|
|
- name: paused
|
|
in: query
|
|
description: Set pause state
|
|
schema:
|
|
type: string
|
|
enum: [paused, unpaused]
|
|
- name: muted
|
|
in: query
|
|
description: Set mute state
|
|
schema:
|
|
type: string
|
|
enum: [muted, unmuted]
|
|
responses:
|
|
'200':
|
|
description: Watch information or operation result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Watch'
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: "OK"
|
|
'404':
|
|
description: Web page change monitor (watch) not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
put:
|
|
operationId: updateWatch
|
|
tags: [Watch Management]
|
|
summary: Update watch
|
|
description: Update an existing web page change monitor (watch) using JSON. Accepts the same structure as returned in [get single watch information](#operation/getWatch).
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X PUT "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"url": "https://updated-example.com",
|
|
"title": "Updated Monitor",
|
|
"paused": false
|
|
}'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'application/json'
|
|
}
|
|
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
|
|
data = {
|
|
'url': 'https://updated-example.com',
|
|
'title': 'Updated Monitor',
|
|
'paused': False
|
|
}
|
|
response = requests.put(f'http://localhost:5000/api/v1/watch/{uuid}',
|
|
headers=headers, json=data)
|
|
print(response.text)
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Web page change monitor (watch) unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateWatch'
|
|
responses:
|
|
'200':
|
|
description: Web page change monitor (watch) updated successfully
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: "OK"
|
|
'500':
|
|
description: Server error
|
|
|
|
delete:
|
|
operationId: deleteWatch
|
|
tags: [Watch Management]
|
|
summary: Delete watch
|
|
description: Delete a web page change monitor (watch) and all related history
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X DELETE "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
|
|
response = requests.delete(f'http://localhost:5000/api/v1/watch/{uuid}', headers=headers)
|
|
print(response.text)
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Web page change monitor (watch) unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'200':
|
|
description: Web page change monitor (watch) deleted successfully
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: "OK"
|
|
|
|
/watch/{uuid}/history:
|
|
get:
|
|
operationId: getWatchHistory
|
|
tags: [Watch History]
|
|
summary: Get watch history
|
|
description: |
|
|
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.
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
|
|
response = requests.get(f'http://localhost:5000/api/v1/watch/{uuid}/history', headers=headers)
|
|
print(response.json())
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Web page change monitor (watch) unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'200':
|
|
description: List of available snapshots
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WatchHistory'
|
|
example:
|
|
"1640995200": "/path/to/snapshot1.txt"
|
|
"1640998800": "/path/to/snapshot2.txt"
|
|
'404':
|
|
description: Web page change monitor (watch) not found
|
|
|
|
/watch/{uuid}/history/{timestamp}:
|
|
get:
|
|
operationId: getWatchSnapshot
|
|
tags: [Snapshots]
|
|
summary: Get single snapshot
|
|
description: |
|
|
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.
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history/latest" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
|
|
timestamp = 'latest' # or use specific timestamp like 1640995200
|
|
response = requests.get(f'http://localhost:5000/api/v1/watch/{uuid}/history/{timestamp}', headers=headers)
|
|
print(response.text)
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Web page change monitor (watch) unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: timestamp
|
|
in: path
|
|
required: true
|
|
description: Snapshot timestamp or 'latest'
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
enum: [latest]
|
|
- name: html
|
|
in: query
|
|
description: Set to 1 to return the last HTML
|
|
schema:
|
|
type: string
|
|
enum: ["1"]
|
|
responses:
|
|
'200':
|
|
description: Snapshot content
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
'404':
|
|
description: Snapshot not found
|
|
|
|
/watch/{uuid}/difference/{from_timestamp}/{to_timestamp}:
|
|
get:
|
|
operationId: getWatchHistoryDiff
|
|
tags: [Watch History]
|
|
summary: Get the difference between two snapshots
|
|
description: |
|
|
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:**
|
|
- Use `'latest'` for the most recent snapshot (to_timestamp)
|
|
- Use `'previous'` for the second-most-recent snapshot (from_timestamp)
|
|
- Or use specific Unix timestamps from the watch history
|
|
|
|
**Format Options:**
|
|
- `text` (default): Plain text with (removed) and (added) prefixes
|
|
- `html`: HTML format with (removed) and (added) text
|
|
- `htmlcolor`: Rich HTML with colored highlights (green for additions, red for deletions)
|
|
|
|
**Word-Level Diffing:**
|
|
- Enable word-level granularity with `word_diff=true` for detailed inline comparisons
|
|
- Disable with `word_diff=false` for line-level comparisons only (default false/off, line-level mode by default)
|
|
|
|
**Raw Diff Output:**
|
|
- Use `no_markup=true` to get raw diff content without any formatting applied
|
|
- Returns content with placeholders for opening/closing tags of changes
|
|
- Allows you to implement your own custom colorisation or formatting
|
|
- Skips all HTML color application and service tweaks (added text, html color tags, etc)
|
|
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
# 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 timestamps in plain 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"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
|
|
|
|
# Compare previous to latest with colored HTML output
|
|
response = requests.get(
|
|
f'http://localhost:5000/api/v1/watch/{uuid}/difference/previous/latest',
|
|
headers=headers,
|
|
params={'format': 'htmlcolor'}
|
|
)
|
|
print(response.text)
|
|
|
|
# Compare specific timestamps with word-level diff
|
|
from_ts = '1640995200'
|
|
to_ts = '1640998800'
|
|
response = requests.get(
|
|
f'http://localhost:5000/api/v1/watch/{uuid}/difference/{from_ts}/{to_ts}',
|
|
headers=headers,
|
|
params={'format': 'text', 'word_diff': 'true'}
|
|
)
|
|
print(response.text)
|
|
|
|
# Show only additions, ignore whitespace and use word-level diff
|
|
response = requests.get(
|
|
f'http://localhost:5000/api/v1/watch/{uuid}/difference/previous/latest',
|
|
headers=headers,
|
|
params={
|
|
'format': 'htmlcolor',
|
|
'type': 'diffWords',
|
|
'removed': 'false',
|
|
'replaced': 'false',
|
|
'ignoreWhitespace': 'true'
|
|
}
|
|
)
|
|
print(response.text)
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Web page change monitor (watch) unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: from_timestamp
|
|
in: path
|
|
required: true
|
|
description: Starting snapshot timestamp, 'previous' for second-most-recent, or specific Unix timestamp
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
description: Unix timestamp of the starting snapshot
|
|
- type: string
|
|
enum: [previous]
|
|
description: Use 'previous' to automatically select the second-most-recent snapshot
|
|
example: previous
|
|
- name: to_timestamp
|
|
in: path
|
|
required: true
|
|
description: Ending snapshot timestamp, 'latest' for most recent, or specific Unix timestamp
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
description: Unix timestamp of the ending snapshot
|
|
- type: string
|
|
enum: [latest]
|
|
description: Use 'latest' to automatically select the most recent snapshot
|
|
example: latest
|
|
- name: format
|
|
in: query
|
|
description: |
|
|
Output format for the diff:
|
|
- `text` (default): Plain text with (removed) and (added) prefixes
|
|
- `html`: Basic HTML format
|
|
- `htmlcolor`: Rich HTML with colored backgrounds (red for deletions, green for additions)
|
|
- `markdown`: Markdown format with HTML rendering
|
|
schema:
|
|
type: string
|
|
enum: [text, html, htmlcolor, markdown]
|
|
default: text
|
|
- name: word_diff
|
|
in: query
|
|
description: |
|
|
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
|
|
schema:
|
|
type: string
|
|
enum: ["true", "false", "1", "0", "yes", "no", "on", "off"]
|
|
default: "false"
|
|
- name: no_markup
|
|
in: query
|
|
description: |
|
|
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
|
|
schema:
|
|
type: string
|
|
enum: ["true", "false", "1", "0", "yes", "no", "on", "off"]
|
|
default: "false"
|
|
- name: type
|
|
in: query
|
|
description: |
|
|
Diff granularity type:
|
|
- `diffLines` (default): Line-level comparison, showing which lines changed
|
|
- `diffWords`: Word-level comparison, showing which words changed within lines
|
|
|
|
This parameter is an alternative to `word_diff` for better alignment with the UI.
|
|
If both are specified, `type=diffWords` will enable word-level diffing.
|
|
schema:
|
|
type: string
|
|
enum: [diffLines, diffWords]
|
|
default: diffLines
|
|
- name: changesOnly
|
|
in: query
|
|
description: |
|
|
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
|
|
schema:
|
|
type: string
|
|
enum: ["true", "false", "1", "0", "yes", "no", "on", "off"]
|
|
default: "true"
|
|
- name: ignoreWhitespace
|
|
in: query
|
|
description: |
|
|
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
|
|
schema:
|
|
type: string
|
|
enum: ["true", "false", "1", "0", "yes", "no", "on", "off"]
|
|
default: "false"
|
|
- name: removed
|
|
in: query
|
|
description: |
|
|
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
|
|
schema:
|
|
type: string
|
|
enum: ["true", "false", "1", "0", "yes", "no", "on", "off"]
|
|
default: "true"
|
|
- name: added
|
|
in: query
|
|
description: |
|
|
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
|
|
schema:
|
|
type: string
|
|
enum: ["true", "false", "1", "0", "yes", "no", "on", "off"]
|
|
default: "true"
|
|
- name: replaced
|
|
in: query
|
|
description: |
|
|
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
|
|
schema:
|
|
type: string
|
|
enum: ["true", "false", "1", "0", "yes", "no", "on", "off"]
|
|
default: "true"
|
|
responses:
|
|
'200':
|
|
description: Formatted diff between the two snapshots
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Plain text diff with change markers
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
description: HTML formatted diff with styling
|
|
'400':
|
|
description: Invalid format parameter or invalid request
|
|
'404':
|
|
description: Watch not found, timestamps not found, or insufficient history
|
|
|
|
/watch/{uuid}/favicon:
|
|
get:
|
|
operationId: getWatchFavicon
|
|
tags: [Favicon]
|
|
summary: Get watch favicon
|
|
description: Get the favicon for a web page change monitor (watch) as displayed in the watch overview list.
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
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
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
|
|
response = requests.get(f'http://localhost:5000/api/v1/watch/{uuid}/favicon', headers=headers)
|
|
with open('favicon.ico', 'wb') as f:
|
|
f.write(response.content)
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Web page change monitor (watch) unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'200':
|
|
description: Favicon binary data
|
|
content:
|
|
image/*:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'404':
|
|
description: Favicon not found
|
|
|
|
/tags:
|
|
get:
|
|
operationId: listTags
|
|
tags: [Group / Tag Management]
|
|
summary: List all tags
|
|
description: Return list of available tags/groups
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/tags" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
response = requests.get('http://localhost:5000/api/v1/tags', headers=headers)
|
|
print(response.json())
|
|
responses:
|
|
'200':
|
|
description: List of tags
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/Tag'
|
|
example:
|
|
"550e8400-e29b-41d4-a716-446655440000":
|
|
uuid: "550e8400-e29b-41d4-a716-446655440000"
|
|
title: "Production Sites"
|
|
notification_urls: ["mailto:admin@example.com"]
|
|
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
|
|
|
|
/tag:
|
|
post:
|
|
operationId: createTag
|
|
tags: [Group / Tag Management]
|
|
summary: Create tag
|
|
description: Create a single tag/group
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X POST "http://localhost:5000/api/v1/tag" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"title": "Important Sites"
|
|
}'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'application/json'
|
|
}
|
|
data = {'title': 'Important Sites'}
|
|
response = requests.post('http://localhost:5000/api/v1/tag',
|
|
headers=headers, json=data)
|
|
print(response.json())
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateTag'
|
|
example:
|
|
title: "Important Sites"
|
|
responses:
|
|
'201':
|
|
description: Tag created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
description: UUID of the created tag
|
|
'400':
|
|
description: Invalid or unsupported tag
|
|
|
|
/tag/{uuid}:
|
|
get:
|
|
operationId: getTag
|
|
tags: [Group / Tag Management]
|
|
summary: Get single tag
|
|
description: Retrieve tag information, set notification_muted status, recheck all web page change monitors (watches) in tag.
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'
|
|
response = requests.get(f'http://localhost:5000/api/v1/tag/{tag_uuid}', headers=headers)
|
|
print(response.json())
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Tag unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: muted
|
|
in: query
|
|
description: Set mute state
|
|
schema:
|
|
type: string
|
|
enum: [muted, unmuted]
|
|
- name: recheck
|
|
in: query
|
|
description: Queue all web page change monitors (watches) with this tag for recheck
|
|
schema:
|
|
type: string
|
|
enum: ["true"]
|
|
responses:
|
|
'200':
|
|
description: Tag information or operation result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Tag'
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: "OK"
|
|
'404':
|
|
description: Tag not found
|
|
|
|
put:
|
|
operationId: updateTag
|
|
tags: [Group / Tag Management]
|
|
summary: Update tag
|
|
description: Update an existing tag using JSON
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X PUT "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"title": "Updated Production Sites",
|
|
"notification_muted": false
|
|
}'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'application/json'
|
|
}
|
|
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'
|
|
data = {
|
|
'title': 'Updated Production Sites',
|
|
'notification_muted': False
|
|
}
|
|
response = requests.put(f'http://localhost:5000/api/v1/tag/{tag_uuid}',
|
|
headers=headers, json=data)
|
|
print(response.text)
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Tag unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Tag'
|
|
responses:
|
|
'200':
|
|
description: Tag updated successfully
|
|
'500':
|
|
description: Server error
|
|
|
|
delete:
|
|
operationId: deleteTag
|
|
tags: [Group / Tag Management]
|
|
summary: Delete tag
|
|
description: Delete a tag/group and remove it from all web page change monitors (watches)
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X DELETE "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'
|
|
response = requests.delete(f'http://localhost:5000/api/v1/tag/{tag_uuid}', headers=headers)
|
|
print(response.text)
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
description: Tag unique ID
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'200':
|
|
description: Tag deleted successfully
|
|
|
|
|
|
/notifications:
|
|
get:
|
|
operationId: getNotifications
|
|
tags: [Notifications]
|
|
summary: Get notification URLs
|
|
description: Return the notification URL list from the configuration
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/notifications" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
response = requests.get('http://localhost:5000/api/v1/notifications', headers=headers)
|
|
print(response.json())
|
|
responses:
|
|
'200':
|
|
description: List of notification URLs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NotificationUrls'
|
|
|
|
post:
|
|
operationId: addNotifications
|
|
tags: [Notifications]
|
|
summary: Add notification URLs
|
|
description: Add one or more notification URLs to the configuration
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X POST "http://localhost:5000/api/v1/notifications" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"notification_urls": [
|
|
"mailto:admin@example.com",
|
|
"discord://webhook_id/webhook_token"
|
|
]
|
|
}'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'application/json'
|
|
}
|
|
data = {
|
|
'notification_urls': [
|
|
'mailto:admin@example.com',
|
|
'discord://webhook_id/webhook_token'
|
|
]
|
|
}
|
|
response = requests.post('http://localhost:5000/api/v1/notifications',
|
|
headers=headers, json=data)
|
|
print(response.json())
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NotificationUrls'
|
|
example:
|
|
notification_urls:
|
|
- "mailto:admin@example.com"
|
|
- "discord://webhook_id/webhook_token"
|
|
responses:
|
|
'201':
|
|
description: Notification URLs added successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NotificationUrls'
|
|
'400':
|
|
description: Invalid input
|
|
|
|
put:
|
|
operationId: replaceNotifications
|
|
tags: [Notifications]
|
|
summary: Replace notification URLs
|
|
description: Replace all notification URLs with the provided list (can be empty)
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X PUT "http://localhost:5000/api/v1/notifications" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"notification_urls": [
|
|
"mailto:newadmin@example.com"
|
|
]
|
|
}'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'application/json'
|
|
}
|
|
data = {
|
|
'notification_urls': [
|
|
'mailto:newadmin@example.com'
|
|
]
|
|
}
|
|
response = requests.put('http://localhost:5000/api/v1/notifications',
|
|
headers=headers, json=data)
|
|
print(response.json())
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NotificationUrls'
|
|
responses:
|
|
'200':
|
|
description: Notification URLs replaced successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NotificationUrls'
|
|
'400':
|
|
description: Invalid input
|
|
|
|
delete:
|
|
operationId: deleteNotifications
|
|
tags: [Notifications]
|
|
summary: Delete notification URLs
|
|
description: Delete one or more notification URLs from the configuration
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X DELETE "http://localhost:5000/api/v1/notifications" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"notification_urls": [
|
|
"mailto:admin@example.com"
|
|
]
|
|
}'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'application/json'
|
|
}
|
|
data = {
|
|
'notification_urls': [
|
|
'mailto:admin@example.com'
|
|
]
|
|
}
|
|
response = requests.delete('http://localhost:5000/api/v1/notifications',
|
|
headers=headers, json=data)
|
|
print(response.status_code)
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NotificationUrls'
|
|
responses:
|
|
'204':
|
|
description: Notification URLs deleted successfully
|
|
'400':
|
|
description: No matching notification URLs found
|
|
|
|
/search:
|
|
get:
|
|
operationId: searchWatches
|
|
tags: [Search]
|
|
summary: Search watches
|
|
description: Search web page change monitors (watches) by URL or title text
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/search?q=example.com" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
params = {'q': 'example.com'}
|
|
response = requests.get('http://localhost:5000/api/v1/search',
|
|
headers=headers, params=params)
|
|
print(response.json())
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
description: Search query to match against watch URLs and titles
|
|
schema:
|
|
type: string
|
|
- name: tag
|
|
in: query
|
|
description: Tag name to limit results (name not UUID)
|
|
schema:
|
|
type: string
|
|
- name: partial
|
|
in: query
|
|
description: Allow partial matching of URL query
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Search results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SearchResult'
|
|
example:
|
|
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
|
|
|
|
/import:
|
|
post:
|
|
operationId: importWatches
|
|
tags: [Import]
|
|
summary: Import watch URLs with configuration
|
|
description: |
|
|
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 watches
|
|
- `proxy` - Use specific proxy for imported watches
|
|
- `dedupe` - Skip duplicate URLs (default: true)
|
|
|
|
**Type Conversion:**
|
|
- Booleans: `true`, `false`, `1`, `0`, `yes`, `no`
|
|
- Arrays: Comma-separated or JSON format (`[item1,item2]`)
|
|
- Objects: JSON format (`{"key":"value"}`)
|
|
- Numbers: Parsed as int or float
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
# Basic import
|
|
curl -X POST "http://localhost:5000/api/v1/import" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: text/plain" \
|
|
-d $'https://example.com\nhttps://example.org\nhttps://example.net'
|
|
|
|
# Import with processor and fetch backend
|
|
curl -X POST "http://localhost:5000/api/v1/import?processor=restock_diff&fetch_backend=html_webdriver" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: text/plain" \
|
|
-d $'https://example.com\nhttps://example.org'
|
|
|
|
# Import with multiple settings
|
|
curl -X POST "http://localhost:5000/api/v1/import?processor=restock_diff&paused=true&tag=production" \
|
|
-H "x-api-key: YOUR_API_KEY" \
|
|
-H "Content-Type: text/plain" \
|
|
-d $'https://example.com'
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {
|
|
'x-api-key': 'YOUR_API_KEY',
|
|
'Content-Type': 'text/plain'
|
|
}
|
|
|
|
# Basic import
|
|
urls = 'https://example.com\nhttps://example.org\nhttps://example.net'
|
|
response = requests.post('http://localhost:5000/api/v1/import',
|
|
headers=headers, data=urls)
|
|
print(response.json())
|
|
|
|
# Import with configuration
|
|
params = {
|
|
'processor': 'restock_diff',
|
|
'fetch_backend': 'html_webdriver',
|
|
'paused': 'false',
|
|
'tag': 'production'
|
|
}
|
|
response = requests.post('http://localhost:5000/api/v1/import',
|
|
headers=headers, params=params, data=urls)
|
|
print(response.json())
|
|
parameters:
|
|
- name: tag_uuids
|
|
in: query
|
|
description: Tag UUID(s) to apply to imported watches (comma-separated for multiple)
|
|
schema:
|
|
type: string
|
|
example: "550e8400-e29b-41d4-a716-446655440000"
|
|
- name: tag
|
|
in: query
|
|
description: Tag name to apply to imported watches
|
|
schema:
|
|
type: string
|
|
example: "production"
|
|
- name: proxy
|
|
in: query
|
|
description: Proxy key to use for imported watches
|
|
schema:
|
|
type: string
|
|
example: "proxy1"
|
|
- name: dedupe
|
|
in: query
|
|
description: Skip duplicate URLs (default true)
|
|
schema:
|
|
type: boolean
|
|
default: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: |
|
|
https://example.com
|
|
https://example.org
|
|
https://example.net
|
|
responses:
|
|
'200':
|
|
description: URLs imported successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
description: List of created watch UUIDs
|
|
'500':
|
|
description: Server error
|
|
|
|
/systeminfo:
|
|
get:
|
|
operationId: getSystemInfo
|
|
tags: [System Information]
|
|
summary: Get system information
|
|
description: Return information about the current system state
|
|
x-code-samples:
|
|
- lang: 'curl'
|
|
source: |
|
|
curl -X GET "http://localhost:5000/api/v1/systeminfo" \
|
|
-H "x-api-key: YOUR_API_KEY"
|
|
- lang: 'Python'
|
|
source: |
|
|
import requests
|
|
|
|
headers = {'x-api-key': 'YOUR_API_KEY'}
|
|
response = requests.get('http://localhost:5000/api/v1/systeminfo', headers=headers)
|
|
print(response.json())
|
|
responses:
|
|
'200':
|
|
description: System information
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemInfo'
|
|
example:
|
|
watch_count: 42
|
|
tag_count: 5
|
|
uptime: "2 days, 3:45:12"
|
|
version: "0.50.10"
|