Page DeltasPage Deltas

API 参考

一个精简稳定的 REST API，用于管理监控器和渠道，以及轮询变更。覆盖与仪表盘相同的操作范围。

基本 URL

生产环境：https://api.pagedeltas.com。所有端点均带有 /api 前缀。成功的响应为 JSON 格式。

身份验证

在 Settings → API keys 中创建密钥（需要编辑者或管理员角色）。密钥在创建时仅显示一次 — 请立即复制。要撤销密钥，请在同一页面将其删除。

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

密钥的作用域限定为创建它的组织，并在该组织内以管理员级别的权限行事，与任何具体用户无关。它们不与成员绑定，因此移除团队成员不会撤销组织的密钥 — 您需要删除密钥本身才能切断访问权限。

错误

错误会返回非 2xx 的状态码。身份验证和权限错误将作为简短的纯文本消息返回（例如 unauthorized、forbidden）；配额和速率限制错误会返回一个包含消息和相关数字的小型 JSON 主体。请不要解析固定的错误包 — 根据 HTTP 状态码进行分支处理：

  • 400 — 请求格式错误（JSON 错误、URL 无效、缺少字段）。
  • 401 — 凭据丢失或无效。
  • 403 — 已通过身份验证，但您的角色缺乏执行此操作的权限。
  • 404 — 资源丢失或不在您的组织中。
  • 409 — 冲突（例如，监控器因反复被屏蔽而处于暂停状态）。
  • 422 — 超出配额（例如，您计划的监控器限制）。JSON 主体包含 current 和 limit。
  • 429 — 速率受限（手动检查）。请退避并在 Retry-After 指定的延迟后重试。

配额错误示例 (422)：

{
  "error": "plan_url_limit exceeded",
  "current": 100,
  "limit": 100,
  "message": "Creating this monitor would exceed your plan's monitor limit (100)."
}

端点参考

方法与路径描述
GET /api/monitors列出您组织中的监控器。
POST /api/monitors创建单个监控器。
GET /api/monitors/{id}获取单个监控器。
PATCH /api/monitors/{id}更新 url、nl_description、filter_prompt、css_selector、xpath_selector、status。
DELETE /api/monitors/{id}删除监控器及其历史记录。
POST /api/monitors/{id}/check-now绕过计划时间表，将立即检查排入队列（受速率限制，见下文）。
GET /api/monitors/{id}/changes列出针对某个监控器检测到的变更（支持 ?limit=，最大 100）。
POST /api/monitors/import通过多部分 CSV 上传进行批量导入（file 字段）。
POST /api/monitors/bulk-pause, bulk-resume, bulk-delete将操作应用于监控器 ID 列表。
GET|PUT /api/monitors/{id}/alert-channels读取或替换监控器的渠道覆盖设置。
GET /api/alert-channels列出通知渠道。
POST /api/alert-channels创建渠道。
PATCH|DELETE /api/alert-channels/{id}更新或删除渠道。
POST /api/alert-channels/{id}/test发送测试有效负载以验证交付情况。
GET|POST /api/sitemap-monitors列出或创建站点地图 (sitemap) 监控器。
POST /api/sitemap-monitors/import通过多部分 CSV 上传批量创建站点地图监控器（file 字段）。
GET|POST|DELETE /api/tokens列出、创建和删除 API 密钥。
GET /api/billing/plan您组织当前的计划和限制。
GET /api/plans公开 — 列出可用计划（无需身份验证）。

示例 — 创建监控器

curl -X POST https://api.pagedeltas.com/api/monitors \
  -H "Authorization: Bearer $PAGEDELTAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "nl_description": "Competitor pricing; alert on plan or price changes",
    "filter_prompt": "Alert on plan or price changes; ignore copy tweaks",
    "channel_ids": []
  }'

可选字段：filter_prompt、css_selector、xpath_selector、is_pdf 和 channel_ids（每个监控器的渠道覆盖设置；省略则使用组织默认值）。没有 frequency（频率）参数 — 检查是自适应调度的。

示例 — 轮询变更

GET /api/monitors/01HW2X.../changes?limit=50
Authorization: Bearer $PAGEDELTAS_TOKEN

首先返回最新的变更（默认 50，最大 100）。没有游标 (cursor) — 通过调整 limit 并追踪您已看过的最新 detected_at 来进行分页。

{
  "changes": [
    {
      "id": "01HW3...",
      "detected_at": "2026-06-01T08:42:00Z",
      "summary": "Pro plan increased from $29 to $39/month."
    }
  ]
}

速率限制

目前对读写端点没有单密钥速率限制。唯一的例外是手动检查：

  • 立即检查 (Check-now)： 1 次请求 / 分钟 / 监控器。

当您达到该限制时，响应状态码为 429，并包含以秒为单位的 Retry-After 标头。在调用其他端点时，仍请保持合理的请求速率。

版本控制

我们的目标是保持该 API 表面的稳定。可能会在不事先通知的情况下添加新字段和端点，因此请编写能够忽略未知 JSON 字段的客户端代码。

API 参考 · 文档 · Page Deltas