### Python Example: Get All Watches

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Demonstrates how to fetch all watches using the Python client library. Ensure the library is installed and configured with your API key.

```python
import changedetection

client = changedetection.Changedetection(
    base_url="http://localhost:5000",
    api_key="YOUR_API_KEY",
)

watches = client.watch.get_all()
for watch in watches:
    print(watch)

```

--------------------------------

### Docker Compose Installation

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/README.md

Install changedetection.io using Docker Compose by cloning the repository and running the command. This is a simple way to get started.

```bash
$ docker compose up -d
```

--------------------------------

### Install setuptools

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Microsoft-Windows

Install the setuptools package using pip3. This is required for Python 3.12 and later.

```bash
pip3 install setuptools
```

--------------------------------

### BrightData Proxy Configuration Example

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Proxy-configuration

Illustrates a `proxies.json` file configured with BrightData proxy details for different geographical locations. This setup allows selecting specific proxy endpoints for various watches.

```json
{
  "europe-germany": {
    "label": "Europe / Germany",
    "url": "http://lum-customer-XXXXXXX-zone-data_center-country-de:PPPPPPPPP@zproxy.lum-superproxy.io:22225"
  },
  "usa-2": {
    "label": "USA",
    "url": "http://lum-customer-XXXXXXX-zone-data_center-country-us:PPPPPPPPP@zproxy.lum-superproxy.io:22225"
  },
  "australia": {
    "label": "Australia",
    "url": "http://lum-customer-XXXXXXX-zone-data_center-country-au:PPPPPPPPP@zproxy.lum-superproxy.io:22225"
  }
}
```

--------------------------------

### Install Dependencies and Generate Docs

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/README.md

Run these commands from the `docs/` directory to install necessary dependencies and generate HTML documentation from the OpenAPI spec using Redoc. This is recommended for modern API documentation.

```bash
# Install dependencies (first time only)
npm install

# Generate the HTML documentation from OpenAPI spec using Redoc
npm run build-docs
```

--------------------------------

### Install and Build Browserless NPM Packages

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher

Navigates into the cloned browserless directory and installs its Node.js dependencies, builds the project, and prunes production packages.

```bash
cd /opt/browserless
npm install
npm run build
npm prune production
```

--------------------------------

### Python Pip Installation and Run

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/README.md

Install changedetection.io using pip and run it with a specified data directory and port. Access the UI via http://127.0.0.1:5000.

```bash
$ pip3 install changedetection.io
$ changedetection.io -d /path/to/empty/data/dir -p 5000
```

--------------------------------

### Install changedetection.io with pip

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/README-pip.md

Installs the changedetection.io package using pip3. This is the primary method for setting up the service.

```bash
$ pip3 install changedetection.io
```

--------------------------------

### Install Required Package on Raspberry Pi

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Troubleshooting

Install the libxslt1 package using apt-get, commonly required when installing changedetection.io from PIP.

```bash
apt-get install libxslt1 -y
```

--------------------------------

### List All Tags Response Example

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example JSON response when listing all tags, showing tag UUIDs, titles, notification URLs, and muted status.

```json
{  *   "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                   }       }
```

--------------------------------

### Install pybind11-pixelmatch

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/processors/image_ssim_diff/README.md

Installs the pybind11-pixelmatch library, which provides an alternative comparison method for better anti-aliasing detection, especially for text-heavy screenshots. Note potential build issues on some platforms.

```bash
pip install pybind11-pixelmatch>=0.1.3
```

--------------------------------

### Retrieve a restock/price monitor

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example using curl to get the details of an existing watch, including its restock_diff processor configuration.

```bash
curl -X GET "http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091" \
 -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Example of Dynamic URL Request

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Handling-variables-in-the-watched-URL

This is an example of how the URL from the previous snippet would be resolved with the current date from the 'Europe/Berlin' timezone.

```html
https://changedetection.io/test.txt?date=24.10.2022
```

--------------------------------

### Example JSON response for search results

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

This is an example JSON response when searching for watches, detailing watch properties.

```json
{
  "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
    }
  }
}
```

--------------------------------

### Start changedetection.io

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Microsoft-Windows

Run the changedetection.io application from the command line.

```bash
changedetection.py
```

--------------------------------

### Install System Dependencies

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher

Installs a comprehensive list of system dependencies required for Playwright and changedetection.io on Debian 11. This includes development tools, fonts, and various libraries.

```bash
sudo apt install python3-dev python3-pip nodejs build-essential ca-certificates curl dumb-init ffmpeg fontconfig fonts-freefont-ttf fonts-gfs-neohellenic fonts-indic fonts-ipafont-gothic fonts-kacst fonts-liberation fonts-noto-cjk fonts-noto-color-emoji fonts-roboto fonts-thai-tlwg fonts-ubuntu fonts-wqy-zenhei gconf-service git libappindicator1 libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm-dev libgbm1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 locales lsb-release msttcorefonts pdftk unzip wget xdg-utils xvfb
```

--------------------------------

### Stab Pane Usage Example

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/templates/_stab.html

Shows how to define content for a specific tab pane using the `stab_pane` macro. This example defines content for an 'overview' pane.

```html
{% call stab_pane('overview') %}

Overview content…

{% endcall %}
```

--------------------------------

### Example JSON response for imported watch UUIDs

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

This is an example JSON response after successfully importing watch URLs, returning the UUIDs of the newly created watches.

```json
[
  "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
```

--------------------------------

### Install Node.js LTS

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher

Installs the Node.js LTS (Long Term Support) repository for Debian-based systems, required for Playwright dependencies.

```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
```

--------------------------------

### Install Development Packages on iPadOS

Source: https://github.com/dgtlmoon/changedetection.io/wiki/iPadOS-Install-Notes---WIP

Install necessary development packages for libxml2 and libxslt on iPadOS. This is a prerequisite for building certain Python packages.

```shell
apk add libxslt-dev libxml2-dev
```

--------------------------------

### Example Mailto URL for Email Notifications

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Notification-configuration-notes

An example of how to specify a mailto URL for sending emails, including the sender and recipient.

```text
mailto://john@mail.mycompany.com/?to=steve@gmail.com
```

--------------------------------

### Visual Selector Examples

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/processors/image_ssim_diff/README.md

Provides examples of CSS selectors and XPath expressions used in the 'Include filters' field to specify regions for comparison. The processor will crop screenshots to the bounding box of the first matched element.

```text
.content-area
//div[@id='main']
```

--------------------------------

### Example Plugin: Word Count for Stats Tab

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/PLUGIN_README.md

A practical example of a UI Stats Tab plugin that calculates and displays the word count of the latest snapshot in a table format within the Stats tab.

```python
import pluggy
from loguru import logger

global_hookimpl = pluggy.HookimplMarker("changedetectionio")

def count_words_in_history(watch):
    """Count words in the latest snapshot"""
    try:
        if not watch.history.keys():
            return 0
            
        latest_key = list(watch.history.keys())[-1]
        latest_content = watch.get_history_snapshot(timestamp=latest_key)
        return len(latest_content.split())
    except Exception as e:
        logger.error(f"Error counting words: {str(e)}")
        return 0

@global_hookimpl
def ui_edit_stats_extras(watch):
    """Add word count to the Stats tab"""
    word_count = count_words_in_history(watch)
    
    html = f"""
    <div class="word-count-stats">
        <h4>Content Analysis</h4>
        <table class="pure-table">
            <tbody>
                <tr>
                    <td>Word count (latest snapshot)</td>
                    <td>{word_count}</td>
                </tr>
            </tbody>
        </table>
    </div>
    """
    return html
```

--------------------------------

### Docker Standalone Installation

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/README.md

Install changedetection.io using a standalone Docker container. This command maps port 5000 and uses a named volume for data persistence.

```bash
$ docker run -d --restart always -p "127.0.0.1:5000:5000" -v datastore-volume:/datastore --name changedetection.io dgtlmoon/changedetection.io
```

--------------------------------

### Install Playwright via Pip

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher

Installs the Playwright library using pip, essential if the 'No module named 'playwright'' error occurs. Assumes Python 3 is available.

```bash
python3 -m pip install playwright
```

--------------------------------

### Clone Browserless Git Repository

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher

Clones the browserless Git repository from GitHub into the /opt/browserless directory. This is part of the Pip install guide setup.

```bash
git clone https://github.com/browserless/chrome /opt/browserless
```

--------------------------------

### Get Notification URLs Response

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example JSON response when retrieving notification URLs.

```json
{
  "notification_urls": [
    "http://example.com"
  ]
}
```

--------------------------------

### Python Example: Create a New Watch

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Demonstrates creating a new watch for a URL using the Python client library. Requires API key.

```python
import changedetection

client = changedetection.Changedetection(
    base_url="http://localhost:5000",
    api_key="YOUR_API_KEY",
)

watch = client.watch.create(url="https://example.com", tag="example-python")
print(watch)

```

--------------------------------

### Get Full API Specification

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Retrieve the fully merged OpenAPI specification for this instance, including schemas from installed processor plugins. This is useful for generating accurate documentation for your specific installation.

```APIDOC
## GET /api/v1/full-spec

### Description
Retrieve the fully merged OpenAPI specification for this instance, including schemas from installed processor plugins. This is useful for generating accurate documentation for your specific installation.

### Method
GET

### Endpoint
/api/v1/full-spec

### Response
#### Success Response (200)
- **OpenAPI Specification** (string) - The merged OpenAPI specification in YAML format.

### Response Example
```yaml
# Example YAML response (truncated)
openapi: 3.0.0
info:
  title: ChangeDetection.io API
  version: 0.50.10
paths:
  /api/v1/import:
    post:
      summary: Import URLs
      description: Import a list of URLs to be monitored.
      parameters:
        - name: processor
          in: query
          schema:
            type: string
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: URLs imported successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
  /api/v1/systeminfo:
    get:
      summary: Get system information
      description: Return information about the current system state
      responses:
        '200':
          description: System information
          content:
            application/json:
              schema:
                type: object
                properties:
                  watch_count:
                    type: integer
                  tag_count:
                    type: integer
                  uptime:
                    type: string
                  version:
                    type: string
```
```

--------------------------------

### Get full live API spec

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Retrieves the fully merged OpenAPI specification for the Change Detection instance, dynamically merged with schemas from installed processor plugins. This is useful for obtaining schema-accurate documentation for your specific installation.

```APIDOC
## GET /api/v1/full-spec

### Description
Retrieves the fully merged OpenAPI specification for the Change Detection instance, dynamically merged with schemas from installed processor plugins. This is useful for obtaining schema-accurate documentation for your specific installation.

### Method
GET

### Endpoint
/api/v1/full-spec

### Response
#### Success Response (200)
- **OpenAPI Specification** (string) - The merged OpenAPI specification in YAML format, including all processor plugin schemas.

### Response Example
```yaml
openapi: 3.0.0
info:
  title: Change Detection API
  version: 1.0.0
paths:
  /api/v1/watch/{watch_id}:
    put:
      summary: Update monitor thresholds
      parameters:
        - name: watch_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                processor_config_restock_diff:
                  type: object
                  properties:
                    in_stock_processing:
                      type: string
                    follow_price_changes:
                      type: boolean
                    price_change_min:
                      type: number
                    price_change_max:
                      type: number
      responses:
        '200':
          description: Monitor updated successfully
    delete:
      summary: Remove monitor
      parameters:
        - name: watch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Monitor deleted successfully
  /api/v1/full-spec:
    get:
      summary: Get full live API spec
      responses:
        '200':
          description: Merged OpenAPI specification in YAML format
```
```

--------------------------------

### Get Single Tag Request (curl)

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example using curl to retrieve a single tag by its UUID and authenticate with an API key.

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

--------------------------------

### Enable Systemd Services

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher

Commands to enable the browserless and changedetection.io services to start automatically on system boot.

```bash
systemctl enable browserless.service
systemctl enable changedetection.service
```

--------------------------------

### Watch History Response Sample

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example JSON response for the Get Watch History endpoint, listing available snapshot timestamps.

```json
{
  "1640995200": "/path/to/snapshot1.txt",
  "1640998800": "/path/to/snapshot2.txt"
}
```

--------------------------------

### Create a restock/price monitor using restock_diff

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example using curl to create a new watch that monitors product availability and price changes with specific configurations.

```bash
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
 }
 }'
```

--------------------------------

### Get Full Live API Spec

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Retrieve the fully merged OpenAPI specification, including schemas from installed processor plugins. Useful for schema-accurate documentation.

```bash
GET /api/v1/full-spec
```

```bash
http://localhost:5000/api/v1/full-spec
```

```bash
https://yourdomain.com/api/v1/full-spec
```

```bash
{protocol}://{host}/api/v1/full-spec
```

--------------------------------

### Get Single Watch Request (curl)

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example using curl to retrieve a specific watch's information by its UUID. Requires an API key for authorization.

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

--------------------------------

### Changedetection.io Systemd Service Configuration

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Playwright-content-fetcher

Example systemd service file for changedetection.io. It specifies the Playwright driver URL pointing to the local browserless service and the command to start the changedetection.io application.

```systemd
[Unit]
Description=changedetection.io service
After=network.target browserless.service
Wants=browserless.service

[Service]
Environment=PLAYWRIGHT_DRIVER_URL=ws://127.0.0.1:3000/?stealth=1&--disable-web-security=true
ExecStart=/usr/local/bin/changedetection.io -d /opt/change-detection -p 80
SyslogIdentifier=change-detection

[Install]
WantedBy=default.target
```

--------------------------------

### Example Headers Text File

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Adding-headers-from-an-external-file

A simple flat text file format for defining custom headers. Each line should contain a header name followed by a colon and its value.

```text
My-header: some value
Another-header: another-value
```

--------------------------------

### Get Watch Favicon (Python)

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

This Python script retrieves and saves the favicon for a given watch UUID. Ensure you have the 'requests' library installed and replace placeholders with your API key and watch UUID.

```Python
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)
```

--------------------------------

### Get System Information (Python)

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

This Python snippet shows how to fetch system information using the requests library.

```Python
import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
response = requests.get('http://localhost:5000/api/v1/systeminfo', headers=headers)
print(response.json())
```

--------------------------------

### Import URLs with configuration

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Bulk import multiple URLs for monitoring. You can specify tags, proxy settings, and deduplication behavior via query parameters.

```text/plain
https://example.com
https://example.org
https://example.net
```

--------------------------------

### Promotional Link for Hosting Service

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/templates/base.html

Displays a prominent link encouraging users to use the 'Let us host your instance!' service, including a referral GUID.

```html
[Let us host your instance!](https://changedetection.io/?ref={{ guid }})
```

--------------------------------

### Stab Pane Usage Example (Settings)

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/templates/_stab.html

Illustrates defining content for another tab pane, in this case, a 'settings' pane.

```html
{% call stab_pane('settings') %}

Settings content…

{% endcall %}
```

--------------------------------

### CSS Selector Example

Source: https://github.com/dgtlmoon/changedetection.io/wiki/CSS-Selector-help

Example of a CSS selector targeting an element with a specific ID within a class.

```html
<div class="points">
  <span id="interesting">
  57 points
  </span>
</div>
```

```css
.points #interesting
```

--------------------------------

### Environment Variables for Comparison Configuration

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/processors/image_ssim_diff/README.md

Lists and explains key environment variables for configuring the image comparison process, including the comparison method, thresholds for OpenCV and pixelmatch, Gaussian blur sigma, minimum change percentage, and diff visualization size limits.

```bash
# Comparison method (opencv or pixelmatch)
COMPARISON_METHOD=opencv  # Default

# OpenCV threshold (0-255, lower = more sensitive)
COMPARISON_THRESHOLD_OPENCV=30  # Default

# Pixelmatch threshold (0-100, mapped to 0-1 scale)
COMPARISON_THRESHOLD_PIXELMATCH=10  # Default

# Gaussian blur sigma for OpenCV (0 = no blur, higher = more blur)
OPENCV_BLUR_SIGMA=0.8  # Default

# Minimum change percentage to trigger detection
OPENCV_MIN_CHANGE_PERCENT=0.1  # Default (0.1%)
PIXELMATCH_MIN_CHANGE_PERCENT=0.1  # Default

# Diff visualization image size limits (pixels)
MAX_DIFF_HEIGHT=8000  # Default
MAX_DIFF_WIDTH=900  # Default
```

--------------------------------

### Notification Service Examples

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/README.md

Examples of notification URLs supported by changedetection.io via the apprise library. These can be configured for various services.

```text
discord://webhook_id/webhook_token
flock://app_token/g:channel_id
gitter://token/room
gchat://workspace/key/token
msteams://TokenA/TokenB/TokenC/
o365://TenantID:AccountEmail/ClientID/ClientSecret/TargetEmail
rocket://user:password@hostname/#Channel
mailto://user:pass@example.com?to=receivingAddress@example.com
json://someserver.com/custom-api
syslog://
```

--------------------------------

### Version Navigation and Keyboard Controls

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/blueprint/ui/templates/preview.html

Renders version selection dropdown and navigation buttons if there are two or more versions available. Includes keyboard shortcuts for navigating between previous and next versions.

```html
{{ _('Select timestamp') }} {% for version in versions|reverse %} {{ version }} {% endfor %}  {{ _('Go') }}

  
**{{ _('Keyboard:') }}** ← {{ _('Previous') }}   → {{ _('Next') }}

{% endif %}
```

--------------------------------

### Telegram Notification Error Example

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Troubleshooting

Example log output showing a 'message is too long' error when sending notifications to Telegram.

```log
WARNING:apprise:Failed to send Telegram notification to {ID}: Bad Request: message is too long, error=400.
DEBUG:apprise:Response Details:
b'{"ok":false,"error_code":400,"description":"Bad Request: message is too long"}'
```

--------------------------------

### POST /api/v1/watch with restock_diff processor

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

This example demonstrates how to create a new watch using the 'restock_diff' processor. It specifies the URL to monitor and the configuration for the processor, including stock processing behavior and price change monitoring.

```APIDOC
## POST /api/v1/watch with restock_diff processor

### Description
Creates a new watch to monitor a product's availability and price changes using the `restock_diff` processor.

### Method
POST

### Endpoint
/api/v1/watch

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the product to monitor.
- **processor** (string) - Required - Set to `"restock_diff"` to use this processor.
- **processor_config_restock_diff** (object) - Optional - Configuration for the `restock_diff` processor.
  - **in_stock_processing** (string) - Optional - `"in_stock_only"` (default), `"all_changes"`, or `"off"`.
  - **follow_price_changes** (boolean) - Optional - `true` (default) to monitor price changes.
  - **price_change_min** (number|null) - Optional - Alert when price drops below this value.
  - **price_change_max** (number|null) - Optional - Alert when price rises above this value.
  - **price_change_threshold_percent** (number|null) - Optional - Minimum percentage change to trigger an alert.

### Request Example
```json
{
  "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
  }
}
```

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier for the created watch.
- **url** (string) - The monitored URL.
- **processor** (string) - The processor used.
- **processor_config_restock_diff** (object) - The configuration applied to the `restock_diff` processor.

#### Response Example
```json
{
  "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
  }
}
```
```

--------------------------------

### Create Watch with Custom Processor (curl)

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Example using curl to create a new watch with a custom processor configuration. Ensure to replace YOUR_API_KEY and adjust the URL and processor details as needed.

```curl
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 }
  }'
```

--------------------------------

### JSON Notification Body Example

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Notification-configuration-notes

An example of a JSON notification body that uses the `tojson` filter to ensure the URL is safely embedded.

```json
{
  "myKey": 1234,
  "url": "{{watch_url|tojson}}"
}
```

--------------------------------

### Import Watch URLs with Configuration

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Imports URLs and applies custom configurations via query parameters. Any watch configuration field, such as processor, fetch_backend, or notification_urls, can be passed as a query parameter. Special parameters like 'tag', 'proxy', and 'dedupe' are also supported.

```cURL
# Import with processor and fetch backend
curl -X POST "http://localhost:5000/api/v1/import?processor=html&fetch_backend=requests" \
 -H "x-api-key: YOUR_API_KEY" \
 -H "Content-Type: text/plain" \
 -d $'https://example.com'
```

--------------------------------

### Run changedetection.io with data directory and port

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/README-pip.md

Starts the changedetection.io service, specifying the data directory and listening port. The data directory is required, and the port defaults to 5000 if not provided.

```bash
$ changedetection.io -d /path/to/empty/data/dir -p 5000
```

--------------------------------

### Example HTML with an Image

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Detecting-changes-in-images

This is an example of HTML content that includes an image within a specific div. It demonstrates the structure that changedetection.io can parse.

```html
<HTML>
<BODY>
   <div id="wrapper">
      <img src="november-calendar.jpg">
   </div>
   <div id="other stuff">
     our new calendar!
    </div>
</BODY>
</HTML>
```

--------------------------------

### Translation Configuration in setup.cfg

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/translations/README.md

Configuration settings for translation extraction, catalog updates, and compilation, ensuring consistent line width and entry ordering.

```ini
[extract_messages]
mapping_file = babel.cfg
output_file = changedetectionio/translations/messages.pot
input_paths = changedetectionio
keywords = _ _l gettext
sort_by_file = true       # Keeps entries ordered by file path
width = 120               # Consistent line width (prevents rewrapping)
add_location = file       # Show file path only (not line numbers)

[update_catalog]
input_file = changedetectionio/translations/messages.pot
output_dir = changedetectionio/translations
domain = messages
width = 120
no_fuzzy_matching = true  # Avoids incorrect automatic matches

[compile_catalog]
directory = changedetectionio/translations
domain = messages
```

--------------------------------

### Minimal api.yaml for a custom processor

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Defines a schema for a custom processor and includes an example of how to use it when creating a watch.

```yaml
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 }
 }'
```

--------------------------------

### Regex Replace Example

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/templates/_common_fields.html

The `regex_replace` filter allows for pattern-based replacement of text within strings. This example demonstrates replacing all digits with a placeholder string.

```html
{{ "hello world 123" | regex_replace('[0-9]+', 'no-more-numbers') }}
```

--------------------------------

### Stab Shell Usage Example

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/templates/_stab.html

Demonstrates how to use the `stab_shell` macro to create a tabbed interface. It defines the shell ID and an array of tab objects, each with an ID, label, and optional icon.

```html
{% from '\_stab.html' import stab_shell, stab_pane %} {% call stab_shell('my-shell-id', [ {'id': 'overview', 'label': _('Overview'), 'icon': '✦'}, {'id': 'settings', 'label': _('Settings'), 'icon': '⚙'}, ]) %}
```

--------------------------------

### Import watch URLs with configuration

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Import a list of URLs to monitor with optional watch configuration. This endpoint allows bulk importing and applying settings like tags and proxies to multiple watches simultaneously.

```APIDOC
## POST /api/v1/import

### Description
Import a list of URLs to monitor with optional watch configuration. Accepts line-separated URLs in request body and allows applying settings via query parameters.

### Method
POST

### Endpoint
/api/v1/import

### Parameters
#### Query Parameters
- **tag_uuids** (string) - Optional - Tag UUID(s) to apply to imported watches (comma-separated for multiple). Example: tag_uuids=550e8400-e29b-41d4-a716-446655440000
- **tag** (string) - Optional - Tag name to apply to imported watches. Example: tag=production
- **proxy** (string) - Optional - Proxy key to use for imported watches. Example: proxy=proxy1
- **dedupe** (boolean) - Optional - Skip duplicate URLs (default: true)

#### Request Body
- **(text/plain)** - Required - A string containing line-separated URLs.

### Request Example
```bash
curl -X POST "http://localhost:5000/api/v1/import" \
  -H "Content-Type: text/plain" \
  -d "https://example.com\nhttps://example.org\nhttps://example.net"
```

### Response
#### Success Response (200)
Returns a list of UUIDs for the imported watches.

#### Response Example
```json
[
  "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
```
```

--------------------------------

### OpenCV Image Comparison Steps

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/processors/image_ssim_diff/README.md

Demonstrates the core image processing steps using OpenCV for difference calculation, including grayscale conversion, Gaussian blur, absolute difference, and thresholding. Configurable via OPENCV_BLUR_SIGMA and COMPARISON_THRESHOLD_OPENCV.

```python
# Convert to grayscale
gray_from = cv2.cvtColor(image_from, cv2.COLOR_RGB2GRAY)
gray_to = cv2.cvtColor(image_to, cv2.COLOR_RGB2GRAY)

# Apply Gaussian blur (reduces noise, controlled by OPENCV_BLUR_SIGMA env var)
gray_from = cv2.GaussianBlur(gray_from, (0, 0), sigma=0.8)
gray_to = cv2.GaussianBlur(gray_to, (0, 0), sigma=0.8)

# Calculate absolute difference
diff = cv2.absdiff(gray_from, gray_to)

# Apply threshold (default: 30)
_, thresh = cv2.threshold(diff, threshold, 255, cv2.THRESH_BINARY)

# Count changed pixels
change_percentage = (changed_pixels / total_pixels) * 100
```

--------------------------------

### Jinja2 Translation String Formatting

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/changedetectionio/translations/README.md

Demonstrates correct Jinja2 syntax for handling translatable strings, ensuring proper sentence structure and reordering of variables across languages. Use the 'GOOD' example to avoid fragments.

```jinja
{# BAD: three fragments; SOV languages can't reorder %(title)s relative to "URL or Title" #}
{{ _('URL or Title') }}{% if active_tag_uuid %} {{ _('in') }} '{{ active_tag.title }}'{% endif %}
```

```jinja
{# GOOD: branch between two complete msgids; each language can freely reorder %(title)s #}
{% if active_tag_uuid %}
  {{ _("URL or Title in '%(title)s'", title=active_tag.title) }}
{% else %}
  {{ _('URL or Title') }}
{% endif %}
```

--------------------------------

### Install Python Development Headers on iPadOS

Source: https://github.com/dgtlmoon/changedetection.io/wiki/iPadOS-Install-Notes---WIP

Attempt to install Python development headers. This may resolve issues related to building Python packages that require C extensions.

```shell
apk get python3-dev
```

--------------------------------

### Set BASE_URL via Environment Variable

Source: https://github.com/dgtlmoon/changedetection.io/wiki/Configurable-BASE_URL-setting

Configure the BASE_URL by exporting it as an environment variable. Include the port number if necessary.

```bash
export BASE_URL=https://mysite.com:5000
```

--------------------------------

### 200 OK Response Sample (JSON)

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

This is a sample JSON response for a successful request (HTTP 200). It outlines the structure of a change detection job configuration.

```json
{
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "date_created": 0,
  "url": "[http://example.com](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"
      }
    }
  }
}
```

--------------------------------

### Get Single Snapshot

Source: https://github.com/dgtlmoon/changedetection.io/blob/master/docs/api_v1/index.html

Retrieves a single snapshot from a web page change monitor. Use 'latest' for the most recent snapshot. The Watch History API can be used to get a list of timestamps to pass.

```APIDOC
## GET /watch/{uuid}/history/{timestamp}

### 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.

### Method
GET

### Endpoint
/watch/{uuid}/history/{timestamp}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - Web page change monitor (watch) unique ID
- **timestamp** (integer or string) - Required - Snapshot timestamp or 'latest'

#### Query Parameters
- **html** (string) - Optional - Set to '1' to return the last HTML.

### Response
#### Success Response (200)
- (text/plain) - Snapshot content

#### Response Example
```text
<html>...</html>
```
```