diff --git a/docs/api-spec.yaml b/docs/api-spec.yaml index d9d87aa4e..0ee11e0b9 100644 --- a/docs/api-spec.yaml +++ b/docs/api-spec.yaml @@ -28,7 +28,7 @@ info: For example: `x-api-key: YOUR_API_KEY` - version: 0.1.4 + version: 0.1.5 contact: name: ChangeDetection.io url: https://github.com/dgtlmoon/changedetection.io @@ -1503,46 +1503,92 @@ paths: post: operationId: importWatches tags: [Import] - summary: Import watch URLs - description: Import a list of URLs to monitor. Accepts line-separated URLs in request body. + summary: Import watch URLs with configuration + description: | + Import a list of URLs to monitor with optional watch configuration. Accepts line-separated URLs in request body. + + **Configuration via Query Parameters:** + + You can pass ANY watch configuration field as query parameters to apply settings to all imported watches. + All parameters from the Watch schema are supported (processor, fetch_backend, notification_urls, etc.). + + **Special Parameters:** + - `tag` / `tag_uuids` - Assign tags to imported watches + - `proxy` - Use specific proxy for imported watches + - `dedupe` - Skip duplicate URLs (default: true) + + **Type Conversion:** + - Booleans: `true`, `false`, `1`, `0`, `yes`, `no` + - Arrays: Comma-separated or JSON format (`[item1,item2]`) + - Objects: JSON format (`{"key":"value"}`) + - Numbers: Parsed as int or float x-code-samples: - lang: 'curl' source: | + # Basic import 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' + + # Import with processor and fetch backend + curl -X POST "http://localhost:5000/api/v1/import?processor=restock_diff&fetch_backend=html_webdriver" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: text/plain" \ + -d $'https://example.com\nhttps://example.org' + + # Import with multiple settings + curl -X POST "http://localhost:5000/api/v1/import?processor=restock_diff&paused=true&tag=production" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: text/plain" \ + -d $'https://example.com' - lang: 'Python' source: | import requests - + headers = { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'text/plain' } + + # Basic import urls = 'https://example.com\nhttps://example.org\nhttps://example.net' - response = requests.post('http://localhost:5000/api/v1/import', + response = requests.post('http://localhost:5000/api/v1/import', headers=headers, data=urls) print(response.json()) + + # Import with configuration + params = { + 'processor': 'restock_diff', + 'fetch_backend': 'html_webdriver', + 'paused': 'false', + 'tag': 'production' + } + response = requests.post('http://localhost:5000/api/v1/import', + headers=headers, params=params, data=urls) + print(response.json()) parameters: - name: tag_uuids in: query - description: Tag UUID to apply to imported web page change monitors (watches) + description: Tag UUID(s) to apply to imported watches (comma-separated for multiple) schema: type: string + example: "550e8400-e29b-41d4-a716-446655440000" - name: tag in: query - description: Tag name to apply to imported web page change monitors (watches) + description: Tag name to apply to imported watches schema: type: string + example: "production" - name: proxy in: query - description: Proxy key to use for imported web page change monitors (watches) + description: Proxy key to use for imported watches schema: type: string + example: "proxy1" - name: dedupe in: query - description: Remove duplicate URLs (default true) + description: Skip duplicate URLs (default true) schema: type: boolean default: true diff --git a/docs/api_v1/index.html b/docs/api_v1/index.html index 7e4915a1d..e50456e8c 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

ChangeDetection.io API (0.1.4)

Download OpenAPI specification:

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

ChangeDetection.io Web page monitoring and notifications API

ChangeDetection.io API (0.1.5)

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.

@@ -532,12 +532,12 @@ notification preferences, and content filtering options.

" class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Delay in seconds for webdriver

webdriver_js_execute_code
string <= 5000 characters

JavaScript code to execute

-
object

Time intervals between checks

+
object

Time intervals between checks. All fields must be non-negative. At least one non-zero value required when not using default settings.

time_between_check_use_default
boolean
Default: true

Whether to use global settings for time between checks - defaults to true if not set

-
notification_urls
Array of strings

Notification URLs for this web page change monitor (watch)

+
notification_urls
Array of strings <= 100 items [ items <= 1000 characters ]

Notification URLs for this web page change monitor (watch). Maximum 100 URLs.

notification_title
string <= 5000 characters

Custom notification title

notification_body
string <= 5000 characters

Format for notifications

track_ldjson_price_data
boolean

Whether to track JSON-LD price data

-
Array of objects

Browser automation steps

+
Array of objects <= 100 items

Browser automation steps. Maximum 100 steps allowed.

processor
string
Default: "text_json_diff"
Enum: "restock_diff" "text_json_diff"

Optional processor mode to use for change detection. Defaults to text_json_diff if not specified.

Responses

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
{
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "notification_muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "time_between_check_use_default": true,
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ],
  • "processor": "restock_diff",
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "last_checked": 0,
  • "last_changed": 0,
  • "last_error": "string",
  • "last_viewed": 0,
  • "link": "string"
}

Update watch

Response samples

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

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

@@ -612,12 +612,12 @@ notification preferences, and content filtering options.

" class="sc-eVqvcJ sc-fszimp kIppRw drqpJr">

Delay in seconds for webdriver

webdriver_js_execute_code
string <= 5000 characters

JavaScript code to execute

-
object

Time intervals between checks

+
object

Time intervals between checks. All fields must be non-negative. At least one non-zero value required when not using default settings.

time_between_check_use_default
boolean
Default: true

Whether to use global settings for time between checks - defaults to true if not set

-
notification_urls
Array of strings

Notification URLs for this web page change monitor (watch)

+
notification_urls
Array of strings <= 100 items [ items <= 1000 characters ]

Notification URLs for this web page change monitor (watch). Maximum 100 URLs.

notification_title
string <= 5000 characters

Custom notification title

notification_body
string <= 5000 characters

Format for notifications

track_ldjson_price_data
boolean

Whether to track JSON-LD price data

-
Array of objects

Browser automation steps

+
Array of objects <= 100 items

Browser automation steps. Maximum 100 steps allowed.

processor
string
Default: "text_json_diff"
Enum: "restock_diff" "text_json_diff"

Optional processor mode to use for change detection. Defaults to text_json_diff if not specified.

last_viewed
integer >= 0

Production server

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,
  • "notification_muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "time_between_check_use_default": true,
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ],
  • "processor": "restock_diff",
  • "last_viewed": 0
}

Delete watch

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

Request samples

Content type
application/json
{
  • "url": "http://example.com",
  • "title": "string",
  • "tag": "string",
  • "tags": [
    ],
  • "paused": true,
  • "notification_muted": true,
  • "method": "GET",
  • "fetch_backend": "html_requests",
  • "headers": {
    },
  • "body": "string",
  • "proxy": "string",
  • "webdriver_delay": 0,
  • "webdriver_js_execute_code": "string",
  • "time_between_check": {
    },
  • "time_between_check_use_default": true,
  • "notification_urls": [
    ],
  • "notification_title": "string",
  • "notification_body": "string",
  • "notification_format": "text",
  • "track_ldjson_price_data": true,
  • "browser_steps": [
    ],
  • "processor": "restock_diff",
  • "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

@@ -1066,16 +1066,48 @@ monitors in large collections or identifying watches that match certain criteria apply tags, proxy settings, and other configurations to all imported watches simultaneously.</p> ">

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)

+

Import watch URLs with configuration

Import a list of URLs to monitor with optional watch configuration. Accepts line-separated URLs in request body.

+

Configuration via Query Parameters:

+

You can pass ANY watch configuration field as query parameters to apply settings to all imported watches. +All parameters from the Watch schema are supported (processor, fetch_backend, notification_urls, etc.).

+

Special Parameters:

+
    +
  • tag / tag_uuids - Assign tags to imported watches
    • +
  • proxy - Use specific proxy for imported watches
    • +
  • dedupe - Skip duplicate URLs (default: true)
    • +
+

Type Conversion:

+
    +
  • Booleans: true, false, 1, 0, yes, no
    • +
  • Arrays: Comma-separated or JSON format ([item1,item2])
    • +
  • Objects: JSON format ({"key":"value"})
    • +
  • Numbers: Parsed as int or float
    • +
+
Authorizations:
ApiKeyAuth
query Parameters
tag_uuids
string
Example: tag_uuids=550e8400-e29b-41d4-a716-446655440000

Tag UUID(s) to apply to imported watches (comma-separated for multiple)

+
tag
string
Example: tag=production

Tag name to apply to imported watches

+
proxy
string
Example: proxy=proxy1

Proxy key to use for imported watches

+
dedupe
boolean
Default: true

Skip duplicate URLs (default true)

Request Body schema: text/plain
required
string

Responses

Response samples

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