API reference

A small, stable REST API for managing monitors and channels and polling for changes. Same surface area as the dashboard.

Base URL

Production: https://api.pagedeltas.com. All endpoints are prefixed with /api. Successful responses are JSON.

Authentication

Create a key from Settings → API keys (editor or admin role required). The key is shown once at creation — copy it immediately. To revoke a key, delete it from the same page.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are scoped to the organisation that created them and act with admin-level access within that organisation, independent of any user. They are not tied to a member, so removing a teammate does not revoke the org's keys — delete the key itself to cut off access.

Errors

Errors return a non-2xx status. Authentication and permission errors come back as a short plain-text message (e.g. unauthorized, forbidden); quota and rate-limit errors return a small JSON body with a message and the relevant numbers. Don't parse a fixed error envelope — branch on the HTTP status code:

400 — malformed request (bad JSON, invalid URL, missing field).
401 — missing or invalid credentials.
403 — authenticated but your role lacks permission for this action.
404 — resource missing or not in your organisation.
409 — conflict (e.g. the monitor is paused due to repeated blocks).
422 — a quota would be exceeded (e.g. your plan's monitor limit). The JSON body includes current and limit.
429 — rate limited (manual checks). Back off and retry after the delay in Retry-After.

Example quota error (422):

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

Endpoint reference

Method & path	Description
`GET /api/monitors`	List monitors in your organisation.
`POST /api/monitors`	Create a single monitor.
`GET /api/monitors/{id}`	Get a single monitor.
`PATCH /api/monitors/{id}`	Update `url`, `nl_description`, `filter_prompt`, `css_selector`, `xpath_selector`, `status`.
`DELETE /api/monitors/{id}`	Delete a monitor and its history.
`POST /api/monitors/{id}/check-now`	Enqueue an immediate check, bypassing the schedule (rate limited, see below).
`GET /api/monitors/{id}/changes`	List detected changes for a monitor (supports `?limit=`, max 100).
`POST /api/monitors/import`	Bulk import via multipart CSV upload (`file` field).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	Apply an action to a list of monitor ids.
`GET\|PUT /api/monitors/{id}/alert-channels`	Read or replace a monitor's channel overrides.
`GET /api/alert-channels`	List notification channels.
`POST /api/alert-channels`	Create a channel.
`PATCH\|DELETE /api/alert-channels/{id}`	Update or delete a channel.
`POST /api/alert-channels/{id}/test`	Send a test payload to verify delivery.
`GET\|POST /api/sitemap-monitors`	List or create sitemap monitors.
`POST /api/sitemap-monitors/import`	Bulk-create sitemap monitors via multipart CSV upload (`file` field).
`GET\|POST\|DELETE /api/tokens`	List, create, and delete API keys.
`GET /api/billing/plan`	Your organisation's current plan and limits.
`GET /api/plans`	Public — list available plans (no auth required).

Example — create a monitor

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": []
  }'

Optional fields: filter_prompt, css_selector, xpath_selector, is_pdf, and channel_ids (per-monitor channel overrides; omit to use the org defaults). There is no frequency — scheduling is adaptive.

Example — poll for changes

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

Returns the most recent changes first (default 50, max 100). There is no cursor — page by adjusting limit and tracking the latest detected_at you've already seen.

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

Rate limits

There are currently no per-key rate limits on the read and write endpoints. The one exception is manual checks:

Check-now: 1 request / minute / monitor.

When you hit that limit, the response is 429 with a Retry-After header in seconds. Please still rate-yourself sensibly on the other endpoints.

Versioning

We aim to keep this surface stable. New fields and endpoints may be added without notice, so write clients that ignore unknown JSON fields.