API Documentation
Introduction
Watch
post Create a single watch
delete Delete a watch and related history
put Update watch information
get Single watch - get data, recheck, pause, mute.
Watch History
get Get a list of all historical snapshots available for a watch
Snapshots
get Get single snapshot from watch
Favicon
get Get Favicon for a watch
Watch Management
get List watches
Group / Tag
post Create a single tag
delete Delete a tag and remove it from all watches
get Single tag - Get data, toggle notification muting, recheck all.
put Update tag information
Group / Tag Management
get List tags
Import
post Import a list of watched URLs
Notifications
post Create Notification URLs
delete Delete Notification URLs
get Return Notification URL List
put Replace Notification URLs
Search
get Search for watches
System Information
get Return system info

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 examples to help you.

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.

Where to find the API key

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

post /api/v1/watch

Create

Requires atleast `url` set, can accept the same structure as get single watch information to create.

Success Responses
200 String OK Was created
500 String ERR Some other error
Example
curl http://localhost:5000/api/v1/watch -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json" -d '{"url": "https://my-nice.com" , "tag": "nice list"}'

delete /api/v1/watch/:uuid

Delete
Parameters
Name Type Required Description
uuid uuid Required Watch unique ID.
Success Responses
200 String OK Was deleted
Example
curl http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091 -X DELETE -H"x-api-key:813031b16330fe25e3780cf0325daa45"

put /api/v1/watch/:uuid

Update a watch

Updates an existing watch using JSON, accepts the same structure as returned in get single watch information

Parameters
Name Type Required Description
uuid uuid Required Watch unique ID.
Success Responses
200 String OK Was updated
500 String ERR Some other error
Example
Update (PUT)
curl http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091 -X PUT -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json" -d '{"url": "https://my-nice.com" , "tag": "new list"}'

get /api/v1/watch/:uuid

Watch

Retrieve watch information and set muted/paused status

Parameters
Name Type Required Description
uuid uuid Required Watch unique ID.
Query Parameters
Name Type Required Description
recheck Boolean Optional Recheck this watch `recheck=1`
paused String Optional =`paused` or =`unpaused` , Sets the PAUSED state
muted String Optional =`muted` or =`unmuted` , Sets the MUTE NOTIFICATIONS state
Success Responses
200 String OK When paused/muted/recheck operation OR full JSON object of the watch
200 JSON WatchJSON JSON Full JSON object of the watch
Example
curl http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091  -H"x-api-key:813031b16330fe25e3780cf0325daa45"
curl "http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091?muted=unmuted"  -H"x-api-key:813031b16330fe25e3780cf0325daa45"
curl "http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091?paused=unpaused"  -H"x-api-key:813031b16330fe25e3780cf0325daa45"

Watch History

get /api/v1/watch/<string:uuid>/history

Get list of available stored snapshots for watch

Requires `uuid`, returns list

Success Responses
200 String OK
404 String ERR Not found
Example
Request 
curl http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091/history -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json"
Response 
{
  "1676649279": "/tmp/data/6a4b7d5c-fee4-4616-9f43-4ac97046b595/cb7e9be8258368262246910e6a2a4c30.txt",
  "1677092785": "/tmp/data/6a4b7d5c-fee4-4616-9f43-4ac97046b595/e20db368d6fc633e34f559ff67bb4044.txt",
  "1677103794": "/tmp/data/6a4b7d5c-fee4-4616-9f43-4ac97046b595/02efdd37dacdae96554a8cc85dc9c945.txt"
}

Snapshots

get /api/v1/watch/<string:uuid>/history/<int:timestamp>

Get single snapshot content

Requires watch `uuid` and `timestamp`. `timestamp` of "`latest`" for latest available snapshot, or use the list returned here

Parameters
Name Type Required Description
html String Optional Optional Set to =1 to return the last HTML (only stores last 2 snapshots, use `latest` as timestamp)
Success Responses
200 String OK
404 String ERR Not found
Example
curl http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091/history/1677092977 -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json"

Favicon

get /api/v1/watch/<string:uuid>/favicon

Get latest Favicon

Requires watch `uuid`

Success Responses
200 String OK
404 String ERR Not found
Example
curl http://localhost:5000/api/v1/watch/cc0cfffa-f449-477b-83ea-0caafd1dc091/favicon -H"x-api-key:813031b16330fe25e3780cf0325daa45"

Watch Management

get /api/v1/watch

ListWatches

Return concise list of available watches and some very basic info

Parameters
Name Type Required Description
recheck_all String Optional Optional Set to =1 to force recheck of all watches
tag String Optional Optional name of tag to limit results
Success Responses
200 String OK JSON dict
Example
Request 
curl http://localhost:5000/api/v1/watch -H"x-api-key:813031b16330fe25e3780cf0325daa45"
Response 
{
  "6a4b7d5c-fee4-4616-9f43-4ac97046b595": {
    "last_changed": 1677103794,
    "last_checked": 1677103794,
    "last_error": false,
    "title": "",
    "url": "http://www.quotationspage.com/random.php"
  },
  "e6f5fd5c-dbfe-468b-b8f3-f9d6ff5ad69b": {
    "last_changed": 0,
    "last_checked": 1676662819,
    "last_error": false,
    "title": "QuickLook",
    "url": "https://github.com/QL-Win/QuickLook/tags"
  }
}

Group / Tag

post /api/v1/watch

Create
Success Responses
200 String OK Was created
500 String ERR Some other error
Example
curl http://localhost:5000/api/v1/watch -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json" -d '{"name": "Work related"}'

delete /api/v1/tag/:uuid

DeleteTag
Parameters
Name Type Required Description
uuid uuid Required Tag unique ID.
Success Responses
200 String OK Was deleted
Example
curl http://localhost:5000/api/v1/tag/cc0cfffa-f449-477b-83ea-0caafd1dc091 -X DELETE -H"x-api-key:813031b16330fe25e3780cf0325daa45"

get /api/v1/tag/:uuid

Tag

Retrieve tag information, set notification_muted status, recheck all in tag.

Parameters
Name Type Required Description
uuid uuid Required Tag unique ID.
Query Parameters
Name Type Required Description
muted String Optional =`muted` or =`unmuted` , Sets the MUTE NOTIFICATIONS state
recheck String Optional = True, Queue all watches with this tag for recheck
Success Responses
200 String OK When muted operation OR full JSON object of the tag
200 JSON TagJSON JSON Full JSON object of the tag

put /api/v1/tag/:uuid

UpdateTag

Updates an existing tag using JSON

Parameters
Name Type Required Description
uuid uuid Required Tag unique ID.
Success Responses
200 String OK Was updated
500 String ERR Some other error
Example
Request 
curl http://localhost:5000/api/v1/tag/cc0cfffa-f449-477b-83ea-0caafd1dc091 -X PUT -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json" -d '{"title": "New Tag Title"}'
Response 
"OK"

Group / Tag Management

get /api/v1/tags

ListTags

Return list of available tags

Success Responses
200 String OK JSON dict
Example
Request 
curl http://localhost:5000/api/v1/tags -H"x-api-key:813031b16330fe25e3780cf0325daa45"
Response 
{
  "cc0cfffa-f449-477b-83ea-0caafd1dc091": {
    "title": "Tech News",
    "notification_muted": false,
    "date_created": 1677103794
  },
  "e6f5fd5c-dbfe-468b-b8f3-f9d6ff5ad69b": {
    "title": "Shopping",
    "notification_muted": true,
    "date_created": 1676662819
  }
}

Import

post /api/v1/import

Import

Accepts a line-feed separated list of URLs to import, additionally with ?tag_uuids=(tag id), ?tag=(name), ?proxy={key}, ?dedupe=true (default true) one URL per line.

Success Responses
200 List OK List of watch UUIDs added
500 String ERR Some other error
Example
curl http://localhost:5000/api/v1/import --data-binary @list-of-sites.txt -H"x-api-key:8a111a21bc2f8f1dd9b9353bbd46049a"

Notifications

post /api/v1/notifications

CreateBatch

Add one or more notification URLs from the configuration

Success Responses
201 Object[] notification_urls List of added notification URLs
Error Responses
400 String Invalid input
Example
curl http://localhost:5000/api/v1/notifications/batch -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json" -d '{"notification_urls": ["url1", "url2"]}'

delete /api/v1/notifications

Delete

Deletes one or more notification URLs from the configuration

Parameters
Name Type Required Description
notification_urls String[] Required The notification URLs to delete.
Success Responses
204 String OK Deleted
Error Responses
400 String No matching notification URLs found.
Example
curl http://localhost:5000/api/v1/notifications -X DELETE -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json" -d '{"notification_urls": ["url1", "url2"]}'

get /api/v1/notifications

Get

Return the Notification URL List from the configuration

Example
curl http://localhost:5000/api/v1/notifications -H"x-api-key:813031b16330fe25e3780cf0325daa45"
HTTP/1.0 200
{
'notification_urls': ["notification-urls-list"]
}

put /api/v1/notifications

Replace

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

Success Responses
200 Object[] notification_urls List of current notification URLs
Error Responses
400 String Invalid input
Example
curl -X PUT http://localhost:5000/api/v1/notifications -H"x-api-key:813031b16330fe25e3780cf0325daa45" -H "Content-Type: application/json" -d '{"notification_urls": ["url1", "url2"]}'

Search

get /api/v1/search

Search

Search watches by URL or title text

Query Parameters
Name Type Required Description
q String Required Search query to match against watch URLs and titles
tag String Optional Optional name of tag to limit results (name not UUID)
partial String Optional Allow partial matching of URL query
Success Responses
200 Object JSON Object containing matched watches
Example
curl "http://localhost:5000/api/v1/search?q=https://example.com/page1" -H"x-api-key:813031b16330fe25e3780cf0325daa45"
curl "http://localhost:5000/api/v1/search?q=https://example.com/page1?tag=Favourites" -H"x-api-key:813031b16330fe25e3780cf0325daa45"
curl "http://localhost:5000/api/v1/search?q=https://example.com?partial=true" -H"x-api-key:813031b16330fe25e3780cf0325daa45"

System Information

get /api/v1/systeminfo

Get Info

Return some info about the current system state

Example
curl http://localhost:5000/api/v1/systeminfo -H"x-api-key:813031b16330fe25e3780cf0325daa45"
HTTP/1.0 200
{
'queue_size': 10 ,
'overdue_watches': ["watch-uuid-list"],
'uptime': 38344.55,
'watch_count': 800,
'version': "0.40.1"
}