Integration · REST API

REST API for automated website change detection.

REST API for automated website change detection in your deploys. Manage websites, groups and URLs, take before and after screenshots around a release, read the change percentages and manage subaccounts, from GitHub Actions, GitLab CI or your own deployment tools.

curl -X POST https://api.webchangedetector.com/api/v2/screenshots/take \
  -H "Authorization: Bearer $WCD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group_ids": ["your-group-id"], "sc_type": "pre"}'

{ "batch": "your-batch-id", "amount_screenshots": 42 }
What you get

Automate your visual checks.

Core resources

Manage websites, groups and URLs (add them from a sitemap or sync them), AI Rules, webhooks, subaccounts and your account, and read your usage and forecast.

Token authentication

Your account API token as a Bearer header on every request. Each subaccount has its own token, so a client integration only reaches that client’s websites.

Additive-only contract

Strict additive-only API v2 contract. New features expand the schema without breaking existing integrations or automation scripts.

CI/CD ready

Take before and after screenshots around your deploy, read the change percentages, and let your script decide whether the build passes.

Pagination built in

Page-based pagination keeps long lists easy to read, from hundreds of client sites to thousands of monitored URLs.

Readable results

Read every check run and its comparisons: the change percentage per page and a public before and after link you can share.

Setup guide

Your first API integration in six steps.

Standard Bearer tokens in headers, clean JSON in and out. Fits the developer workflows your agency already has.

STEP 01

Get your token

Copy your account API token from the dashboard. If you work per client, each subaccount has its own token.

STEP 02

Make the first call

Make a simple GET /api/v2/websites request with your Bearer token. A 200 response with your websites confirms authentication is working.

STEP 03

Register a site and URLs

Create websites and groups, then add URLs one by one or from a sitemap, or sync them.

STEP 04

Take screenshots

Send POST /api/v2/screenshots/take with your group IDs and sc_type “pre” before the release, and “post” after it. The response returns a batch ID and the number of screenshots.

STEP 05

Read the results

Read the run with GET /api/v2/batches/{id} and its comparisons with GET /api/v2/comparisons, each with a change percentage and a public before and after link. Or skip polling with signed webhooks.

STEP 06

Automate on it

Fail a build when a key page changed too much, open a ticket for a regression, or send the public link to your client.

Auth & examples

Authentication and your first two calls.

Authentication is your account API token as a Bearer header on every request, no OAuth, no session handling. The dashboard shows the token and copies it with one click. Keep it secret.

curl https://api.webchangedetector.com/api/v2/websites \
  -H "Authorization: Bearer $WCD_TOKEN"

Take the after screenshots, then read the run:

curl -X POST https://api.webchangedetector.com/api/v2/screenshots/take \
  -H "Authorization: Bearer $WCD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group_ids": ["your-group-id"], "sc_type": "post"}'

curl https://api.webchangedetector.com/api/v2/batches/your-batch-id \
  -H "Authorization: Bearer $WCD_TOKEN"

Error handling follows the status codes you expect: 401 means a missing or invalid token, 402 means you do not have enough checks left, 422 means a validation problem with the request body (the response names the field), and 429 means you are sending requests faster than the rate limit allows: wait and retry. Responses are JSON in every case, including errors.

MethodEndpointWhat it does
GET · POST/api/v2/websitesList and create websites
GET · POST/api/v2/groupsManage groups of URLs and their settings
GET · POST/api/v2/urlsManage URLs, add them from a sitemap or sync them
POST/api/v2/screenshots/takeTake before (pre) or after (post) screenshots
GET/api/v2/batches/{id}Read a check run
GET/api/v2/comparisonsRead comparisons with change percentage and public link
POST/api/v2/monitoring/triggerRun Monitoring now
GET · POST/api/v2/ai-feedback-rulesManage AI Rules
GET · POST · PUT · DELETE/api/v2/webhooksCreate, update and delete webhooks
GET · POST/api/v2/subaccountsManage subaccounts and invite them
GET · PUT/api/v2/accountRead and update your account
GET/api/v2/account/statsUsage and forecast
Recipe

Automation recipe: the visual deploy gate.

Take the before screenshots before the release and the after screenshots after it, then read the change percentages. Or trigger Monitoring right after the deploy to compare with the last Monitoring screenshots. If a key page changed more than you accept, your script stops the release and posts the public before and after links to your pull request or Slack channel. Visual QA without manual spot checks, matching the workflow described in API & Automation.

FAQ

Frequently asked questions

What endpoints are available in the REST API v2?

The REST API v2 covers websites, groups, URLs (including add from sitemap and sync), before and after screenshots, check runs and comparisons, Run Monitoring now, AI Rules, webhooks, subaccounts (including invites), and your account with usage and forecast.

How does API authentication work?

Send your account API token as a Bearer header (Authorization: Bearer <token>). The dashboard shows the token and copies it with one click. Each subaccount has its own token for that client’s websites.

Are there API rate limits?

Each account can send 500 requests per minute. Run Monitoring now has its own limit of 120 requests per minute. Taking screenshots is asynchronous: the call returns right away with a batch ID, so your script never waits.

Can I integrate visual regression tests into GitHub Actions or GitLab CI?

Yes. Take the before screenshots in a cURL step before you deploy and the after screenshots after it. Your script reads the change percentages, or listens for a signed webhook, and passes or fails the build.

How do checks triggered via API consume plan credits?

API checks count like dashboard runs: one check per URL and device per run. GET /api/v2/account/stats shows your usage and forecast before you start large runs.

Does the REST API support password-protected staging environments?

Yes. Basic Auth credentials are a group setting, so every check of that group gets through. Most sites behind bot protection and firewalls are reached as well.

Catch the next visual bug before anyone else.

Start with a free trial, connect a site, and see your first before and after comparison today.