REST API

For maximum flexibility, you can interact directly with the RegressionBot REST API. All endpoints are hosted at https://api.regressionbot.com/v1.

Authentication

Provide your API key via the x-api-key header in all requests.

Start a Job

Initiate a visual regression scan. You can test a single URL, an array of paths, or automatically crawl a sitemap.

curl -X POST https://api.regressionbot.com/v1/crawl \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-web-app",
    "testOrigin": "https://preview.myapp.com",
    "baseOrigin": "https://myapp.com",
    "devices": ["Desktop Chrome"],
    "sitemapUrl": "https://preview.myapp.com/sitemap.xml",
    "scan": "**"
  }'

Check Status & Results

Poll /job/{jobId} to track progress, then fetch /job/{jobId}/summary once the job reaches COMPLETED for the full results including diff images, AI-powered [RegressionBot Summaries](/docs/regressionbot-summaries), and perceptual similarity scores.

curl https://api.regressionbot.com/v1/job/JOB_ID_HERE/summary \
  -H "x-api-key: YOUR_API_KEY"

Job Lifecycle

Jobs move through the following statuses. Poll /job/{jobId} until you see COMPLETED, APPROVED, or FAILED.

Result Fields

Each URL/device combination in the results array includes two complementary signals for understanding what changed.