changedetection.io API v1 接口详解与使用指南

项目概述

changedetection.io 是一个开源的网页变更检测工具，它能够监控网页内容的变化并在检测到变更时发送通知。该项目提供的 API v1 版本允许开发者通过编程方式管理监控任务（watches），实现自动化集成。

API 基础信息

认证方式

所有 API 请求都需要在请求头中包含 x-api-key 字段，该密钥可以在 changedetection.io 的用户界面设置中找到。

请求格式

API 遵循 RESTful 设计风格，支持标准的 HTTP 方法（GET、POST、PUT、DELETE等），请求和响应数据格式均为 JSON。

核心功能接口

监控任务管理

创建监控任务

POST /api/v1/watch

请求参数：

• url (必填)：要监控的网页URL
• title (可选)：监控任务的显示名称
• tag (可选)：用于分类的标签
• fetch_backoff (可选)：重试间隔时间（秒）

响应示例：

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com",
  "title": "Example监控",
  "created": "2023-01-01T00:00:00Z"
}

获取监控任务列表

GET /api/v1/watch

查询参数：

• tag (可选)：按标签过滤
• paused (可选)：true/false，筛选暂停/运行中的任务

监控任务操作

获取单个任务详情

GET /api/v1/watch/{uuid}

返回指定UUID监控任务的完整配置和当前状态。

更新监控任务

PUT /api/v1/watch/{uuid}

支持更新监控任务的各项参数，如URL、标题、标签等。

删除监控任务

DELETE /api/v1/watch/{uuid}

删除指定UUID的监控任务。

历史记录管理

获取变更历史

GET /api/v1/watch/{uuid}/history

返回该监控任务的所有变更记录，包含时间戳和变更内容摘要。

高级功能接口

即时检测

POST /api/v1/watch/{uuid}/check

手动触发一次即时检测，无需等待预定检测时间。

暂停/恢复监控

POST /api/v1/watch/{uuid}/pause
POST /api/v1/watch/{uuid}/unpause

临时暂停或恢复指定监控任务。

最佳实践

1. 错误处理：所有API响应都包含标准HTTP状态码，4xx表示客户端错误，5xx表示服务器错误。

2. 频率限制：避免高频调用API，特别是即时检测接口。

3. 数据验证：创建或更新监控任务时，确保URL格式正确。

4. 密钥安全：妥善保管API密钥，避免泄露。

示例代码

使用cURL创建监控任务

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","title":"Example监控"}' \
  http://your-instance/api/v1/watch

使用Python获取监控列表

import requests

headers = {
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get('http://your-instance/api/v1/watch', headers=headers)
print(response.json())

注意事项

1. API v1版本仍在持续开发中，部分功能可能变更。

2. 大规模操作时建议分批处理，避免性能问题。

3. 监控敏感网站时请遵守相关法律法规和网站的使用条款。

通过这套API，开发者可以轻松将changedetection.io的网页监控能力集成到自己的系统中，实现自动化运维、内容监控等各类应用场景。