Watch Management

Watches are the core of changedetection.io - each watch monitors a single URL for changes. Use these endpoints to create, retrieve, update, and delete watches programmatically.

List All Watches

endpoint

/api/v1/watch

Retrieve a list of all watches with basic information.

Query Parameters

string

Filter watches by tag name (not UUID)

string

default:""

Set to "1" to trigger recheck of all watches

Response Fields

string

Unique identifier for the watch

string

The raw URL being monitored (may contain Jinja2 templates)

string

The rendered URL (Jinja2 processed) - always use this for display

string

Custom title for the watch

string

HTML <title> tag from the page

array

Array of tag UUIDs associated with this watch

integer

Unix timestamp of last check

integer

Unix timestamp of last detected change

string | boolean

Last error message, false if no error, null if never checked

Example

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

import requests

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

{
  "095be615-a8ad-4c33-8e9c-c7612fbf6c9f": {
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "url": "http://example.com?id={{1+1}}",
    "link": "http://example.com?id=2",
    "title": "Example Website Monitor",
    "page_title": "Example Domain",
    "tags": ["550e8400-e29b-41d4-a716-446655440000"],
    "paused": false,
    "notification_muted": false,
    "last_checked": 1640995200,
    "last_changed": 1640995200,
    "last_error": false,
    "viewed": true
  }
}

Create a Watch

endpoint

/api/v1/watch

Create a new watch to monitor a URL.

Request Body

string

required

URL to monitor (must use http://, https://, or ftp:// protocol)

string

Custom title for the watch

array

Array of tag UUIDs to associate with this watch

string

Single tag UUID (alternative to tags array)

string

default:"text_json_diff"

Processor mode: text_json_diff or restock_diff

string

default:"system"

Fetcher to use: system, html_requests, html_webdriver, or extra_browser_*

boolean

default:false

Whether the watch is paused

boolean

default:false

Whether notifications are muted

array

Array of notification URLs (Apprise format)

object

Check interval with fields: weeks, days, hours, minutes, seconds

boolean

default:true

Use global check interval settings

array

CSS/XPath selectors to extract content

array

CSS/XPath selectors to remove content

array

Text patterns to ignore in change detection

array

Text patterns that must be present to trigger

Example

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

import requests

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.json())

{
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Get a Single Watch

endpoint

/api/v1/watch/

Retrieve complete information about a specific watch.

Path Parameters

string

required

UUID of the watch

Query Parameters

string

Set to "1" or "true" to trigger immediate recheck

string

Set to "paused" or "unpaused" to change pause state

string

Set to "muted" or "unmuted" to change mute state

Example

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

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

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'

# Get watch info
response = requests.get(
    f'http://localhost:5000/api/v1/watch/{uuid}',
    headers=headers
)
print(response.json())

# Trigger recheck
response = requests.get(
    f'http://localhost:5000/api/v1/watch/{uuid}',
    headers=headers,
    params={'recheck': '1'}
)
print(response.text)  # "OK"

Update a Watch

endpoint

/api/v1/watch/

Update an existing watch. Only include fields you want to change.

Path Parameters

string

required

UUID of the watch to update

Request Body

Accepts the same fields as Create Watch. Only specified fields will be updated.

integer

Unix timestamp to mark the watch as viewed (set higher than last_changed)

Example

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 '{
    "title": "Updated Monitor Title",
    "paused": false
  }'

import requests

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'
data = {
    'title': 'Updated Monitor Title',
    'paused': False
}

response = requests.put(
    f'http://localhost:5000/api/v1/watch/{uuid}',
    headers=headers,
    json=data
)
print(response.text)  # "OK"

Delete a Watch

endpoint

/api/v1/watch/

Delete a watch and all its history.

Path Parameters

string

required

UUID of the watch to delete

Example

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

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.status_code)  # 204

Get Watch History

endpoint

/api/v1/watch//history

Get a list of all available snapshots for a watch.

Path Parameters

string

required

UUID of the watch

Example

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

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())

{
  "1640995200": "/path/to/snapshot1.txt",
  "1640998800": "/path/to/snapshot2.txt",
  "1641002400": "/path/to/snapshot3.txt"
}

Get Single Snapshot

endpoint

/api/v1/watch//history/

Retrieve a specific snapshot by timestamp.

Path Parameters

string

required

UUID of the watch

string | integer

required

Unix timestamp or "latest" for most recent snapshot

Query Parameters

string

Set to "1" to return raw HTML instead of processed text

Example

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

# Get raw HTML
curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history/latest?html=1" \
  -H "x-api-key: YOUR_API_KEY"

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f'

# Get latest snapshot
response = requests.get(
    f'http://localhost:5000/api/v1/watch/{uuid}/history/latest',
    headers=headers
)
print(response.text)

# Get raw HTML
response = requests.get(
    f'http://localhost:5000/api/v1/watch/{uuid}/history/latest',
    headers=headers,
    params={'html': '1'}
)
print(response.text)

Get Snapshot Diff

endpoint

/api/v1/watch//difference//

Compare two snapshots and get the differences.

Path Parameters

string

required

UUID of the watch

string | integer

required

Starting timestamp or "previous" for second-most-recent

string | integer

required

Ending timestamp or "latest" for most recent

Query Parameters

string

default:"text"

Output format: text, html, htmlcolor, or markdown

boolean

default:false

Enable word-level diffing (vs line-level)

boolean

default:false

Return raw diff without formatting

boolean

default:true

Show only changed lines (no context)

boolean

default:false

Ignore whitespace-only changes

boolean

default:true

Include removed content

boolean

default:true

Include added content

boolean

default:true

Include replaced content

Example

# Compare previous 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"

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}/difference/previous/latest',
    headers=headers,
    params={'format': 'htmlcolor'}
)
print(response.text)

Get Watch Favicon

endpoint

/api/v1/watch//favicon

Retrieve the favicon for a watch.

Path Parameters

string

required

UUID of the watch

Example

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

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)

Search Watches

endpoint

/api/v1/search

Search for watches by URL or title text. Useful for finding specific monitors in large deployments.

Query Parameters

string

required

Search query to match against watch URLs and titles

string

Tag name to limit search results (name not UUID)

boolean

default:"false"

Allow partial matching of URL query (set to 1 or true)

Response

Returns matching watches with basic information:

string

Unique identifier for the watch

string

URL being monitored

string

Custom title for the watch

integer

Unix timestamp of last check

integer

Unix timestamp of last detected change

string

Most recent error message (if any)

boolean

Whether changes have been viewed

Examples

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

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())

const response = await fetch(
  'http://localhost:5000/api/v1/search?q=example.com',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

const results = await response.json();
console.log(results);

Use Cases

Find watches by domain

Search for all watches monitoring a specific domain:

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

Filter by tag

Search within a specific tag group:

curl -X GET "http://localhost:5000/api/v1/search?q=api&tag=production" \
  -H "x-api-key: YOUR_API_KEY"

Partial URL matching

Enable partial matching for more flexible searches:

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

​Watch Management

​List All Watches

​Query Parameters

​Response Fields

​Example

​Create a Watch

​Request Body

​Example

​Get a Single Watch

​Path Parameters

​Query Parameters

​Example

​Update a Watch

​Path Parameters

​Request Body

​Example

​Delete a Watch

​Path Parameters

​Example

​Get Watch History

​Path Parameters

​Example

​Get Single Snapshot

​Path Parameters

​Query Parameters

​Example

​Get Snapshot Diff

​Path Parameters

​Query Parameters

​Example

​Get Watch Favicon

​Path Parameters

​Example

​Search Watches

​Query Parameters

​Response

​Examples

​Use Cases

Watch Management

List All Watches

Query Parameters

Response Fields

Example

Create a Watch

Request Body

Example

Get a Single Watch

Path Parameters

Query Parameters

Example

Update a Watch

Path Parameters

Request Body

Example

Delete a Watch

Path Parameters

Example

Get Watch History

Path Parameters

Example

Get Single Snapshot

Path Parameters

Query Parameters

Example

Get Snapshot Diff

Path Parameters

Query Parameters

Example

Get Watch Favicon

Path Parameters

Example

Search Watches

Query Parameters

Response

Examples

Use Cases