Importing Watches

Changedetection.io provides multiple methods to import large lists of URLs, making it easy to migrate from other services or set up bulk monitoring.

Import Methods

Excel Import (Recommended)

Import URLs from Excel .xlsx files with full configuration options:

Create Excel file with columns:
- URL (required) - Website URL to monitor
- Title - Watch title/name
- Tag - Comma-separated tags
- Fetch Backend - html_requests, playwright, webdriver, etc.
- Notification URLs - Apprise notification URLs
- Filters - CSS/XPath selectors
- Any other watch configuration fields
Upload via Web UI:
- Go to Import page
- Click Choose File and select your .xlsx file
- Click Import
- Review imported watches

Example Excel structure:

| URL                           | Title          | Tag            | Fetch Backend |
|-------------------------------|----------------|----------------|---------------|
| https://example.com/product1  | Product 1      | prices,urgent  | html_requests |
| https://example.com/product2  | Product 2      | prices         | playwright    |
| https://api.example.com/data  | API Endpoint   | api,monitoring | html_requests |

Excel import is recommended because it supports full configuration including tags, notifications, filters, and other watch settings.

Plaintext URL List

Import a simple list of URLs (one per line):

Create text file with URLs:

https://example.com
https://another-site.com
https://api.example.com/endpoint

Upload via Web UI:
- Go to Import page
- Paste URLs into text area (one per line)
- Click Import
Upload via File:
- Save URLs to .txt file
- Upload via Import page

Plaintext import creates watches with default settings. Configure individual watches after import.

API Import

Programmatically import URLs using the REST API.

Basic API Import

POST /api/v1/watch/import

endpoint

Import a list of URLs from plaintextRequest:

curl -X POST https://changedetection.example.com/api/v1/watch/import \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://example.com\nhttps://another-site.com'

Response (< 20 URLs):

[
  "uuid-1111-2222-3333-4444",
  "uuid-5555-6666-7777-8888"
]

Response (≥ 20 URLs - background processing):

{
  "status": "Importing 50 URLs in background",
  "count": 50
}

Import with Configuration

Use query parameters to configure imported watches: Available parameters:

tag - Assign tag(s) to all imported watches
tag_uuids - Comma-separated tag UUIDs
dedupe - Skip duplicate URLs (default: true)
proxy - Proxy name from proxies.json
Any watch configuration field (see below)

Example with tag:

curl -X POST "https://changedetection.example.com/api/v1/watch/import?tag=imported,batch-2024" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://example.com\nhttps://another-site.com'

Example with processor:

curl -X POST "https://changedetection.example.com/api/v1/watch/import?processor=text_json_diff" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://api.example.com/data\nhttps://api.example.com/users'

Example with fetch backend:

curl -X POST "https://changedetection.example.com/api/v1/watch/import?fetch_backend=playwright" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://example.com\nhttps://another-site.com'

Example with proxy:

curl -X POST "https://changedetection.example.com/api/v1/watch/import?proxy=socks5proxy" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://example.com\nhttps://another-site.com'

Advanced Configuration Parameters

tag

string

Comma-separated tags to assignExample:

?tag=production,api,critical

dedupe

boolean

default:"true"

Skip URLs that already exist in watchesExample:

?dedupe=false  # Allow duplicates

proxy

string

Proxy name from proxies.jsonExample:

?proxy=socks5proxy

Must match a proxy_name defined in your proxies.json.

processor

string

Content processor typeAvailable processors:

text_json_diff - JSON API monitoring
restock_diff - Product restock/price monitoring
text_content_diff - Text-only comparison

Example:

?processor=text_json_diff

fetch_backend

string

Content fetcher to useAvailable fetchers:

html_requests - Fast HTTP client (default)
playwright - Chrome browser via Playwright
webdriver - Chrome browser via Selenium
system - Use global default

Example:

?fetch_backend=playwright

notification_urls

array

Notification URLs (comma-separated or JSON array)Example (comma-separated):

?notification_urls=discord://webhook_id/token,mailto://user:[email protected]?to=[email protected]

Example (JSON array):

?notification_urls=["discord://webhook_id/token","mailto://[email protected]"]

method

string

default:"GET"

HTTP request methodValues: GET, POST, PUT, PATCH, DELETEExample:

?method=POST

headers

object

Custom HTTP headers (JSON object)Example:

?headers={"Authorization":"Bearer token123","X-Custom":"value"}

body

string

HTTP request body (for POST/PUT/PATCH)Example:

?body={"key":"value"}

time_between_check

object

Check interval configuration (JSON object)Format:

{
  "weeks": 0,
  "days": 0,
  "hours": 1,
  "minutes": 0,
  "seconds": 0
}

Example:

?time_between_check={"hours":6}

include_filters

array

CSS/XPath selectors to include (comma-separated)Example:

?include_filters=.price,.availability

subtractive_selectors

array

CSS/XPath selectors to excludeExample:

?subtractive_selectors=.ads,.footer

Complete API Import Example

curl -X POST "https://changedetection.example.com/api/v1/watch/import?tag=api-monitoring&processor=text_json_diff&fetch_backend=html_requests&time_between_check={\"hours\":1}&notification_urls=discord://1234567890/token" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://api.example.com/v1/users\nhttps://api.example.com/v1/products\nhttps://api.example.com/v1/orders'

Background Processing

For large imports (20+ URLs), changedetection.io automatically switches to background processing:

IMPORT_SWITCH_TO_BACKGROUND_THRESHOLD

integer

default:"20"

Number of URLs above which import switches to background processingBehavior:

< 20 URLs: Synchronous import, immediate response with UUIDs
≥ 20 URLs: Background thread, immediate HTTP 202 response

Response for background processing:

{
  "status": "Importing 50 URLs in background",
  "count": 50
}

Background imports are logged but don’t return watch UUIDs immediately. Check the watch list or logs to verify import completion.

Import from File

Import from a file on your local machine:

Using cURL

curl -X POST https://changedetection.example.com/api/v1/watch/import \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @urls.txt

Using Python

import requests

with open('urls.txt', 'r') as f:
    urls = f.read()

response = requests.post(
    'https://changedetection.example.com/api/v1/watch/import',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'text/plain'
    },
    data=urls
)

print(response.json())

Using JavaScript/Node.js

const fs = require('fs');
const axios = require('axios');

const urls = fs.readFileSync('urls.txt', 'utf-8');

axios.post('https://changedetection.example.com/api/v1/watch/import', urls, {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'text/plain'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Deduplication

By default, changedetection.io skips URLs that already exist:

dedupe

boolean

default:"true"

Skip duplicate URLs during importBehavior:

true (default) - Skip URLs that already exist in watches
false - Allow duplicate URLs (create multiple watches)

Example to allow duplicates:

curl -X POST "https://changedetection.example.com/api/v1/watch/import?dedupe=false" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://example.com\nhttps://example.com'

URL Validation

All imported URLs are validated:

Format validation: Must be valid HTTP/HTTPS URLs
Security validation: Private/reserved IPs blocked (unless ALLOW_IANA_RESTRICTED_ADDRESSES=true)
Protocol validation: Only http://, https://, and file:// (if enabled) are supported

Invalid URLs return 400 error:

{
  "error": "Invalid or unsupported URL - ftp://example.com"
}

Proxy Assignment

Assign proxies during import using the proxy parameter: Prerequisites:

Create proxies.json in datastore directory

Define proxy profiles:

[
  {
    "proxy_name": "proxy1",
    "proxy_url": "http://proxy1.example.com:8080"
  },
  {
    "proxy_name": "socks5proxy",
    "proxy_url": "socks5://user:[email protected]:1080"
  }
]

Import with proxy:

curl -X POST "https://changedetection.example.com/api/v1/watch/import?proxy=socks5proxy" \
  -H "Content-Type: text/plain" \
  -H "x-api-key: YOUR_API_KEY" \
  -d $'https://example.com\nhttps://another-site.com'

Error if proxy not found:

{
  "error": "Invalid proxy choice, currently supported proxies are 'proxy1, socks5proxy'"
}

Batch Import Script

Create a shell script to import URLs in batches:

#!/bin/bash

API_KEY="your-api-key-here"
BASE_URL="https://changedetection.example.com"
URL_FILE="urls.txt"
BATCH_SIZE=50

# Split URLs into batches
split -l $BATCH_SIZE "$URL_FILE" batch_

# Import each batch
for batch in batch_*; do
  echo "Importing $batch..."
  curl -X POST "$BASE_URL/api/v1/watch/import?tag=imported-$(date +%Y%m%d)" \
    -H "Content-Type: text/plain" \
    -H "x-api-key: $API_KEY" \
    --data-binary @"$batch"
  
  echo ""
  sleep 2  # Rate limit
done

# Cleanup
rm batch_*
echo "Import complete!"

Troubleshooting

Import Fails with 400 Error

Cause: Invalid URL format or unsupported protocol Solution:

Check URL format: https://example.com (not example.com)
Ensure protocol is HTTP/HTTPS
Remove any leading/trailing whitespace
Check for special characters that need URL encoding

Import Returns 400 “Invalid proxy choice”

Cause: Proxy name doesn’t exist in proxies.json Solution:

Verify proxies.json exists in datastore
Check proxy_name matches exactly (case-sensitive)
Restart changedetection.io after modifying proxies.json

Background Import Not Completing

Cause: Resource constraints or invalid URLs in batch Solution:

Check Docker logs: docker logs changedetection
Look for error messages about specific URLs
Reduce batch size
Check available disk space and memory

Duplicates Created Despite dedupe=true

Cause: URL normalization differences (trailing slash, query params) Solution:

Normalize URLs before import (add/remove trailing slashes consistently)
Consider using dedupe=false and cleaning up manually
Use API to check for duplicates first

Best Practices

Use Excel import for initial setup with full configuration
Test with small batch (5-10 URLs) before importing thousands
Tag imports by date or source for easier management
Enable deduplication to avoid duplicate watches
Validate URLs before import using a script
Monitor logs during large imports
Import during low-traffic periods
Backup datastore before large imports
Use background processing for large batches (20+ URLs)
Configure defaults (processor, fetch_backend) to reduce individual configuration

API Documentation - Complete API reference
Proxy Setup - Configure proxies for imported watches
Notifications Setup - Set up notifications during import
Environment Variables - Import-related configuration

Get Started

Installation

Core Features

Content Extraction

Browser Integration

Configuration

Advanced

Import Methods

Excel Import (Recommended)

Plaintext URL List

API Import

Basic API Import

Import with Configuration

Advanced Configuration Parameters

Complete API Import Example

Background Processing

Import from File

Using cURL

Using Python

Using JavaScript/Node.js

Deduplication

URL Validation

Proxy Assignment

Batch Import Script

Troubleshooting

Import Fails with 400 Error

Import Returns 400 “Invalid proxy choice”

Background Import Not Completing

Duplicates Created Despite dedupe=true

Best Practices

Build docs developers (and LLMs) love

Get Started

Installation

Core Features

Content Extraction

Browser Integration

Configuration

Advanced

​Import Methods

​Excel Import (Recommended)

​Plaintext URL List

​API Import

​Basic API Import

​Import with Configuration

​Advanced Configuration Parameters

​Complete API Import Example

​Background Processing

​Import from File

​Using cURL

​Using Python

​Using JavaScript/Node.js

​Deduplication

​URL Validation

​Proxy Assignment

​Batch Import Script

​Troubleshooting

​Import Fails with 400 Error

​Import Returns 400 “Invalid proxy choice”

​Background Import Not Completing

​Duplicates Created Despite dedupe=true

​Best Practices

​Related Documentation

Build docs developers (and LLMs) love

Import Methods

Excel Import (Recommended)

Plaintext URL List

API Import

Basic API Import

Import with Configuration

Advanced Configuration Parameters

Complete API Import Example

Background Processing

Import from File

Using cURL

Using Python

Using JavaScript/Node.js

Deduplication

URL Validation

Proxy Assignment

Batch Import Script

Troubleshooting

Import Fails with 400 Error

Import Returns 400 “Invalid proxy choice”

Background Import Not Completing

Duplicates Created Despite dedupe=true

Best Practices

Related Documentation