Regressionbot Developer Docs

Welcome to the Regressionbot documentation. The most efficient way to use Regressionbot is via Agentic Workflows (MCP), allowing AI agents to autonomously manage your visual testing lifecycle.

v1.0.0

Recommended

Agentic Workflows (MCP)

Connect Regressionbot directly to your AI agent (Gemini, Windsurf, Cursor, or MCP in Agentic IDE). This is the optimal workflow for modern development—letting your agent run tests, interpret AI Summaries, and approve changes autonomously.

MCP in Agentic IDE / Agent Session

# Simply ask your agent to run the test
> compare my preview URL https://pr-123.myapp.com against production

# The agent uses the MCP tool to start the job
[run_regression_job] → job_7x9kLm2p
[get_job_status] → COMPLETED ✓

# The agent reviews the AI summary and decides to approve
"I found 1 intentional change: the 'Signup' button is now blue. Approving."
[approve_job] → Success.

Learn how to set up your agent in the MCP Documentation.

Node.js SDK

Integrate visual regression tests deeply into your automated test suites, scripts, or deployment pipelines using our strongly-typed Node.js SDK.

example.ts

import { Visual } from 'regressionbot';

const visual = new Visual(process.env.REGRESSIONBOT_API_KEY);

const job = await visual.test('https://preview.myapp.com')
  .against('https://myapp.com')
  .run();

await job.waitForCompletion();
const summary = await job.getSummary();
console.log(summary.overallScore);

CLI Usage

Install the CLI directly or start a test from your terminal. Regressionbot CLI makes it trivial to check an environment or hook it into CI quickly.

Terminal

# Run a quick test against your preview URL
npx regressionbot@latest https://preview.myapp.com \
  --against https://myapp.com

API Reference

Direct access to the underlying REST API that powers the SDKs, CLI, and Agentic Workflows.
Base URL: https://api.regressionbot.com

post/crawl

Start a visual regression job

Triggers a new visual regression job for a single URL or a sitemap.

Request Body

{
  "project": "string",
  "testOrigin": "string",
  "url": "string",
  "sitemapUrl": "string",
  "baseOrigin": "string",
  "devices": [
    "string"
  ],
  "paths": [
    {
      "path": "string",
      "label": "string"
    }
  ],
  "scans": [
    {
      "pattern": "string",
      "options": null
    }
  ],
  "masks": [
    "string"
  ],
  "concurrency": 0
}

Responses

200Job started successfully

{
  "message": "Visual regression job started",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

400Invalid input

500Internal server error

get/job/{jobId}

Get job status

Retrieve the current status and progress of a visual regression job.

Responses

200Job status retrieved successfully

{
  "jobId": "string",
  "status": "string",
  "progress": {
    "total": 0,
    "completed": 0,
    "percent": "50.00"
  },
  "executionTime": 0,
  "results": [
    {
      "url": "string",
      "status": "string",
      "diffCount": 0,
      "diffPercentage": 0,
      "currentKey": "string",
      "baselineKey": "string",
      "diffKey": "string",
      "regressionbotSummary": "string"
    }
  ],
  "collageKey": "string",
  "createdAt": "string"
}

404Job not found

get/job/{jobId}/summary

Get job summary with signed URLs

Retrieve a summary of the completed job, including pre-signed URLs for diff images.

Responses

200Job summary retrieved successfully

{
  "jobId": "string",
  "status": "string",
  "totalUrls": 0,
  "completedCount": 0,
  "overallScore": 98.5,
  "executionTime": 0,
  "regressionCount": 0,
  "matchCount": 0,
  "newBaselineCount": 0,
  "errorCount": 0,
  "collageUrl": "string",
  "regressions": [
    {
      "url": "string",
      "variantName": "Desktop Chrome",
      "diffCount": 0,
      "baselineUrl": "string",
      "currentUrl": "string",
      "diffUrl": "string",
      "regressionbotSummary": "string"
    }
  ],
  "matches": [
    {
      "url": "string",
      "variantName": "string",
      "baselineUrl": "string",
      "currentUrl": "string"
    }
  ],
  "newBaselines": [
    {
      "url": "string",
      "variantName": "string"
    }
  ],
  "errors": [
    {
      "url": "string",
      "errorMessage": "string"
    }
  ]
}

400Job not completed yet

404Job not found

get/job/{jobId}/collage

Generate and get regression collage

On-demand generation of a single collage image containing all detected regressions.

Responses

200Collage generated successfully

{
  "jobId": "string",
  "collageKey": "string",
  "collageUrl": "string",
  "regressionCount": 0
}

404Job not found or no regressions found

500Failed to generate collage

post/approve

Approve job baselines

Promote the current screenshots of a job to be the new baselines.

Request Body

{
  "jobId": "string"
}

Responses

200Baselines approved successfully

{
  "message": "Job baseline approved",
  "jobId": "string",
  "approvedUrlsCount": 0
}

404Job not found