# ChangeDetection.io API

- ChangeDetection.io Web page monitoring and notifications API
  - Where to find my API key?
  - Connection URL
  - Authentication
- Watch Management
  - getList all watches
  - postCreate a new watch
  - getGet single watch
  - putUpdate watch
  - delDelete watch
- Watch History
  - getGet watch history
- Snapshots
  - getGet single snapshot
- Favicon
  - getGet watch favicon
- Group / Tag Management
  - getList all tags
  - postCreate tag
  - getGet single tag
  - putUpdate tag
  - delDelete tag
- Notifications
  - getGet notification URLs
  - postAdd notification URLs
  - putReplace notification URLs
  - delDelete notification URLs
- Search
  - getSearch watches
- Import
  - postImport watch URLs
- System Information
  - getGet system information

API docs by Redocly

# ChangeDetection.io API (0.1.0)

Download OpenAPI specification:

URL: https://github.com/dgtlmoon/changedetection.io License: Apache 2.0

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

## Watch Management

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.

## List all watches

Return concise list of available web page change monitors (watches) and basic info

##### Authorizations:

ApiKeyAuth

##### query Parameters

recheck_all | string Value: "1" Set to 1 to force recheck of all watches
tag | string Tag name to filter results

### Responses

Development server

http://localhost:5000/api/v1/watch

Production server

https://yourdomain.com/api/v1/watch

Custom server

{protocol}://{host}/api/v1/watch

### Request samples

- curl
- Python

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

### Response samples

- 200

Content type
application/json
`
{

- "095be615-a8ad-4c33-8e9c-c7612fbf6c9f":
  {
  - "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  - "url": "http://example.com",
  - "title": "Example Website Monitor",
  - "tag": "550e8400-e29b-41d4-a716-446655440000",
  - "tags":
    [
    - "550e8400-e29b-41d4-a716-446655440000"
    ],
  - "paused": false,
  - "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": "https://news.example.org",
  - "title": "News Site Tracker",
  - "tag": "330e8400-e29b-41d4-a716-446655440001",
  - "tags":
    [
    - "330e8400-e29b-41d4-a716-446655440001"
    ],
  - "paused": false,
  - "muted": true,
  - "method": "GET",
  - "fetch_backend": "html_webdriver",
  - "last_checked": 1640998800,
  - "last_changed": 1640995200
  }

}`

## Create a new watch

Create a single web page change monitor (watch). Requires at least 'url' to be set.

##### Authorizations:

ApiKeyAuth

##### Request Body schema: application/json
required

url required | string <uri> <= 5000 characters URL to monitor for changes
title | string <= 5000 characters Custom title for the web page change monitor (watch)
tag | string <= 5000 characters Tag UUID to associate with this web page change monitor (watch)
tags | Array of strings Array of tag UUIDs
paused | boolean Whether the web page change monitor (watch) is paused
muted | boolean Whether notifications are muted
method | string Enum: "GET" "POST" "DELETE" "PUT" HTTP method to use
fetch_backend | string Enum: "html_requests" "html_webdriver" Backend to use for fetching content
| object HTTP headers to include in requests
body | string <= 5000 characters HTTP request body
proxy | string <= 5000 characters Proxy configuration
webdriver_delay | integer Delay in seconds for webdriver
webdriver_js_execute_code | string <= 5000 characters JavaScript code to execute
| object Time intervals between checks
notification_urls | Array of strings Notification URLs for this web page change monitor (watch)
notification_title | string <= 5000 characters Custom notification title
notification_body | string <= 5000 characters Custom notification body
notification_format | string Enum: "Text" "HTML" "Markdown" Format for notifications
track_ldjson_price_data | boolean Whether to track JSON-LD price data
| Array of objects Browser automation steps

### Responses

Development server

http://localhost:5000/api/v1/watch

Production server

https://yourdomain.com/api/v1/watch

Custom server

{protocol}://{host}/api/v1/watch

### Request samples

- Payload
- curl
- Python

Content type
application/json
`
{

- "url": "https://example.com",
- "title": "Example Site Monitor",
- "time_between_check":
  {
  - "hours": 1
  }

}`

## Get single watch

Retrieve web page change monitor (watch) information and set muted/paused status. Returns the FULL Watch JSON.

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Web page change monitor (watch) unique ID

##### query Parameters

recheck | string Enum: "1" "true" Recheck this web page change monitor (watch)
paused | string Enum: "paused" "unpaused" Set pause state
muted | string Enum: "muted" "unmuted" Set mute state

### Responses

Development server

http://localhost:5000/api/v1/watch/{uuid}

Production server

https://yourdomain.com/api/v1/watch/{uuid}

Custom server

{protocol}://{host}/api/v1/watch/{uuid}

### Request samples

- curl
- Python

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

### Response samples

- 200
- 404

Content type
application/json
`
{

- "url": "http://example.com",
- "title": "string",
- "tag": "string",
- "tags":
  [
  - "string"
  ],
- "paused": true,
- "muted": true,
- "method": "GET",
- "fetch_backend": "html_requests",
- "headers":
  {
  - "property1": "string",
  - "property2": "string"
  },
- "body": "string",
- "proxy": "string",
- "webdriver_delay": 0,
- "webdriver_js_execute_code": "string",
- "time_between_check":
  {
  - "weeks": 0,
  - "days": 0,
  - "hours": 0,
  - "minutes": 0,
  - "seconds": 0
  },
- "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"
    }
  ],
- "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
- "last_checked": 0,
- "last_changed": 0,
- "last_error": "string",
- "last_viewed": 0

}`

## Update watch

Update an existing web page change monitor (watch) using JSON. Accepts the same structure as returned in get single watch information.

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Web page change monitor (watch) unique ID

##### Request Body schema: application/json
required

url required | string <uri> <= 5000 characters URL to monitor for changes
title | string <= 5000 characters Custom title for the web page change monitor (watch)
tag | string <= 5000 characters Tag UUID to associate with this web page change monitor (watch)
tags | Array of strings Array of tag UUIDs
paused | boolean Whether the web page change monitor (watch) is paused
muted | boolean Whether notifications are muted
method | string Enum: "GET" "POST" "DELETE" "PUT" HTTP method to use
fetch_backend | string Enum: "html_requests" "html_webdriver" Backend to use for fetching content
| object HTTP headers to include in requests
body | string <= 5000 characters HTTP request body
proxy | string <= 5000 characters Proxy configuration
webdriver_delay | integer Delay in seconds for webdriver
webdriver_js_execute_code | string <= 5000 characters JavaScript code to execute
| object Time intervals between checks
notification_urls | Array of strings Notification URLs for this web page change monitor (watch)
notification_title | string <= 5000 characters Custom notification title
notification_body | string <= 5000 characters Custom notification body
notification_format | string Enum: "Text" "HTML" "Markdown" Format for notifications
track_ldjson_price_data | boolean Whether to track JSON-LD price data
| Array of objects Browser automation steps
last_viewed | integer >= 0 Unix timestamp in seconds of the last time the watch was viewed. Setting it to a value higher than `last_changed` in the "Update watch" endpoint marks the watch as viewed.

### Responses

Development server

http://localhost:5000/api/v1/watch/{uuid}

Production server

https://yourdomain.com/api/v1/watch/{uuid}

Custom server

{protocol}://{host}/api/v1/watch/{uuid}

### Request samples

- Payload
- curl
- Python

Content type
application/json
`
{

- "url": "http://example.com",
- "title": "string",
- "tag": "string",
- "tags":
  [
  - "string"
  ],
- "paused": true,
- "muted": true,
- "method": "GET",
- "fetch_backend": "html_requests",
- "headers":
  {
  - "property1": "string",
  - "property2": "string"
  },
- "body": "string",
- "proxy": "string",
- "webdriver_delay": 0,
- "webdriver_js_execute_code": "string",
- "time_between_check":
  {
  - "weeks": 0,
  - "days": 0,
  - "hours": 0,
  - "minutes": 0,
  - "seconds": 0
  },
- "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"
    }
  ],
- "last_viewed": 0

}`

## Delete watch

Delete a web page change monitor (watch) and all related history

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Web page change monitor (watch) unique ID

### Responses

Development server

http://localhost:5000/api/v1/watch/{uuid}

Production server

https://yourdomain.com/api/v1/watch/{uuid}

Custom server

{protocol}://{host}/api/v1/watch/{uuid}

### Request samples

- curl
- Python

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

## Watch History

Access historical snapshots and change data for your watches. View the complete timeline of detected changes and retrieve specific versions of monitored content for comparison and analysis.

## Get watch history

Get a list of all historical snapshots available for a web page change monitor (watch)

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Web page change monitor (watch) unique ID

### Responses

Development server

http://localhost:5000/api/v1/watch/{uuid}/history

Production server

https://yourdomain.com/api/v1/watch/{uuid}/history

Custom server

{protocol}://{host}/api/v1/watch/{uuid}/history

### Request samples

- curl
- Python

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

### Response samples

- 200

Content type
application/json
`
{

- "1640995200": "/path/to/snapshot1.txt",
- "1640998800": "/path/to/snapshot2.txt"

}`

## Snapshots

Retrieve individual snapshots of monitored content. Access both the processed change detection data and the raw HTML content that was captured during monitoring checks.

## Get single snapshot

Get single snapshot from web page change monitor (watch). Use 'latest' for the most recent snapshot.

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Web page change monitor (watch) unique ID
required | integer or string Snapshot timestamp or 'latest'

##### query Parameters

html | string Value: "1" Set to 1 to return the last HTML

### Responses

Development server

http://localhost:5000/api/v1/watch/{uuid}/history/{timestamp}

Production server

https://yourdomain.com/api/v1/watch/{uuid}/history/{timestamp}

Custom server

{protocol}://{host}/api/v1/watch/{uuid}/history/{timestamp}

### Request samples

- curl
- Python

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

## Favicon

Retrieve favicon images associated with monitored web pages. These are used in the dashboard interface to visually identify different watches in your monitoring list.

## Get watch favicon

Get the favicon for a web page change monitor (watch) as displayed in the watch overview list.

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Web page change monitor (watch) unique ID

### Responses

Development server

http://localhost:5000/api/v1/watch/{uuid}/favicon

Production server

https://yourdomain.com/api/v1/watch/{uuid}/favicon

Custom server

{protocol}://{host}/api/v1/watch/{uuid}/favicon

### Request samples

- curl
- Python

    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

## Group / Tag Management

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.

## List all tags

Return list of available tags/groups

##### Authorizations:

ApiKeyAuth

### Responses

Development server

http://localhost:5000/api/v1/tags

Production server

https://yourdomain.com/api/v1/tags

Custom server

{protocol}://{host}/api/v1/tags

### Request samples

- curl
- Python

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

### Response samples

- 200

Content type
application/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
  }

}`

## Create tag

Create a single tag/group

##### Authorizations:

ApiKeyAuth

##### Request Body schema: application/json
required

title required | string <= 5000 characters Tag title
notification_urls | Array of strings Default notification URLs for web page change monitors (watches) with this tag
notification_muted | boolean Whether notifications are muted for this tag

### Responses

Development server

http://localhost:5000/api/v1/tag

Production server

https://yourdomain.com/api/v1/tag

Custom server

{protocol}://{host}/api/v1/tag

### Request samples

- Payload
- curl
- Python

Content type
application/json
`
{

- "title": "Important Sites"

}`

### Response samples

- 201

Content type
application/json
`
{

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

}`

## Get single tag

Retrieve tag information, set notification_muted status, recheck all web page change monitors (watches) in tag.

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Tag unique ID

##### query Parameters

muted | string Enum: "muted" "unmuted" Set mute state
recheck | string Value: "true" Queue all web page change monitors (watches) with this tag for recheck

### Responses

Development server

http://localhost:5000/api/v1/tag/{uuid}

Production server

https://yourdomain.com/api/v1/tag/{uuid}

Custom server

{protocol}://{host}/api/v1/tag/{uuid}

### Request samples

- curl
- Python

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

### Response samples

- 200

Content type
application/json
`
{

- "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
- "title": "string",
- "notification_urls":
  [
  - "string"
  ],
- "notification_muted": true

}`

## Update tag

Update an existing tag using JSON

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Tag unique ID

##### Request Body schema: application/json
required

title required | string <= 5000 characters Tag title
notification_urls | Array of strings Default notification URLs for web page change monitors (watches) with this tag
notification_muted | boolean Whether notifications are muted for this tag

### Responses

Development server

http://localhost:5000/api/v1/tag/{uuid}

Production server

https://yourdomain.com/api/v1/tag/{uuid}

Custom server

{protocol}://{host}/api/v1/tag/{uuid}

### Request samples

- Payload
- curl
- Python

Content type
application/json
`
{

- "title": "string",
- "notification_urls":
  [
  - "string"
  ],
- "notification_muted": true

}`

## Delete tag

Delete a tag/group and remove it from all web page change monitors (watches)

##### Authorizations:

ApiKeyAuth

##### path Parameters

uuid required | string <uuid> Tag unique ID

### Responses

Development server

http://localhost:5000/api/v1/tag/{uuid}

Production server

https://yourdomain.com/api/v1/tag/{uuid}

Custom server

{protocol}://{host}/api/v1/tag/{uuid}

### Request samples

- curl
- Python

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

## Notifications

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.

## Get notification URLs

Return the notification URL list from the configuration

##### Authorizations:

ApiKeyAuth

### Responses

Development server

http://localhost:5000/api/v1/notifications

Production server

https://yourdomain.com/api/v1/notifications

Custom server

{protocol}://{host}/api/v1/notifications

### Request samples

- curl
- Python

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

### Response samples

- 200

Content type
application/json
`
{

- "notification_urls":
  [
  - "http://example.com"
  ]

}`

## Add notification URLs

Add one or more notification URLs to the configuration

##### Authorizations:

ApiKeyAuth

##### Request Body schema: application/json
required

notification_urls required | Array of strings <uri> [ items <uri > ] List of notification URLs

### Responses

Development server

http://localhost:5000/api/v1/notifications

Production server

https://yourdomain.com/api/v1/notifications

Custom server

{protocol}://{host}/api/v1/notifications

### Request samples

- Payload
- curl
- Python

Content type
application/json
`
{

- "notification_urls":
  [
  - "mailto:admin@example.com",
  - "discord://webhook_id/webhook_token"
  ]

}`

### Response samples

- 201

Content type
application/json
`
{

- "notification_urls":
  [
  - "http://example.com"
  ]

}`

## Replace notification URLs

Replace all notification URLs with the provided list (can be empty)

##### Authorizations:

ApiKeyAuth

##### Request Body schema: application/json
required

notification_urls required | Array of strings <uri> [ items <uri > ] List of notification URLs

### Responses

Development server

http://localhost:5000/api/v1/notifications

Production server

https://yourdomain.com/api/v1/notifications

Custom server

{protocol}://{host}/api/v1/notifications

### Request samples

- Payload
- curl
- Python

Content type
application/json
`
{

- "notification_urls":
  [
  - "http://example.com"
  ]

}`

### Response samples

- 200

Content type
application/json
`
{

- "notification_urls":
  [
  - "http://example.com"
  ]

}`

## Delete notification URLs

Delete one or more notification URLs from the configuration

##### Authorizations:

ApiKeyAuth

##### Request Body schema: application/json
required

notification_urls required | Array of strings <uri> [ items <uri > ] List of notification URLs

### Responses

Development server

http://localhost:5000/api/v1/notifications

Production server

https://yourdomain.com/api/v1/notifications

Custom server

{protocol}://{host}/api/v1/notifications

### Request samples

- Payload
- curl
- Python

Content type
application/json
`
{

- "notification_urls":
  [
  - "http://example.com"
  ]

}`

## Search

Search and filter your watches by URL patterns, titles, or tags. Useful for quickly finding specific monitors in large collections or identifying watches that match certain criteria.

## Search watches

Search web page change monitors (watches) by URL or title text

##### Authorizations:

ApiKeyAuth

##### query Parameters

q required | string Search query to match against watch URLs and titles
tag | string Tag name to limit results (name not UUID)
partial | string Allow partial matching of URL query

### Responses

Development server

http://localhost:5000/api/v1/search

Production server

https://yourdomain.com/api/v1/search

Custom server

{protocol}://{host}/api/v1/search

### Request samples

- curl
- Python

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

### Response samples

- 200

Content type
application/json
`
{

- "watches":
  {
  - "095be615-a8ad-4c33-8e9c-c7612fbf6c9f":
    {
    - "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    - "url": "http://example.com",
    - "title": "Example Website Monitor",
    - "tag": "550e8400-e29b-41d4-a716-446655440000",
    - "tags":
      [
      - "550e8400-e29b-41d4-a716-446655440000"
      ],
    - "paused": false,
    - "muted": false
    }
  }

}`

## Import

Bulk import multiple URLs for monitoring. Accepts plain text lists of URLs and can automatically apply tags, proxy settings, and other configurations to all imported watches simultaneously.

## Import watch URLs

Import a list of URLs to monitor. Accepts line-separated URLs in request body.

##### Authorizations:

ApiKeyAuth

##### query Parameters

tag_uuids | string Tag UUID to apply to imported web page change monitors (watches)
tag | string Tag name to apply to imported web page change monitors (watches)
proxy | string Proxy key to use for imported web page change monitors (watches)
dedupe | boolean Default: true Remove duplicate URLs (default true)

##### Request Body schema: text/plain
required

string

### Responses

Development server

http://localhost:5000/api/v1/import

Production server

https://yourdomain.com/api/v1/import

Custom server

{protocol}://{host}/api/v1/import

### Request samples

- Payload
- curl
- Python

Content type
text/plain

    https://example.com
    https://example.org
    https://example.net

### Response samples

- 200

Content type
application/json
`
[

- "497f6eca-6276-4993-bfeb-53cbbbba6f08"

]`

## System Information

Retrieve system status and statistics about your changedetection.io instance, including total watch counts, uptime information, and version details.

## Get system information

Return information about the current system state

##### Authorizations:

ApiKeyAuth

### Responses

Development server

http://localhost:5000/api/v1/systeminfo

Production server

https://yourdomain.com/api/v1/systeminfo

Custom server

{protocol}://{host}/api/v1/systeminfo

### Request samples

- curl
- Python

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

### Response samples

- 200

Content type
application/json
`
{

- "watch_count": 42,
- "tag_count": 5,
- "uptime": "2 days, 3:45:12",
- "version": "0.50.10"

}`