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

GET

endpoint

/api/v1/watch

Retrieve a list of all watches with basic information.

Query Parameters

tag

string

Filter watches by tag name (not UUID)

recheck_all

string

default:""

Set to "1" to trigger recheck of all watches

Response Fields

uuid

string

Unique identifier for the watch

url

string

The raw URL being monitored (may contain Jinja2 templates)

link

string

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

title

string

Custom title for the watch

page_title

string

HTML <title> tag from the page

Example

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

{
  "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

POST

endpoint

/api/v1/watch

Create a new watch to monitor a URL.

Request Body

url

string

required

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

title

string

Custom title for the watch

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

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

Get a Single Watch

GET

endpoint

/api/v1/watch/

Retrieve complete information about a specific watch.

Path Parameters

uuid

string

required

UUID of the watch

Query Parameters

recheck

string

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

paused

string

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

muted

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"

Update a Watch

PUT

endpoint

/api/v1/watch/

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

Path Parameters

uuid

string

required

UUID of the watch to update

Request Body

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

last_viewed

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

Delete a Watch

DELETE

endpoint

/api/v1/watch/

Delete a watch and all its history.

Path Parameters

uuid

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"

Get Watch History

GET

endpoint

/api/v1/watch//history

Get a list of all available snapshots for a watch.

Path Parameters

uuid

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"

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

Get Single Snapshot

GET

endpoint

/api/v1/watch//history/

Retrieve a specific snapshot by timestamp.

Path Parameters

uuid

string

required

UUID of the watch

timestamp

string | integer

required

Unix timestamp or "latest" for most recent snapshot

Query Parameters

html

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"

Get Snapshot Diff

GET

endpoint

/api/v1/watch//difference//

Compare two snapshots and get the differences.

Path Parameters

uuid

string

required

UUID of the watch

from_timestamp

string | integer

required

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

to_timestamp

string | integer

required

Ending timestamp or "latest" for most recent

Query Parameters

format

string

default:"text"

Output format: text, html, htmlcolor, or markdown

word_diff

boolean

default:false

Enable word-level diffing (vs line-level)

no_markup

boolean

default:false

Return raw diff without formatting

changesOnly

boolean

default:true

Show only changed lines (no context)

ignoreWhitespace

boolean

default:false

Ignore whitespace-only changes

removed

boolean

default:true

Include removed content

added

boolean

default:true

Include added content

replaced

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"

Get Watch Favicon

GET

endpoint

/api/v1/watch//favicon

Retrieve the favicon for a watch.

Path Parameters

uuid

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

Search Watches

GET

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

tag

string

Tag name to limit search results (name not UUID)

partial

boolean

default:"false"

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

Response

Returns matching watches with basic information:

uuid

string

Unique identifier for the watch

url

string

URL being monitored

title

string

Custom title for the watch

last_checked

integer

Unix timestamp of last check

last_changed

integer

Unix timestamp of last detected change

last_error

string

Most recent error message (if any)

viewed

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"

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"

Overview

Endpoints

​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

Build docs developers (and LLMs) love

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