From f4f716fffaa65480c7eb286f466e49c23595596b Mon Sep 17 00:00:00 2001 From: dgtlmoon Date: Sat, 23 Aug 2025 23:53:06 +0200 Subject: [PATCH] More openAPI fixes --- docs/api-spec.yaml | 435 ++++++++++++++++++++++++++++++++++++++++- docs/api_v1/index.html | 157 ++++++++++++--- 2 files changed, 565 insertions(+), 27 deletions(-) diff --git a/docs/api-spec.yaml b/docs/api-spec.yaml index e3d45edc6..cb3e9ce27 100644 --- a/docs/api-spec.yaml +++ b/docs/api-spec.yaml @@ -41,17 +41,80 @@ servers: description: Development server - url: https://yourdomain.com/api/v1 description: Production server + - url: '{protocol}://{host}/api/v1' + description: Custom server + variables: + protocol: + enum: + - http + - https + default: https + host: + default: yourdomain.com + description: Your changedetection.io host security: - ApiKeyAuth: [] +tags: + - name: Watch Management + description: | + 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. + + - name: Watch History + description: | + 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. + + - name: Snapshots + description: | + Retrieve individual snapshots of monitored content. Access both the processed change detection data and + the raw HTML content that was captured during monitoring checks. + + - name: Favicon + description: | + Retrieve favicon images associated with monitored web pages. These are used in the dashboard interface + to visually identify different watches in your monitoring list. + + - name: Group / Tag Management + description: | + 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. + + - name: Notifications + description: | + 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. + + - name: Search + description: | + 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. + + - name: Import + description: | + 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. + + - name: System Information + description: | + Retrieve system status and statistics about your changedetection.io instance, including total watch + counts, uptime information, and version details. + components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key - description: API key for authentication + description: | + API key for authentication. You can find your API key in the changedetection.io dashboard under Settings > API. + + Enter your API key in the "Authorize" button above to automatically populate all code examples. schemas: Watch: @@ -266,6 +329,18 @@ paths: tags: [Watch Management] summary: List all watches description: Return concise list of available watches and basic info + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/watch" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + import requests + + headers = {'x-api-key': 'YOUR_API_KEY'} + response = requests.get('http://localhost:5000/api/v1/watch', headers=headers) + print(response.json()) parameters: - name: recheck_all in: query @@ -316,6 +391,38 @@ paths: tags: [Watch Management] summary: Create a new watch description: Create a single watch. Requires at least 'url' to be set. + x-code-samples: + - lang: 'curl' + 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", + "title": "Example Site Monitor", + "time_between_check": { + "hours": 1 + } + }' + - lang: 'Python' + source: | + import requests + import json + + 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.text) requestBody: required: true content: @@ -344,9 +451,23 @@ paths: /watch/{uuid}: get: + operationId: getSingleWatch tags: [Watch Management] summary: Get single watch description: Retrieve watch information and set muted/paused status. Returns the FULL Watch JSON. + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + 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}', headers=headers) + print(response.json()) parameters: - name: uuid in: path @@ -392,9 +513,38 @@ paths: $ref: '#/components/schemas/Error' put: + operationId: updateWatch tags: [Watch Management] summary: Update watch - description: Update an existing watch using JSON. Accepts the same structure as returned in get single watch information. + description: Update an existing watch using JSON. Accepts the same structure as returned in [get single watch information](#operation/getSingleWatch). + x-code-samples: + - lang: 'curl' + source: | + 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 '{ + "url": "https://updated-example.com", + "title": "Updated Monitor", + "paused": false + }' + - lang: 'Python' + source: | + import requests + + headers = { + 'x-api-key': 'YOUR_API_KEY', + 'Content-Type': 'application/json' + } + uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f' + data = { + 'url': 'https://updated-example.com', + 'title': 'Updated Monitor', + 'paused': False + } + response = requests.put(f'http://localhost:5000/api/v1/watch/{uuid}', + headers=headers, json=data) + print(response.text) parameters: - name: uuid in: path @@ -424,6 +574,19 @@ paths: tags: [Watch Management] summary: Delete watch description: Delete a watch and all related history + x-code-samples: + - lang: 'curl' + source: | + curl -X DELETE "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + 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.text) parameters: - name: uuid in: path @@ -446,6 +609,19 @@ paths: tags: [Watch History] summary: Get watch history description: Get a list of all historical snapshots available for a watch + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + 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()) parameters: - name: uuid in: path @@ -472,6 +648,20 @@ paths: tags: [Snapshots] summary: Get single snapshot description: Get single snapshot from watch. Use 'latest' for the most recent snapshot. + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/watch/095be615-a8ad-4c33-8e9c-c7612fbf6c9f/history/latest" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + import requests + + headers = {'x-api-key': 'YOUR_API_KEY'} + uuid = '095be615-a8ad-4c33-8e9c-c7612fbf6c9f' + timestamp = 'latest' # or use specific timestamp like 1640995200 + response = requests.get(f'http://localhost:5000/api/v1/watch/{uuid}/history/{timestamp}', headers=headers) + print(response.text) parameters: - name: uuid in: path @@ -510,6 +700,21 @@ paths: tags: [Favicon] summary: Get watch favicon description: Get the favicon for a watch as displayed in the watch overview list. + x-code-samples: + - lang: 'curl' + source: | + 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 + - lang: 'Python' + source: | + 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) parameters: - name: uuid in: path @@ -534,6 +739,18 @@ paths: tags: [Group / Tag Management] summary: List all tags description: Return list of available tags/groups + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/tags" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + import requests + + headers = {'x-api-key': 'YOUR_API_KEY'} + response = requests.get('http://localhost:5000/api/v1/tags', headers=headers) + print(response.json()) responses: '200': description: List of tags @@ -560,6 +777,19 @@ paths: tags: [Group / Tag Management] summary: Get single tag description: Retrieve tag information, set notification_muted status, recheck all in tag. + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + import requests + + headers = {'x-api-key': 'YOUR_API_KEY'} + tag_uuid = '550e8400-e29b-41d4-a716-446655440000' + response = requests.get(f'http://localhost:5000/api/v1/tag/{tag_uuid}', headers=headers) + print(response.json()) parameters: - name: uuid in: path @@ -598,6 +828,32 @@ paths: tags: [Group / Tag Management] summary: Update tag description: Update an existing tag using JSON + x-code-samples: + - lang: 'curl' + source: | + curl -X PUT "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "title": "Updated Production Sites", + "notification_muted": false + }' + - lang: 'Python' + source: | + import requests + + headers = { + 'x-api-key': 'YOUR_API_KEY', + 'Content-Type': 'application/json' + } + tag_uuid = '550e8400-e29b-41d4-a716-446655440000' + data = { + 'title': 'Updated Production Sites', + 'notification_muted': False + } + response = requests.put(f'http://localhost:5000/api/v1/tag/{tag_uuid}', + headers=headers, json=data) + print(response.text) parameters: - name: uuid in: path @@ -622,6 +878,19 @@ paths: tags: [Group / Tag Management] summary: Delete tag description: Delete a tag/group and remove it from all watches + x-code-samples: + - lang: 'curl' + source: | + curl -X DELETE "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + import requests + + headers = {'x-api-key': 'YOUR_API_KEY'} + tag_uuid = '550e8400-e29b-41d4-a716-446655440000' + response = requests.delete(f'http://localhost:5000/api/v1/tag/{tag_uuid}', headers=headers) + print(response.text) parameters: - name: uuid in: path @@ -638,6 +907,28 @@ paths: tags: [Group / Tag Management] summary: Create tag description: Create a single tag/group + x-code-samples: + - lang: 'curl' + source: | + curl -X POST "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "title": "Important Sites" + }' + - lang: 'Python' + source: | + import requests + + headers = { + 'x-api-key': 'YOUR_API_KEY', + 'Content-Type': 'application/json' + } + tag_uuid = '550e8400-e29b-41d4-a716-446655440000' + data = {'title': 'Important Sites'} + response = requests.post(f'http://localhost:5000/api/v1/tag/{tag_uuid}', + headers=headers, json=data) + print(response.text) requestBody: required: true content: @@ -657,6 +948,18 @@ paths: tags: [Notifications] summary: Get notification URLs description: Return the notification URL list from the configuration + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/notifications" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + import requests + + headers = {'x-api-key': 'YOUR_API_KEY'} + response = requests.get('http://localhost:5000/api/v1/notifications', headers=headers) + print(response.json()) responses: '200': description: List of notification URLs @@ -669,6 +972,35 @@ paths: tags: [Notifications] summary: Add notification URLs description: Add one or more notification URLs to the configuration + x-code-samples: + - lang: 'curl' + source: | + curl -X POST "http://localhost:5000/api/v1/notifications" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "notification_urls": [ + "mailto:admin@example.com", + "discord://webhook_id/webhook_token" + ] + }' + - lang: 'Python' + source: | + import requests + + headers = { + 'x-api-key': 'YOUR_API_KEY', + 'Content-Type': 'application/json' + } + data = { + 'notification_urls': [ + 'mailto:admin@example.com', + 'discord://webhook_id/webhook_token' + ] + } + response = requests.post('http://localhost:5000/api/v1/notifications', + headers=headers, json=data) + print(response.json()) requestBody: required: true content: @@ -693,6 +1025,33 @@ paths: tags: [Notifications] summary: Replace notification URLs description: Replace all notification URLs with the provided list (can be empty) + x-code-samples: + - lang: 'curl' + source: | + curl -X PUT "http://localhost:5000/api/v1/notifications" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "notification_urls": [ + "mailto:newadmin@example.com" + ] + }' + - lang: 'Python' + source: | + import requests + + headers = { + 'x-api-key': 'YOUR_API_KEY', + 'Content-Type': 'application/json' + } + data = { + 'notification_urls': [ + 'mailto:newadmin@example.com' + ] + } + response = requests.put('http://localhost:5000/api/v1/notifications', + headers=headers, json=data) + print(response.json()) requestBody: required: true content: @@ -713,6 +1072,33 @@ paths: tags: [Notifications] summary: Delete notification URLs description: Delete one or more notification URLs from the configuration + x-code-samples: + - lang: 'curl' + source: | + curl -X DELETE "http://localhost:5000/api/v1/notifications" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "notification_urls": [ + "mailto:admin@example.com" + ] + }' + - lang: 'Python' + source: | + import requests + + headers = { + 'x-api-key': 'YOUR_API_KEY', + 'Content-Type': 'application/json' + } + data = { + 'notification_urls': [ + 'mailto:admin@example.com' + ] + } + response = requests.delete('http://localhost:5000/api/v1/notifications', + headers=headers, json=data) + print(response.status_code) requestBody: required: true content: @@ -730,6 +1116,20 @@ paths: tags: [Search] summary: Search watches description: Search watches by URL or title text + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/search?q=example.com" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + 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()) parameters: - name: q in: query @@ -770,6 +1170,25 @@ paths: tags: [Import] summary: Import watch URLs description: Import a list of URLs to monitor. Accepts line-separated URLs in request body. + x-code-samples: + - lang: 'curl' + source: | + curl -X POST "http://localhost:5000/api/v1/import" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: text/plain" \ + -d $'https://example.com\nhttps://example.org\nhttps://example.net' + - lang: 'Python' + source: | + import requests + + headers = { + 'x-api-key': 'YOUR_API_KEY', + 'Content-Type': 'text/plain' + } + urls = 'https://example.com\nhttps://example.org\nhttps://example.net' + response = requests.post('http://localhost:5000/api/v1/import', + headers=headers, data=urls) + print(response.json()) parameters: - name: tag_uuids in: query @@ -821,6 +1240,18 @@ paths: tags: [System Information] summary: Get system information description: Return information about the current system state + x-code-samples: + - lang: 'curl' + source: | + curl -X GET "http://localhost:5000/api/v1/systeminfo" \ + -H "x-api-key: YOUR_API_KEY" + - lang: 'Python' + source: | + import requests + + headers = {'x-api-key': 'YOUR_API_KEY'} + response = requests.get('http://localhost:5000/api/v1/systeminfo', headers=headers) + print(response.json()) responses: '200': description: System information diff --git a/docs/api_v1/index.html b/docs/api_v1/index.html index b18f2c738..29a1f9531 100644 --- a/docs/api_v1/index.html +++ b/docs/api_v1/index.html @@ -432,7 +432,7 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ -
API docs by Redocly
API docs by Redocly

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

List all watches

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 watches and basic info

Authorizations:
ApiKeyAuth
query Parameters
recheck_all
string
Value: "1"

Set to 1 to force recheck of all watches

@@ -478,7 +484,11 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Response samples

Content type
application/json
{
  • "095be615-a8ad-4c33-8e9c-c7612fbf6c9f": {
    },
  • "7c9e6b8d-f2a1-4e5c-9d3b-8a7f6e4c2d1a": {
    }
}

Create a new watch

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

Custom server

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

Request samples 

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

Response samples

Content type
application/json
{
  • "095be615-a8ad-4c33-8e9c-c7612fbf6c9f": {
    },
  • "7c9e6b8d-f2a1-4e5c-9d3b-8a7f6e4c2d1a": {
    }
}

Create a new watch

Create a single 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

@@ -528,7 +538,9 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Request samples

Content type
application/json
{
  • "url": "https://example.com",
  • "title": "Example Site Monitor",
  • "time_between_check": {
    }
}

Get single watch

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

Custom server

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

Request samples

Content type
application/json
{
  • "url": "https://example.com",
  • "title": "Example Site Monitor",
  • "time_between_check": {
    }
}

Get single watch

Retrieve watch information and set muted/paused status. Returns the FULL Watch JSON.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

@@ -546,8 +558,12 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Response samples

Content type
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "Text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ],
  • "last_checked": 0,
  • "last_changed": 0,
  • "last_error": "string"
}

Update watch

Update an existing watch using JSON. Accepts the same structure as returned in get single watch information.

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

Custom server

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

Request samples 

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

Response samples

Content type
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "Text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ],
  • "last_checked": 0,
  • "last_changed": 0,
  • "last_error": "string"
}

Update watch

Update an existing watch using JSON. Accepts the same structure as returned in get single watch information.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

Request Body schema: application/json
required
url
required
string <uri> <= 5000 characters

Development server

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

Production server

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

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "Text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ]
}

Delete watch

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

Custom server

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

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "Text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ]
}

Delete watch

Delete a watch and all related history

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

@@ -608,7 +626,15 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Watch History

Get watch history

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

Custom server

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

Request samples 

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 watch

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

@@ -620,7 +646,15 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Response samples

Content type
application/json
{
  • "1640995200": "/path/to/snapshot1.txt",
  • "1640998800": "/path/to/snapshot2.txt"
}

Snapshots

Get single snapshot

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

Custom server

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

Request samples 

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

Response samples

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 watch. Use 'latest' for the most recent snapshot.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

@@ -636,7 +670,15 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Favicon

Get watch favicon

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

Custom server

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

Request samples 

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 watch as displayed in the watch overview list.

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Watch unique ID

@@ -648,7 +690,18 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Group / Tag Management

List all tags

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

Custom server

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

Request samples 

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

Production server

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

Response samples

Content type
application/json
{
  • "550e8400-e29b-41d4-a716-446655440000": {
    },
  • "330e8400-e29b-41d4-a716-446655440001": {
    }
}

Get single tag

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

Custom server

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

Request samples 

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

Response samples

Content type
application/json
{
  • "550e8400-e29b-41d4-a716-446655440000": {
    },
  • "330e8400-e29b-41d4-a716-446655440001": {
    }
}

Get single tag

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

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Tag unique ID

@@ -672,7 +729,11 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Response samples

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

Update tag

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

Custom server

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

Request samples 

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

Response samples

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

Update tag

Update an existing tag using JSON

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Tag unique ID

@@ -690,7 +751,9 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Request samples

Content type
application/json
{
  • "title": "string",
  • "notification_urls": [
    ],
  • "notification_muted": true
}

Delete tag

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

Custom server

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

Request samples

Content type
application/json
{
  • "title": "string",
  • "notification_urls": [
    ],
  • "notification_muted": true
}

Delete tag

Delete a tag/group and remove it from all watches

Authorizations:
ApiKeyAuth
path Parameters
uuid
required
string <uuid>

Tag unique ID

@@ -700,7 +763,11 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Create tag

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

Custom server

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

Request samples 

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

Create tag

Create a single tag/group

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
title
required
string <= 5000 characters

Tag title

@@ -716,7 +783,15 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Request samples

Content type
application/json
{
  • "title": "Important Sites"
}

Notifications

Get notification URLs

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

Custom server

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

Request samples

Content type
application/json
{
  • "title": "Important Sites"
}

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.

+

Get notification URLs

Return the notification URL list from the configuration

Authorizations:
ApiKeyAuth

Responses

Production server

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

Response samples

Content type
application/json
{}

Add notification URLs

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

Custom server

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

Request samples 

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

Response samples

Content type
application/json
{}

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

@@ -736,7 +815,9 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Request samples

Content type
application/json
{
  • "notification_urls": [
    ]
}

Response samples

Content type
application/json
{}

Replace notification URLs

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

Custom server

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

Request samples

Content type
application/json
{
  • "notification_urls": [
    ]
}

Response samples

Content type
application/json
{}

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

@@ -748,7 +829,9 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete notification URLs

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

Custom server

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

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

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

@@ -760,7 +843,13 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Request samples

Content type
application/json
{}

Search

Search watches

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

Custom server

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

Request samples

Content type
application/json
{}

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 watches by URL or title text

Authorizations:
ApiKeyAuth
query Parameters
q
required
string

Search query to match against watch URLs and titles

@@ -774,7 +863,15 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Response samples

Content type
application/json
{
  • "watches": {
    }
}

Import

Import watch URLs

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

Custom server

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

Request samples 

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

Response samples

Content type
application/json
{
  • "watches": {
    }
}

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 watches

@@ -792,10 +889,16 @@ data-styled.g138[id="sc-enPhjR"]{content:"SikXG,"}/*!sc*/ " class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Development server

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

Production server

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

Request samples

Content type
text/plain
https://example.com
+
https://yourdomain.com/api/v1/import

Custom server

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

Request samples

Content type
text/plain
https://example.com
 https://example.org
 https://example.net
-

Response samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

System Information

Get system information

Response samples

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

Production server

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

Response samples

Content type
application/json
{
  • "watch_count": 42,
  • "tag_count": 5,
  • "uptime": "2 days, 3:45:12",
  • "version": "0.50.10"
}
+
https://yourdomain.com/api/v1/systeminfo

Custom server

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

Request samples 

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

Response samples

Content type
application/json
{
  • "watch_count": 42,
  • "tag_count": 5,
  • "uptime": "2 days, 3:45:12",
  • "version": "0.50.10"
}